CHT 4.x to 5.x Helm Charts Migration Guide

Step 1: Prepare Migration Values File

1. Export the values from your existing 4.x deployment into the migration-5x-values.yaml file:

   helm get values <your-release-name> --namespace <your-namespace> > migration-5x-values.yaml

2. Be sure all booleans are unquoted by running these two sed commands which will correct them in the migration-5x-values.yaml file:

   sed -i 's/: "false"/: false/g' migration-5x-values.yaml
   sed -i 's/: "true"/: true/g' migration-5x-values.yaml

3. Update the migration-5x-values.yaml file to be compliant with 5.x deployment requirements:

   # Change field names - keep the same true/false value from your 4.x deployment
   # Use true for multi-node deployments, false for single-node deployments
   couchdb:
     clusteredCouchEnabled: false  # was: clusteredCouch_enabled: false
   
   # For most migrations, use "preExistingDataAvailable" false. Use true for pre-created volumes for provisioning
   # For most migrations, use "dataPathOnDiskForCouchDB": "data". Double-check this is the correct path.  
   couchdb_data:
     preExistingDataAvailable: false  # Keep using dynamic storage provisioning  
     dataPathOnDiskForCouchDB: "data" # This is the path where couchdb data will be stored. Leave it as data if you don't have pre-existing data.
    # To mount to a specific subpath (If data is from an old 3.x instance for example): dataPathOnDiskForCouchDB: "storage/medic-core/couchdb/data"
    # To mount to the root of the volume: dataPathOnDiskForCouchDB: ""
    # To use the default "data" subpath, remove the subPath line entirely from values.yaml or name it "data" or use null.
   
   # Add required API service configuration
   api:
     service:
       type: ClusterIP
   
   # Upstream server configuration
   upstream_servers:
     docker_registry: "public.ecr.aws/medic" # DEFAULT: Good default
     builds_url: "https://staging.dev.medicmobile.org/_couch/builds_4" # DEFAULT: Good default
   
   # Update image versions to 5.x
   chtversion: 5.0.1
   cht_image_tag: 5.0.1

4. Depending on the hosting environment, make a final edit to migration-5x-values.yaml file:

couchdb:
  persistent_disk:
    size: <size>  # Set appropriate size for your needs

ebs:
  preExistingEBSVolumeSize: <size>  # Set appropriate size for your needs

couchdb:
  storage_class: local-path  # was: "local-storage"

Step 2: Perform the Migration

1. Upgrade the helm deployment from the same directory as migration-5x-values.yaml. As well, update /path/to/cht-core to be the location where the CHT Core repo is checked out:

   helm upgrade <your-release-name> /path/to/cht-core/scripts/build/helm \
     -f migration-5x-values.yaml \
     --namespace <your-namespace>

2. Monitor the upgrade:

   helm status <your-release-name> --namespace <your-namespace>
   kubectl get pods--namespace <your-namespace>

Step 3: Verify Migration Success

1. Check pod status:

   kubectl get pods -n <your-namespace>

2. Verify new 5.x components:

   # Look for the new couchdb-nouveau component
   kubectl get pods --namespace <your-namespace> | grep nouveau

3. Test data integrity

4. Test application access