Bitnami to Bitnami Legacy Migration Rule Book

1. Overview

This rule book provides a systematic approach for migrating Bitnami Helm charts and container images from the bitnami repository to the bitnamilegacy repository.
This migration is necessary due to Bitnami's transition effective August 28th, 2025, where existing images will be moved to the legacy repository.

2. Background

• Effective Date: August 28th, 2025
• Impact: All existing Bitnami container images will be moved from docker.io/bitnami to docker.io/bitnamilegacy.
• Helm Charts: Will continue to work but require image repository updates.
• Legacy Repository: Receives no further updates and should only be used as a temporary migration step.

3. Migration Prerequisites

• Access to Kubernetes clusters (staging, sandbox, production).
• Terraform access with appropriate permissions.
• Helm CLI installed and configured.
• kubectl access to target clusters.
• Communication with stakeholders regarding downtime or risks.

4. Migration Process

Phase 1: Discovery and Assessment

1. Identify Bitnami Charts

   helm list -A
   helm repo list | grep bitnami
   

2. Inventory Current Deployments
   • Chart names and versions
   • Namespaces
   • Current status
   • Dependencies
3. Check Terraform Configuration

   find . -name "*.tf" -exec grep -l "bitnami" {} \;
   grep -r "bitnami" ./terraform/ --include="*.tf" -n
   

Phase 2: Planning

1. Create Migration Plan
   For each identified component:

   • Current chart version
   • Target migration approach (image override vs. chart upgrade)
   • Dependencies and order of operations
   • Rollback procedures

2. Chart Verification
   Before migration, verify that the chart exists in the Bitnami Legacy repository:

   helm search repo bitnamilegacy/<chart-name>
   

   If the chart does not exist, do not proceed and raise an issue with the DevOps team.

Phase 3: Implementation

1. Terraform Configuration Updates

   • Update image references from bitnami → bitnamilegacy.
   • If required, allow insecure images:

     global:
       security:
         allowInsecureImages: true
     

2. Handle StatefulSet Restrictions
   StatefulSets restrict updates on certain fields.
   If you encounter errors such as:

   updates to statefulset spec for fields other than 'replicas'... are forbidden
   

   Solution: uninstall and reinstall the Helm chart, then reapply Terraform.

3. Terraform Execution Steps

   cd terraform && terraform fmt -recursive
   cd terraform/environments/<environment>/20_platform
   terraform init
   terraform plan
   terraform apply -auto-approve
   

Phase 4: Validation

1. Verify Helm Deployments

   helm list -A
   kubectl get all -n <namespace>
   

2. Functional Testing
   • Verify application integrations
   • Monitor logs for errors
3. Image Verification

   kubectl describe pod <pod-name> -n <namespace> | grep Image
   

Phase 5: Documentation and Cleanup

1. Update Documentation
   • Record migration completion dates
   • Update deployment documentation
   • Note configuration changes
2. Monitor Post-Migration
   • Monitor for 24–48 hours
   • Check for performance issues
   • Validate image pulls

5. Common Issues and Solutions

• Issue 1: StatefulSet Update Restrictions
  Symptom: Cannot update StatefulSet spec fields.
  Solution: Uninstall and reinstall chart, then reapply configuration.

• Issue 2: Image Pull Errors
  Symptom: Pods fail with image pull errors.
  Solution: Verify allowInsecureImages: true is set globally.

• Issue 3: Configuration Drift
  Symptom: Terraform shows unexpected changes.
  Solution: Run terraform fmt -recursive and confirm all overrides are correct.

6. Security Considerations

• allowInsecureImages is required for Bitnami Legacy but should be monitored.
• Implement image vulnerability scanning.
• Plan for migration away from Legacy images long-term.

7. Rollback Procedures

• Immediate Rollback: Revert Terraform configuration to the previous version.
• Helm Rollback:

  helm rollback <release> <revision> -n <namespace>
  

• Emergency: Switch back to bitnami repository (if still available).

8. Timeline Recommendations

• Pre-August 28th, 2025: Complete staging and sandbox migrations.
• August 28th, 2025: Execute production migration.
• Post-Migration: Monitor for one week, then plan a long-term strategy.

9. Long-term Strategy

Since the Bitnami Legacy repository is temporary, consider:

• Bitnami Secure Images for supported production workloads.
• Alternative chart providers.
• Building and maintaining your own container images.

10. Migration Checklist

Pre-Migration

• Inventory all Bitnami deployments
• Document current versions and configurations
• Test migration process in staging
• Prepare rollback procedures

Migration Execution

• Update Terraform configurations
• Apply changes to staging environment
• Validate staging deployment
• Apply to sandbox, validate deployment
• Apply to production, validate deployment

Post-Migration

• Verify all services are functional
• Monitor for 24–48 hours
• Update documentation
• Define long-term strategy