Helm Operations and Argo CD Migrations

Moving static Kubernetes manifests into Helm and then into Argo CD is a change in ownership as well as templating. Inventory the live resources, preserve immutable names and storage, and make the desired state reproducible before turning on automated pruning.

Understand Helm’s Release Model #

For a direct Helm release, an upgrade compares the previous release manifest, the newly rendered manifest, and the live object. Resources present in both manifests are updated when their fields permit it; resources only in the new manifest are created; resources removed from the chart are normally deleted. Immutable fields can require an explicit replacement strategy.

helm upgrade --install web ./chart \
  --namespace web --create-namespace \
  --values environments/production.yaml \
  --dry-run --debug

Use helm diff when it is available in the established toolchain, and inspect helm get manifest and helm history after an upgrade. The helm.sh/resource-policy: keep annotation can retain a resource during uninstall, but it should be a deliberate lifecycle decision, not a general safeguard.

Migrate Static Manifests Incrementally #

First, capture the actual desired specification from source control and compare it with the live object. Parameterize genuine environment differences—image version, hostname, resource limits, storage class—rather than every field. Render the chart and compare it to the existing resources.

Keep stable metadata.name, namespace, selectors, and persistent-volume claim names during the first migration. Changing a selector can strand pods; changing a PVC name creates a new claim and does not move data. For stateful workloads, rehearse backup, restore, and rollback procedures in a non-production cluster before any ownership transition.

Hand Off to Argo CD Safely #

When Argo CD renders a Helm chart, avoid running a separate helm upgrade against the same resources. Configure the Application, verify the rendered manifests and diff, synchronize without pruning first, then enable pruning only after the application is healthy and no unrelated resources are in scope.

For a resource rename or a dependency graph with deletion guards, use a staged migration:

1. add the new resource while retaining the old one;
2. update consumers and wait for health checks;
3. remove old dependents;
4. remove the old parent resource in a later synchronization.

Argo CD sync waves can order an ordinary apply and prune sequence, but a staged change is clearer when data migration, admission webhooks, or external clients are involved.