Adopting existing Helm releases into Argo CD

Adopting existing Helm releases into Argo CD without a service outage

Adopting an existing Helm release into Argo CD is a planned cutover for each release, not a single switch across the cluster. Effort depends on two things: how many releases were installed with helm install or from CI, and how many of them use Helm hooks or set custom instance labels. A small set of plain releases can move in a few controlled steps. A platform with many charts, each with its own hooks and label conventions, needs an inventory and an agreed order of moves before anyone changes a manifest. Count the releases per namespace, and flag any chart that relies on hooks, because hooks behave differently once Argo CD controls the sync.

The old release records stop being the source of truth because Argo CD renders charts itself with helm template and then manages the resulting objects through its own lifecycle. Applications it deploys do not appear in helm list, so a release that still shows up in Helm can drift from what Argo CD applies. A later helm upgrade run from a laptop or CI job would then overwrite changes that were made through Git. Read the Argo CD Helm guide before the first move, since it explains how the release name and labels map onto the resources Argo CD creates.

Two settings decide whether a move causes an outage. First, the release name must match what existing selectors and the app.kubernetes.io/instance label expect, because overriding releaseName can break selectors that rely on that label. If the name cannot stay the same, the Helm guide suggests changing application.instanceLabelKey in argocd-cm, but first confirm which Services, NetworkPolicies and monitors select on that label. Second, if another tool sets the same instance label, the Argo CD FAQ notes that the application can stay OutOfSync after syncing and suggests argocd.argoproj.io/instance as the key. Test both changes in a non-production cluster, and keep the old release in place until the Argo CD application reports healthy and in sync.

Which Helm release concepts map to Argo CD and which do not

This table compares the Helm release concepts your team relies on today with their Argo CD equivalents, and flags where a decision is required before cutover. Read each row against the chart you plan to adopt, paying most attention to rows marked with a decision. The main takeaway is that Argo CD takes over lifecycle management, so release names, labels and hooks must be settled before the first sync.

Helm concept	Argo CD equivalent	What to decide or confirm
Release name	Application name and the release name passed to helm template	Keep the existing release name if possible. Overriding it can break selectors that depend on app.kubernetes.io/instance.
Values files and overrides	Helm parameters, values files or valueFiles in the Application source	Move every value into Git. Confirm that the rendered output matches the live objects before the first sync.
Revision history	Git commit history and Application sync history	Helm revision records stay behind in the cluster. Decide whether you need them as evidence before removing them.
Release Secrets (sh.helm.release.v1)	No equivalent. Argo CD does not read or write them	Plan removal of old release records after adoption. Confirm that no other tool depends on them.
Instance labels (app.kubernetes.io/instance)	Tracking label set by application.instanceLabelKey or annotation-based tracking	If another tool sets the same label, the Application can stay OutOfSync. Choose a dedicated label key and set it in argocd-cm.
Helm hooks (pre-install, post-upgrade and similar)	Argo CD hooks and sync waves, mapped from Helm hook annotations	Review each hook. Hooks that run on every sync or assume Helm lifecycle semantics may behave differently. Test on a non-production cluster.
helm list output	Application list in the Argo CD UI, CLI or API	Argo CD-managed charts no longer appear in helm list. Update runbooks and monitoring that depend on that command.
helm upgrade and rollback	Git revert, a new commit and an Argo CD sync	Rollback becomes a Git operation. Confirm the team agrees on the process before cutover.

How instance label collisions cause OutOfSync after adoption

Adoption fails quietly when the app.kubernetes.io/instance label means different things to Helm, Argo CD and other tools in the same cluster. The two documented failure modes below look different in practice, but both come from one label being read by more than one owner.

Release name changes break selectors

If you keep the Helm release name unchanged when moving to Argo CD, nothing changes for the label. If you override releaseName in the Application to match an existing name, the rendered app.kubernetes.io/instance value can change, and Services, NetworkPolicies or PodDisruptionBudgets that select on the old value stop matching pods. Check every selector in the chart and in neighboring manifests before the first sync.

Another tool sets the same label

Some operators, sidecar injectors and older deployment scripts also write app.kubernetes.io/instance. After Argo CD syncs, the live object carries a value Argo CD did not render, so the application reports OutOfSync even though nothing is wrong with the chart. List the resources that show drift and check their metadata.labels for a second writer before you assume the chart is at fault.

Switch the tracking label key

The documented fix is to set application.instanceLabelKey to argocd.argoproj.io/instance in the argocd-cm ConfigMap, which moves Argo CD's ownership marker off the shared label. Treat this as a cluster-wide setting: it changes how Argo CD tracks every application on that installation, so plan it as a deliberate change rather than a per-chart fix.

Verify before changing a live installation

Before editing argocd-cm on a running instance, record which applications show drift and why, and confirm no other controller reads the old key. Check how existing applications will be re-tracked after the change, and test the new key on a non-production instance with a copy of the same charts. Keep the previous ConfigMap so you can restore it if drift or pruning behavior changes unexpectedly.

Confirm the label owner in each cluster

Ownership of app.kubernetes.io/instance is often unclear in clusters where platform teams, operators and Argo CD all touch the same namespaces. Ask each team which tool writes the label, and record the answer with the application inventory. The adoption plan should name one owner per namespace before any release is moved, or the same drift will return after the next sync.

Choosing an adoption path for each release

Some releases can move under Argo CD with little more than a new Application that points at the same chart and values. This path fits when the release name and the labels the chart applies already match what the Application will render, so existing selectors keep matching the objects they select. The trade-off is speed against false confidence, because a match in the manifests can still differ from the live objects in the cluster.

Release name is unchanged: the Application's release name equals the existing Helm release name, so generated names and selectors stay the same.
Instance label is unchanged: the app.kubernetes.io/instance value on live objects equals the value Argo CD will render.
Values are recovered: the values used at install are taken from the release record or the original source, and the team checks them against the live configuration.
Only one tool reconciles: no Helm upgrade job, CI step or engineer's shell still runs helm upgrade against the release.

Confirm these points with a diff of rendered output against live objects in a non-production namespace before you choose this path.

Sequence for moving one Helm release to Argo CD

This sequence moves one Helm release under Argo CD ownership in a controlled order, so each release is inventoried, proven in a non-production cluster, cut over once, and cleaned up only after Argo CD owns its objects. The output is a per-release record showing that the rendered manifests match the live objects and that Argo CD reports the expected state.

Inventory each release and its values
Your platform team lists every release in scope with helm list across the target namespaces, then records the chart name and version, the release name, the namespace, the user-supplied values (helm get values), and any hooks or CRDs the chart installs. Chart source, values files and any post-render changes are stored in Git before anything else changes. Done when each release has a written entry in the migration backlog and its values exist in version control.
Render the chart with helm template
An engineer runs helm template with the same chart version and the recorded values, and writes the output to a file. The rendered manifests are then compared with the live objects (for example with kubectl get -o yaml and a diff tool) to find fields that differ, such as generated labels, random passwords or hook resources. Done when every difference is either explained and accepted or fixed in the values, and the team has a list of labels Argo CD will need to match.
Pick the instance label and release name
Before writing the Application, the team checks whether the release name or chart labels use app.kubernetes.io/instance, and whether another tool already sets that label on the same objects. If there is a conflict, the team plans to set application.instanceLabelKey in argocd-cm to a dedicated key so Argo CD does not clash with existing selectors. Done when the chosen label key and release name are written down and checked against the rendered output.
Create the Application in a non-production cluster
An engineer creates an Argo CD Application in a non-production cluster that points at the chart source and the same values used by the Helm release, with the target namespace set to the existing one. Sync is kept manual at first so the team reviews what Argo CD plans to change. Done when the Application exists in Argo CD and the first comparison runs without errors.
Confirm Argo CD reports the expected state
In the non-production cluster, the team checks that the Application reports Synced and Healthy against the live objects, and that a sync produces no unexpected deletions or recreations of Deployments, Services or Secrets. A pre-sync diff and a second sync should show no changes. Done when the team has a signed-off result for that release, and any OutOfSync drift has been traced to a cause and resolved.
Cut over the release in production
The team repeats the same Application setup in production during an agreed change window, with a rollback note that records the Helm revision number and the values file. Argo CD takes over management of the objects, and the team confirms the workloads still serve traffic and that Argo CD reports the Application as Synced and Healthy. Done when the production Application is healthy and no helm upgrade is run against the release afterward.
Remove the old Helm release records
Once Argo CD owns the objects for a release and has run cleanly for an agreed period, the team removes the Helm release record Secrets that Helm keeps in the namespace, so helm list no longer treats the release as active. The exact commands and the Secret naming must be confirmed against your Helm version and the documented procedure before running them, and a backup of the Secrets is kept. Done when helm list no longer shows the release and the Argo CD Application still reports Synced and Healthy.

What happens to Helm hooks after adoption

Argo CD does not run helm install or helm upgrade for an adopted chart. It renders the chart with helm template and applies the output itself, so hook resources in that output are handled by Argo CD's sync engine instead of Helm's release lifecycle. Argo CD maps the common Helm hook annotations onto its own phases: hooks that run before install or upgrade become PreSync work, hooks that run after become PostSync work, and deletion hooks run when the application is removed. Hook weights carry over as sync waves, which set the order in which hooks and ordinary resources are applied. The Helm guide describes this mapping, but confirm the supported annotations against the Argo CD release you run before you rely on them.

The first sync after adoption is where hook behavior matters most. A pre-upgrade Job that Helm ran only during an upgrade will run on Argo CD's first sync, and it will run again on every later sync, including automated syncs if you enable them. Review every hook before that first sync and ask four questions: is the Job idempotent, does it depend on resources the old release created, does it assume Helm's release records or revision history, and what happens if it fails partway through. Some Helm behavior has no direct equivalent. Do not assume rollback and test hooks behave as they did under Helm. Any hook that relied on Helm's rollback or release history needs a replacement plan, such as a separate runbook or an explicitly ordered sync-phase Job.

Test hooks in a non-production cluster that matches production in chart version, values file and namespace layout. Render the chart with helm template using the production values, then run argocd app diff and a manual sync with auto-sync disabled. Watch which hooks run, in what order, and whether their Job objects are cleaned up according to the delete policy you set. Set argocd.argoproj.io/hook-delete-policy explicitly where cleanup matters, so completed Jobs neither pile up nor disappear before you read their logs. Enable automated sync for the adopted application only after one full upgrade cycle passes without hook surprises.

What drives the effort of adopting Helm releases

This table lists the factors that change how much work it takes to move a Helm release under Argo CD, who does each piece, and whether the work happens once or keeps recurring. Read it before asking for a quote, because each row maps to a question the partner should answer in writing. The main takeaway is that release count and hook, CRD and secret handling usually matter more than the chart install itself.

Driver	Why it changes effort	Who does the work and one-time or recurring
Number of releases	Each release needs its own Application, sync check and cutover window, so effort grows with the release list.	Platform team inventories releases once. Partner or internal team repeats the cutover per release. One-time.
Custom release names	A release name other than the Application name can break selectors that rely on the app.kubernetes.io/instance label, so names must be matched or relabeled.	Platform engineers decide the naming plan once. Chart values or label keys may need editing per chart. One-time.
Reliance on instance labels	Other tools or selectors using app.kubernetes.io/instance can leave an Application OutOfSync, which may require changing application.instanceLabelKey.	Platform team audits selectors across the cluster. Config change is one-time, but new charts must keep the same rule. Recurring review.
Hook count and type	Helm hooks such as pre-install or post-upgrade jobs map to Argo CD sync hooks, and their behavior after adoption must be tested.	Chart owners and the adopting team test each hook. One-time per chart, repeated after chart upgrades.
CRDs managed by charts	CRDs have cluster-wide scope and lifecycle rules, so ownership and upgrade order must be decided before Argo CD syncs them.	Platform team decides ownership once. Each chart upgrade that changes CRDs needs a fresh check. Mostly recurring.
Values stored outside Git	Values set with --set, values files on a workstation or values in release history must be captured in Git before sync is trusted.	Adopting team extracts values with helm get values and commits them. One-time, then ongoing if people still edit values by hand.
Secrets handling	Secrets rendered by charts or passed as values must move to a method that keeps them out of Git and out of cached manifests.	Security and platform teams choose the method. Secret migration is one-time, while rotation and new charts recur.
Number of clusters	Each cluster has its own release records, RBAC, cluster registration and cutover, so effort repeats per cluster.	Platform team registers clusters and repeats the checks per cluster. Registration is one-time, verification recurs with each new cluster.
Old Helm release records	Removing release Secrets or history after adoption is irreversible, so it needs a backup and a sign-off step.	Platform team removes records after verification. One-time per release, with backup retained by the client.

What usually goes wrong during Helm adoption

Adopting a Helm release into Argo CD fails in a small number of predictable ways. Each failure below comes from the same underlying issue: two systems believe they own the same objects, or the identifiers that tie objects together change during the move.

Double reconciliation during cutover

If Helm and Argo CD both keep applying the same objects, each tool reverts the other's changes on its own schedule, and the cluster state flips back and forth. Before the first sync, stop any pipeline or operator that runs helm upgrade against the release. Then confirm that only one controller reports the application as managed. Check the live objects for drift after the first sync rather than assuming the cutover was clean.

Changed release name breaks selectors

Argo CD renders the chart with the release name you give it, so a different name changes generated labels and selector values. A Service or Deployment selector that points at the old instance label can stop matching pods, which drops traffic without any error from Argo CD. Keep the release name identical where possible. If it must change, set application.instanceLabelKey in argocd-cm as the Helm guide describes, and verify that every selector still resolves before sync.

Hooks running during first sync

Helm hook annotations such as pre-install or post-upgrade are handled differently once Argo CD renders the chart. A hook that Helm already ran may execute again, for example a database migration Job or a seed task. Review every hook in the chart output with helm template before adoption, and decide whether each one should run, be skipped or be converted to an Argo CD sync hook. Confirm this in a non-production cluster first.

Orphaned Helm release records

After adoption, helm list no longer shows the release, but the Secrets Helm uses to store release history can remain in the namespace. Operators then see a release that appears installed in one tool and managed in another, which slows incident response and invites a stray helm upgrade. Record the release revision before cutover, remove the stored release records only after Argo CD reports healthy status, and document who may run Helm against that namespace.

Values drift from Git

The values a team used with helm install often exist only in the command history, a local file or a previous release revision. If the Argo CD Application points at a values file that differs from the live release, the first sync changes running workloads to match Git. Export the deployed values with helm get values, diff them against the values in your config repository, and resolve each difference before enabling automated sync.

Questions teams ask before adopting Helm releases into Argo CD

Can our own team adopt existing Helm releases into Argo CD without a partner?

Yes, if your team already runs Argo CD and has someone who knows how the existing charts, values files and release history fit together. The work is mostly inventory and verification: confirming each release's chart version, values, namespace and labels, then creating Applications that render the same manifests. Teams without Kubernetes and Helm depth often find the careful part is not the sync itself but proving that the first Argo CD sync changes nothing unexpected. A partner's value is usually that second check, run across many releases on a fixed scope agreed in writing before work starts.

What drives the cost and time of adopting Helm releases?

The main drivers are the number of releases, how much each one differs from its chart defaults, and how many environments and clusters they span. Releases with hand-edited values, custom hooks, or resources created outside the chart take longer to reconcile. Shared label conventions across tools and any change-window restrictions also add time. Cost follows the same pattern: one-time effort for inventory, mapping and cutover, plus any ongoing support you choose to retain afterward. Ask for a quote that lists releases, clusters, environments and the verification steps per release.

What must we provide before adoption work starts?

Prepare the inputs that determine whether the first sync is safe:

The exact chart name, repository and version for each release, plus the output of helm get values and helm get manifest.
Current release names, namespaces and the labels already applied to running resources.
Read access to the target clusters and a Git repository where the Application definitions will live.
Agreed change windows, rollback owners and a list of releases that cannot be touched during business hours.

Missing any of these usually stretches the schedule more than the technical work itself.

Can we adopt a Helm release into Argo CD without downtime?

Downtime is avoidable in most cases because adoption can keep the same Kubernetes objects and only change which tool manages them. The risk comes from mismatches: a different release name that changes resource names, a label selector that no longer matches, or a hook that runs again during the first sync. Teams usually stage this by namespace, compare rendered output before the first sync, and keep a rollback path. Confirm the approach against the official Argo CD Helm guide and test it on a non-production cluster first.

Why does helm list stop showing releases after adoption?

Argo CD renders charts with helm template and manages the resulting objects itself, so it does not create Helm release records. Once an application is managed by Argo CD, helm list no longer reports it, even though the workloads keep running. That is expected behavior, not a sign of failure. Before cutover, record each release's current revision and values so you have a reference. After cutover, decide whether to remove the old Helm release records, and confirm that no other pipeline still runs helm upgrade against them.

Why does an adopted application stay OutOfSync or select the wrong pods?

The two common causes are label collisions and overridden release names. If another tool sets the app.kubernetes.io/instance label, Argo CD may keep reporting OutOfSync after a successful sync. Changing the release name can also break selectors that rely on that label. The Argo CD documentation describes setting application.instanceLabelKey in argocd-cm to avoid these conflicts, and the FAQ suggests argocd.argoproj.io/instance as the alternative key. Decide the label strategy before the first sync, because changing it later touches resources across the cluster.

How do Helm hooks behave after a release moves under Argo CD?

Argo CD maps Helm hooks to its own sync phases instead of running them the way the Helm CLI does, so the same hook can fire at a different point or more often than before. Pre-install and post-install jobs, such as database migrations, are the most sensitive. Review every hook in the chart, decide whether it should run on each sync, and confirm its delete policy. Verify this with a test release in a non-production environment before adopting anything that runs data changes.

What should we confirm about access, secrets and repository setup?

Confirm who can change Application definitions, where Helm values files are stored, and how secrets reach the cluster. Values files that contain credentials should not be committed to Git in plain text, and the repo-server runs Helm on repository content, so the source repositories need the same trust controls as production code. Also confirm the Argo CD version, because repository configuration moved to Kubernetes Secrets in version 3.0. Ask your team or partner to document these choices before any release is moved.

Who owns the process after adoption is complete?

Your team owns the resulting Applications, Git repositories and Argo CD configuration, whether the adoption was done in-house or with a partner. Recurring work includes upgrading Argo CD within supported minor versions, updating chart versions through pull requests, and reviewing sync failures. If you want outside help after cutover, that is usually set up as a separate retainer with its own written scope. Ask for a handover that names the Git paths, the owners of each application and the runbook for rollback.

How DeployOpen scopes and delivers Helm to Argo CD adoption

DeployOpen approaches adoption of existing Helm releases as a fixed-scope engagement inside your own clusters and infrastructure. We start from an inventory of what is installed today, then agree in writing how each release moves under Argo CD without a service interruption.

How we scope

We inventory each Helm release, its chart version, values sources and the cluster and namespace it runs in.
The written scope lists which releases move, which stay on Helm, and which labels and release names must be preserved.
We agree in writing how instance label handling, hook behavior and old release record cleanup will be verified before work starts.

How we build

We prepare Application manifests that render the same chart and values, then compare the rendered output against the live objects.
We test the instance label choice in a non-production cluster and confirm the application reaches Synced and Healthy without changes.
We document each cutover step per release, including the order of Helm record removal and the rollback steps if a comparison fails.

How we hand over

You receive the Application manifests, the verification checklist and the record of each release that was adopted.
The handover explains how to keep Git as the source of change, how to add new charts, and how to retire any remaining Helm workflows.
Runbooks cover the checks to run after a cluster change so that drift from the Git definitions is found early.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the adoption work is complete.
Retainer scope is agreed in writing, so you can confirm which Argo CD upgrades and chart updates are covered.
Ask for a quote based on the written scope. Cost depends on the number of releases, cluster count and how much hook logic must be reviewed.

Adopting existing Helm releases into Argo CD