Helm Charts 4x to 5x Migration

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

Overview

This guide covers the migration of Kubernetes based CHT 4.x deployments using the legacy Helm charts to the new charts introduced in CHT 5.x. The new Helm chart require updates to your values.yaml file.

Before starting be sure you have a git clone of the CHT Core repository and that you have updated it with git pull origin to ensure you have the latest changes locally.

Migration Steps

Step 1: Prepare Migration Values File

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

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
```

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 false. Use true for pre-created volumes for provisioning
couchdb_data:
  preExistingDataAvailable: false  # Keep using dynamic storage provisioning  

# Add required API service configuration
api:
  service:
    type: ClusterIP

# Update image versions to 5.x
chtversion: 5.0.0
cht_image_tag: 5.0.0

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

Upgrade the helm deployment form same directory as migration-5x-values.yaml. As well, update /path/to/cht-core to be the location where 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>
```

Monitor the upgrade:

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

Step 3: Verify Migration Success

Check pod status:
```
kubectl get pods -n <your-namespace>
```

Verify new 5.x components:

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

Test data integrity
Test application access

Best Practices

Test First: Always test migrations in a non-production environment
Backup Data: Ensure complete data backup before migration
Monitor Closely: Watch deployment logs and metrics during migration
Document Changes: Keep track of any custom configurations
Plan Downtime: Schedule migrations during maintenance windows

Breaking Changes Reference

Change Type	Old (4.x)	New (5.x)	Platform	Impact
Field Rename	`clusteredCouch_enabled`	`couchdb.clusteredCouchEnabled`	All	Critical
Field Rename	`local.diskPath`	`local_storage.preExistingDiskPath-1`	All	Critical
New Field	-	`api.service.type: ClusterIP`	All	Critical
Storage Config	Default sizes	`couchdb.couchdb_node_storage_size` required	All	Critical
Storage Config	Default sizes	`couchdb.persistent_disk.size` required	GKE	Critical
Storage Config	Default sizes	`ebs.preExistingEBSVolumeSize` required	EKS	Critical
Storage Class	`local-storage`	`local-path`	K3s-K3d	Minor
Structure	Flat config	Nested couchdb configuration	All	Medium

Getting Help

If you encounter issues during migration:

Check the CHT Documentation
Review the CHT Forum
Open an issue in the CHT Core Repository

Last updated on October 23, 2025

Did this documentation help you ?

Preparing to upgrade to CHT 4.0