How to move Argo CD to a new management cluster without double reconciliation
The safe way to move Argo CD to a new management cluster is to treat it as a controlled handover: export the current state, import it into an Argo CD of the same version on the new cluster, re-register every destination cluster and repository, and switch DNS and ownership in one step. The main risk is not the copy itself but the window where both instances can reconcile the same applications. Before anything is imported, decide which instance owns each application, and plan to stop the old one from syncing before the new one starts. Run argocd admin export from the quay.io/argoproj/argocd image that matches the running server version, and do not assume the export succeeded just because it finished. The disaster recovery guide notes that export does not report an error when pointed at the wrong namespace, so confirm the namespace and the object counts before you rely on the file.
Version matching is the first technical gate. The new instance should run the same Argo CD minor version as the source, and the import image must match it too. Upgrading during the move doubles the variables if something fails, so keep the upgrade as a separate, later step. Repositories need particular care: since Argo CD 3.0, repository definitions live in Kubernetes Secrets rather than in argocd-cm, so check that every repository credential exists as a Secret in the new namespace before syncing. Confirm the SSO and RBAC settings too, because the Dex claim used for RBAC changed to federated_claims.user_id in 3.0. Cluster registrations and their credentials are not something to copy blindly from the export; re-register each destination cluster with credentials that the new management cluster is allowed to use, and check that the old cluster secrets are removed or disabled afterward.
The cutover itself should be sequenced. Pause automated sync on the old instance, disable its controllers or scale them to zero, confirm no application is still syncing, then start the new instance and switch the DNS name or ingress that users and webhooks call. Webhook endpoints in Git hosts and CI systems often point at the old address, so update them in the same window. Verify that each application shows the expected source, destination and health on the new instance, and that a test change to a non-critical application produces one sync event. Plan rollback before you start: keep the old instance and its state intact until the new instance has run through a full sync cycle. Effort depends on how many applications, clusters and repositories are in scope, and on how many teams must approve the change window. Ask any implementation partner to quote from a written inventory of those three counts, and to name who runs the cutover and who signs off on it.
What maps cleanly from the old Argo CD and what needs rebuilding
This table compares each Argo CD object or setting on the old management cluster with its equivalent on the new one, and marks whether it can be exported and imported or must be recreated. Use it as a checklist during planning, then verify each row against your own export before cutover. The main takeaway is that Git-held definitions move with little change, while credentials, identity links and anything kept outside Argo CD must be re-established on the destination.
| Item | On the new cluster | Migration notes |
|---|---|---|
| Applications | Application objects reapplied from Git or restored from an admin export | Confirm each Application's source repository, path and destination match the new cluster's name and server URL before any sync is enabled. |
| AppProjects | AppProject objects in the Argo CD namespace | Review source repo allow lists and destination rules, since they reference repositories and clusters that must be re-registered first. |
| Repository secrets | Repository credentials stored as Kubernetes Secrets with the repository label | On 3.0 and later, repositories must be Secrets, not entries in argocd-cm. Re-create deploy keys, tokens or GitHub App credentials, since they are not portable from the old cluster. |
| Cluster secrets | Cluster registration Secrets for each managed cluster | Destination clusters must be re-registered with credentials issued for the new management cluster. Check that the cluster service account and its RBAC are still valid. |
| RBAC and SSO settings | argocd-rbac-cm and argocd-cm entries, plus Dex or OIDC configuration | Re-create the OIDC client or connector redirect URIs for the new hostname. Confirm group claims and the federated_claims.user_id mapping used by Dex RBAC on 3.0 and later. |
| Local admin user | Admin account with admin.enabled set to false once SSO works | Keep the admin account only for initial setup, then disable it. Store its recovery procedure outside the cluster before disabling. |
| Notifications | Notification ConfigMap, triggers, templates and subscriptions | Notification secrets such as chat webhook tokens and email credentials must be re-entered. Test each trigger against a non-production target first. |
| ApplicationSets | ApplicationSet objects and their generator inputs | Generators that read cluster or Git state will regenerate Applications on arrival. Pause them until ownership of generated Applications is confirmed to avoid unexpected creates or deletes. |
| Argo CD version | Same minor version as the old instance, or a planned upgrade on the destination | Use the export tool from the image matching the source version. Consult the upgrade notes for any version change, and confirm the target release line is still patched. |
| Secrets outside Argo CD | Secrets consumed by workloads, plugins and external secret operators | These are not Argo CD objects and are not moved by an Argo CD export. Re-establish them on the destination and confirm each consumer reads from the new source. |
Documented export and import paths for Argo CD state
Argo CD keeps most of its state in Kubernetes objects, so a move to a new management cluster depends on which objects you export, which you recreate from Git, and which you deliberately leave behind. The cards below separate the official export and import path from the GitOps path and the checks that catch silent mistakes.
Official export and import commands
The argocd admin export command writes Argo CD configuration and resources to a file, and argocd admin import restores them. The documented procedure runs both from the quay.io/argoproj/argocd image whose tag matches the running server version, so the tooling and the data format agree. Confirm the exact version of the source server before you start, and pin the same tag on the destination. Follow the official disaster recovery guide for the full sequence rather than improvising from memory.
Verify the namespace before exporting
Export does not report an error when it runs against the wrong namespace. A command pointed at an empty or incorrect namespace can finish successfully and write an output file with little or nothing in it. Before you trust a backup, check the namespace the Argo CD installation actually uses, count the Applications, AppProjects and repository Secrets in the export file, and compare those counts with kubectl get results from the source cluster. Store the verified file outside the cluster.
Kubernetes objects that define state
Argo CD state lives in ordinary Kubernetes objects: Application and AppProject custom resources, ApplicationSets, ConfigMaps such as argocd-cm and argocd-rbac-cm, and Secrets for repository, cluster and SSO credentials. Redis holds only disposable cache data and does not need to move. Build an inventory of these kinds on the source cluster so you know what the export must cover and what you must recreate by hand, including anything added outside Argo CD, such as custom resource health checks or notification settings.
Recreating Applications from Git
If your Applications and projects are declared in a Git repository, the GitOps path is often cleaner than restoring old objects. Apply the root Application or AppProject manifests with kubectl apply against the new cluster, then let Argo CD reconcile the rest. This path keeps an auditable change history, but it only works for definitions that were actually committed. Compare the live Applications on the source cluster with the manifests in Git and treat any difference as state you must capture before cutover.
Kubectl restore for selected objects
For a targeted move, you can export specific resources with kubectl get and apply them to the destination. Strip cluster-specific fields such as resourceVersion, uid and status before applying. This works for a handful of Applications or projects, but it does not restore everything Argo CD stores. Use it to fill gaps after the official import, not as a replacement for it, and check each restored object against the source cluster.
Secrets and credentials need separate handling
Repository credentials, cluster credentials and SSO client secrets are stored as Kubernetes Secrets, and Argo CD redacts them from API responses and logs. Confirm with your security team whether the export file contains these values, where it is stored, who can read it and how long it is kept. Restore credentials from your approved secrets source where possible rather than copying plaintext files between clusters, and record each credential that was re-issued so access can be reviewed later.
Sequence for inventory, parallel run, cutover and decommission
This sequence moves Argo CD to a new management cluster while every application keeps exactly one controller reconciling it at any point, so the move can be verified and reversed before the old instance is retired.
Inventory clusters, repositories, projects and SSO
The platform owner and the Argo CD administrators list every registered cluster, every repository credential, every AppProject with its source and destination rules, every Application and ApplicationSet, and the SSO and RBAC configuration on the source instance. Record the exact Argo CD version and the namespace it runs in, since the export and import tooling must match the server version. The step is done when the inventory is reviewed by the owning teams and each Application has a named owner and a target cluster. Confirm any credential that cannot be exported, such as cloud-issued cluster tokens, with the cloud provider and your security team before the build starts.
Build the destination at the source version
Install Argo CD on the new management cluster at the same version as the source, using the same installation method and the high availability layout you have chosen. Keep the version identical during the move and defer any upgrade to a separate change, so that export and import behave as tested. Check that the new cluster has enough nodes for the HA manifests, which need at least three nodes because of pod anti-affinity rules. The step is complete when the destination API server, repo-server and controllers report healthy and admin access is confirmed through a method other than the source instance.
Pilot on a non-production application set
Choose one non-production set of Applications that has a clear owner and a simple dependency graph. Re-create its project, repository secret and cluster registration on the destination, and move only that set using the export and import steps that follow. Confirm that the destination reports the expected sync state, that resources in the target cluster are unchanged, and that the owner can sign in and perform the actions their role allows. The pilot is done when the owner signs off in writing and the rollback steps have been rehearsed on the same set.
Export settings and import them to the destination
Run the argocd admin export command from the quay.io/argoproj/argocd image that matches the source server version, and save the output to a location that the source and destination teams can both review. Import the file on the destination with argocd admin import using the same image version. Because export does not report an error when pointed at the wrong namespace, check the namespace flag and compare object counts for Applications, AppProjects and repository Secrets against the inventory. The step is done when the counts match the inventory and the imported objects are visible on the destination.
Re-register clusters and repositories
Register each destination cluster with the credentials appropriate for the new environment, and confirm that repositories are defined as Kubernetes Secrets, since repository configuration in argocd-cm was removed in Argo CD 3.0. Rotate or re-issue any credential that was stored in a form that should not be copied between instances. Test each repository connection and each cluster connection from the destination. The step is complete when every cluster and repository shows a successful connection and no credential is copied in plain text into shared documentation.
Run in parallel with automated sync paused on one side
Keep the source and destination running side by side, but ensure that for each Application only one instance has automated sync enabled. Typically the source keeps reconciling until the moment of cutover, and the destination Applications are imported with automated sync disabled so they can be compared. Use the diff views on the destination to confirm the desired state matches what is live. Two controllers reconciling the same resources can fight over them, so write down which instance owns each Application and check that assignment at every review. The step is done when the diff reports match for the whole pilot set and the ownership record has been reviewed.
Switch DNS and cut over ownership
Disable automated sync on the source for the Applications being moved, enable it on the destination, and then update the DNS record that users and automation use to reach Argo CD. Lower the DNS TTL well before the change, using a value your DNS team confirms. Update webhooks from Git hosts so they point to the destination, and verify that a commit triggers a refresh there. The step is complete when a test change syncs through the destination, the source reports no active automated sync for the moved Applications, and sign-in works through the new address.
Decommission the old instance after a verified period
Keep the source instance in a read-only or stopped state for a verification period agreed in advance by the platform and application owners, so that any missed object or webhook can be recovered. Take a final export from the source before shutting it down and store it with your other Argo CD backups. Remove its cluster registrations and repository credentials once the destination is confirmed as the only controller. The step is done when the owners sign off, the final export is stored, and the source's cluster-side resources and credentials are removed.
Avoiding double reconciliation during the parallel run
Two Argo CD instances that both manage the same resources will fight over them. Each controller compares live state with the Git revision it watches, so when the old and new instances point at the same repository path and destination, each one can revert changes the other has just applied. The result is drift and flapping: applications that toggle between Synced and OutOfSync, unexplained resource rewrites, and sync history that no longer matches what anyone approved in Git. The fix is to make ownership explicit before the first new Application syncs. Decide, per application, which instance is the owner at every point in the parallel run, and record that decision in your migration runbook.
Use one of two patterns. The first pauses the old instance for each application: disable automated sync on the source Application in the old cluster, or pause the Application entirely, then confirm no automated sync is still active before the new Application takes over. The second moves ownership one application at a time: the new instance syncs a single application, you verify its health and resource state, and only then do you remove or disable that Application on the old side. Do not let both Applications stay enabled with automated sync against the same resources, even briefly. Remove the old Application with its finalizer behavior in mind, so that deleting it does not cascade into the workloads the new instance now owns. Confirm the exact deletion behavior in the Argo CD documentation for your version before you rely on it.
Resource tracking is the other source of conflict. From Argo CD 2.14 to 3.0, annotation-based resource tracking is the default, so each managed resource carries an annotation that names its owning Application. If the old and new instances use different tracking settings, one instance may not recognize resources the other has labeled, and ownership checks will disagree. Before the cutover, compare the resource tracking method on both instances, confirm the application.resourceTrackingMethod setting in argocd-cm on the destination, and check a sample of live resources for the expected annotations. Confirm the current tracking defaults for your version in the Argo CD upgrade notes and in your own test cluster before you start the parallel run.
What drives the effort and duration of the move
This table lists the factors that change how much work a move to a new management cluster involves, what raises or lowers each one, and what to request in a written quote. Read each row against your own inventory of Applications, clusters, repositories and access paths. The main takeaway is that the number of resources to re-register and the number of teams that must sign off on a cutover usually matter more than the Argo CD version alone.
| Driver | Why it changes effort | What to ask for in a quote |
|---|---|---|
| Applications and ApplicationSets | Each Application and ApplicationSet must be exported, checked against the destination and reconciled once. Large counts of generated Applications raise verification work. | A written inventory count by type, the export and import method, and how drift between source and destination will be checked. |
| Clusters and repositories re-registered | Cluster credentials and repository definitions must be recreated on the new instance. Repositories are defined as Kubernetes Secrets in Argo CD 3.0 and later, so each one needs its own review. | A list of every cluster and repository to be re-registered, who supplies credentials, and how credentials are rotated afterward. |
| SSO and RBAC reused or rebuilt | Reusing SSO and RBAC means verifying group claims and project roles on the new instance. Rebuilding them adds design, testing and user communication. Dex RBAC uses the federated_claims.user_id claim from 3.0 onward. | Whether SSO and RBAC are migrated as exported or redesigned, the test accounts used, and the handling of the admin account. |
| Version gap between source and destination | Export and import must use an Argo CD image matching the server version. A large gap may add upgrade steps, breaking-change review and a separate compatibility test. | The source and target versions, the upgrade path planned, and the test environment where the gap is closed before cutover. |
| High availability on the destination | HA manifests need at least three nodes because of pod anti-affinity rules. Controller sharding and Redis HA settings add configuration and load testing. | Node count and placement on the destination, whether HA is in scope, and the sharding and Redis settings to be validated. |
| External secrets operators | If secrets come from an external operator, the operator, its identity and its store must be rebuilt or re-authorized on the destination cluster before Applications sync. | Which operator and secret stores are in use, the access they need on the new cluster, and who approves those permissions. |
| Teams that must approve the cutover window | Each application owner, change board and on-call group that approves a window adds coordination time. Freeze periods and shared namespaces increase this further. | The approval list, the change process for the cutover window, and the freeze calendar that the plan must respect. |
| DNS switch and double reconciliation control | Controlling which instance reconciles each resource, and when, requires disabling auto-sync on the source before the DNS change. Mistakes here cause conflicting updates. | The written cutover runbook, the sync pause method on the source, and the rollback steps if both instances reconcile the same resources. |
What usually goes wrong during an Argo CD cluster move
Most failed Argo CD moves do not fail in the new cluster. They fail at the seams: the export, the cutover of who reconciles what, the credentials that did not come along, and the sign-in path users depend on. Each risk below has a prevention step you can plan before the move window opens.
Version mismatch between export and destination
An export and import only behave predictably when the tooling matches the running server. Run argocd admin export from the quay.io/argoproj/argocd image that matches the server version, and confirm the destination installs the same minor version before importing. Before the window, check the release notes for any version step between source and destination, and record both version strings in the change ticket so the rollback decision is based on facts.
Exporting from the wrong namespace
The export command does not report an error when it runs against the wrong namespace, so a backup can look successful and still contain nothing useful. Confirm the Argo CD namespace on the source cluster, then check that the exported file contains the Applications, AppProjects, repository Secrets and cluster Secrets you expect. Keep the exported file with the change record, and test the import into a scratch namespace before cutover.
Two controllers reconciling the same resources
If the old and new Argo CD instances both have Applications pointing at the same Git path and cluster, they will both apply changes and fight over drift. This produces churn, unexpected rollbacks and confusing sync history. Freeze auto-sync and self-heal on the source instance before the cutover, disable the source Applications once the destination is healthy, and confirm in the destination that each Application shows a single owner before the old instance is scaled down.
Losing cluster credentials or repository access
Cluster and repository definitions are stored as Kubernetes Secrets, and an import can carry stale tokens or kubeconfig references that no longer work from the new network. Check that every registered cluster and repository authenticates from the new management cluster before any Application is switched over. Keep the credentials in your secrets store as well, so a failed import does not leave you without a way to re-register them.
Forgotten SSO redirect URLs and DNS delays
Users sign in through an identity provider that was configured with the old Argo CD callback URL. After the move, sign-in fails until the new redirect URI is added to the provider, and the old hostname may keep resolving to the old cluster for as long as the DNS record is cached. List every OIDC or Dex client that targets the instance, add the new callback URLs ahead of time, and lower the record TTL well before the switch so you can verify resolution from several networks.
Lost admin access after disabling the admin user
The user management guidance recommends disabling the built-in admin user with admin.enabled set to false once local users or SSO work. If that is done on the new instance before SSO group mappings are tested, nobody may be able to sign in to repair RBAC. Keep the admin user enabled through the cutover, verify at least one SSO administrator can change Applications and Projects, and disable the admin user only after that check passes.
Questions teams ask before moving Argo CD to a new cluster
How much effort does moving Argo CD to a new management cluster take?
The effort depends mostly on how much state lives outside Git and how many clusters, repositories and SSO connections the current installation already manages. A single-cluster install with all applications defined in Git and a few repositories is a small job. An installation that has grown through manual settings, many registered clusters, custom Secrets and several identity connections takes longer because each of those must be inventoried and re-created. Argo CD keeps most of its data in Kubernetes objects, so the work is mainly careful transfer and verification rather than rebuilding applications. Cost comes from the engineering time to inventory, rehearse and cut over, plus any testing you require before the switch. Ask any partner for a fixed-scope quote built from your own inventory of clusters, repositories, Secrets, RBAC and SSO settings.
What sets the timeline for relocating Argo CD?
The timeline is set by the number of change windows you can use, the approval steps your change control process requires, and how many applications must be verified after cutover. Preparation includes confirming that the new cluster runs a supported Kubernetes version for the Argo CD release you plan to use, matching the Argo CD version on both sides, and rehearsing the export and import in a non-production cluster. The Argo CD release process ships a minor release four times a year and patches only the three most recent minor versions, so a version that is already out of patch support adds upgrade work to the move. Ask for a written schedule with the rehearsal, cutover and rollback dates, and confirm the window with your own change board.
What does the move need from our own team?
Your team provides access, decisions and verification. Typically this means someone who owns the cluster and its network paths, someone who can approve DNS and certificate changes, the people who own each repository and each registered cluster, and an identity administrator if SSO is in scope. Your team also confirms which applications are business-critical and what healthy looks like for each one after cutover. You should expect to supply credentials for the source and target clusters, a list of Git repositories with their access methods, and the current Argo CD configuration, including RBAC and SSO settings. Agree on these responsibilities in the written scope so that delays do not come from waiting on access or approvals.
Can our in-house platform team move Argo CD without a partner?
Yes, a capable platform team can do this, and many do. The work is well defined: export settings, rebuild the target installation, re-register clusters and repositories, check versions, and change DNS. The risks are in the details. The export does not report an error when run against the wrong namespace, so teams must verify the output before relying on it. Argo CD 3.0 changed where repository definitions live and how Dex RBAC claims are read, so settings copied from an older release need adjustment. Your team should decide whether it has the time, the rehearsal environment and the on-call coverage for a cutover. A partner is useful when the internal team needs a second pair of hands, an independent review of the cutover plan, or a documented runbook for the next change.
Does the Argo CD export capture everything we need?
No. The argocd admin export command captures the Argo CD resources stored in Kubernetes, such as Applications, AppProjects, ConfigMaps and Secrets in the Argo CD namespace, but it does not replace the other parts of the move. Git repositories remain the source of truth for application manifests, so any application defined only in the cluster must be checked. Cluster credentials, repository credentials, SSO client secrets, TLS certificates, custom plugins, notification settings and any external secret store references need separate review. Check the exported file against an inventory you build from the live installation. Verify restored behavior with a test sync rather than trusting that a successful import means every integration works.
How do we avoid downtime and double reconciliation during the switch?
Keep one controller reconciling each application at any moment. Stop automated sync on the old installation or pause the applications before the new installation is allowed to act on the same resources, then switch DNS or the webhook endpoint once the new installation shows the expected state. Two Argo CD instances managing the same resources can fight over the live state and cause flapping, so the cutover order matters more than the tooling. Use a rehearsal to measure how long pausing and resuming takes for your application count, and keep the old installation intact until the rollback window closes. Webhooks from Git hosts and any notification targets also need to be repointed in the same window.
What does a DeployOpen engagement cover for this move?
DeployOpen plans, implements and documents self-hosted open-source platforms inside your own infrastructure, including Argo CD relocation work of this kind. An engagement starts with a written scope that lists the inventory, rehearsal, export and import steps, cluster and repository re-registration, version matching, DNS and webhook changes, verification and rollback steps. Most engagements are fixed-scope, so deliverables and timelines are agreed in writing before work begins, and a quote follows from that scope. Ongoing support and upgrades are available as retainers if you want help after the move. Ask for the written scope and a list of the evidence the engagement will produce, such as the runbook and verification results.
Official Argo CD documentation for the move
Start with the disaster recovery guide in the Argo CD operator manual. It is the primary reference for the export and import steps used in this move, and it describes the backup pattern the platform team should follow: run argocd admin export from the quay.io/argoproj/argocd image that matches the running server version, then restore with argocd admin import on the new cluster. Read it before you schedule the cutover, because the same guide warns that export does not report an error when it is pointed at the wrong namespace, so the team must verify the exported contents rather than trust a successful exit code. Pair it with the Argo CD disaster recovery guide and keep a copy of the export file with the change record.
Next, read the high availability guide to confirm what actually has to move. The guide describes Argo CD as largely stateless, with its data held in Kubernetes objects and Redis acting as a disposable cache. That means the new cluster can rebuild Redis and the controller state, but it also means the team must confirm that every Application, AppProject, repository Secret, cluster Secret and RBAC ConfigMap is captured by the export. If the target version differs from the source, review the 2.14 to 3.0 upgrade notes first, since they cover repository Secrets, the federated_claims.user_id claim for Dex RBAC, and the logs permission change. Confirm your exact source and target versions against the release process and cadence before choosing the image tag.
