Why moving Argo CD to HA is a planned change, not a manifest swap
If your single-replica Argo CD now deploys production workloads, the move to high availability is a change to a running control plane, not a file you apply on a quiet afternoon. The short answer is that you need spare node capacity, a maintenance window agreed with the teams whose deployments pause during the change, and a rollback path you have tested before you touch the live installation. The Argo CD installation guide states that the non-HA installation is not recommended for production and that the HA installation, with multiple replicas for supported components, is recommended for production. That recommendation is the reason to do the work, and it also means the work touches every component that reconciles your applications.
The effort comes from three places. First, the HA manifests use pod anti-affinity, so the cluster needs enough schedulable nodes to spread the replicas, and the high availability documentation says at least three nodes are required. Second, you must align the API server and application controller replica counts with the ARGOCD_API_SERVER_REPLICAS and ARGOCD_CONTROLLER_REPLICAS settings, and decide how the controller is sharded. Third, Redis moves to an HA layout. Confirm whether your cluster is IPv6-only, because the documentation says those clusters are not supported. Also check how your current installation was deployed, since Kustomize overlays, Helm values and manual edits each change the migration path.
Before scheduling the window, ask your platform team to export the Argo CD ConfigMaps, Secrets, RBAC policy and Application and AppProject objects, then confirm that a restore into a scratch cluster reproduces the same state. Review the Argo CD high availability documentation against your own manifest source and version so the replica settings match. Agree in writing who approves the window, who can roll back, and what counts as a successful cutover. Effort scales with the number of clusters Argo CD manages, the number of custom settings in place, and whether automated sync is active during the change.
Which non-HA settings carry over to the HA install and which need changes
This table compares each part of a single-replica Argo CD setup with what it becomes on the HA manifests and the migration note for it. Read it as a checklist to run against your own manifests before the cutover, since the exact keys and versions depend on the release you run. The main takeaway is that most configuration carries over unchanged, while repository definitions, admin access and the replica settings need deliberate checks.
| Component | Single-replica setup | HA equivalent and migration note |
|---|---|---|
| ConfigMaps (argocd-cm, argocd-cmd-params-cm) | Single controller, server and repo-server settings in one place | Carries over, but confirm each key still exists in the HA release you target. Set replica counts to match ARGOCD_API_SERVER_REPLICAS and ARGOCD_CONTROLLER_REPLICAS. |
| Repository secrets | Repositories defined as Kubernetes Secrets on 3.0 and later | Carries over unchanged. On versions before 3.0, confirm repositories were not still defined in argocd-cm, because 3.0 removed that path. |
| Cluster secrets | Destination clusters registered as Kubernetes Secrets | Carries over. Confirm credentials still resolve from the HA namespace and that no application is pointed at a cluster name that changed. |
| RBAC (argocd-rbac-cm) | Policy CSV and default policy | Carries over. On 3.0 and later, confirm that update and delete rules apply to the application itself and that logs access has an explicit logs, get permission. |
| SSO via bundled Dex or direct OIDC | Connector or OIDC settings in argocd-cm, secrets for client credentials | Carries over. Confirm the redirect URL still matches the external hostname, and on 3.0 and later confirm RBAC mappings use the federated_claims.user_id claim. |
| Admin account | Built-in admin user, often still enabled | Check admin.enabled before and after. Disable it once local users or SSO work, and confirm a working SSO login exists first. |
| Ingress and TLS | Single server service behind one ingress | Needs review. Confirm the ingress targets the HA server service, that TLS terminates as before, and that gRPC and CLI access still work. |
| Custom plugins | Plugins defined in argocd-cm or sidecar plugins | Confirm the plugin method for your version. Plugins defined in argocd-cm no longer work after 2.8, so they must already be sidecar plugins before the move. |
| Notifications | Notification controller config and secrets | Carries over, but confirm the notification settings and secret names exist in the HA manifests you apply and that alerts resume once the new pods are running. |
| Redis | Single Redis instance acting as a cache | Replaced by Redis HA. Redis is a disposable cache, so the move does not need Redis data migrated, but confirm cache-dependent sync behavior after cutover. |
Node, network and cluster prerequisites for HA
If the cluster has at least three schedulable nodes, the main question is whether those nodes can host the HA pods without breaking pod anti-affinity. The HA manifests spread replicas of components such as the API server, repo-server and Redis across nodes, so the scheduler must find a placement for each replica on a different node. Capacity is the usual blocker: a three-node cluster that is already near its limits may leave replicas in Pending. Confirm the actual placement before you apply anything.
- Schedulable node count: Count nodes that are Ready and not tainted in a way that excludes the Argo CD pods. Control-plane taints and dedicated node pools often reduce the usable count below the number you expect.
- Free CPU and memory: Add the resource requests of the HA replicas to current usage, then check headroom on the nodes that remain after a single node failure.
- Storage for Redis and the controller: Confirm which components need persistent volumes in your HA design and that a storage class is available across the nodes.
- Maintenance windows: Check whether node drains or upgrades in your cluster would take two of three nodes out at once.
Before the move, decide who approves a temporary increase in resource requests and whether the cluster autoscaler or node pool changes are in scope.
A cluster with one or two nodes cannot satisfy the pod anti-affinity rules in the HA manifests, so the HA layout will not schedule as designed. Teams in this position usually have two choices: add nodes to reach three or more before the move, or keep the single-replica installation on purpose for now and accept that it is not the recommended production layout. The installation guide describes the non-HA setup as not recommended for production, so the decision should be recorded, not assumed.
- Node addition lead time: Ask your infrastructure or cloud team how long new nodes take to provision, approve and join the cluster, since this sets the earliest date for the move.
- Node sizing: Size new nodes for the HA replicas plus the workload already running, not for Argo CD alone.
- Interim risk: Document what a single Argo CD outage would stop, such as application syncs, rollbacks and access for teams that deploy through it.
- Interim hardening: Confirm backups of Argo CD's Kubernetes objects are current, because the single-replica installation is the state you would restore from.
- Decision owner: Name who accepts the risk if the move waits for nodes, and when that decision is reviewed.
Before you commit to a date, confirm with your platform team that the node addition is funded and scheduled, not just requested.
The HA documentation states that IPv6-only clusters are not supported. If your cluster is IPv6-only, the HA manifests should not be treated as a drop-in target, regardless of node count. The decision here is architectural: either the cluster gains an IPv4 path that the HA setup can use, or the team confirms the current support position with the Argo CD project before planning further. Do not assume that a workaround used for other components applies to Argo CD HA.
- Dual-stack status: Confirm whether your cluster runs IPv6-only or dual-stack, and whether pods and services have IPv4 addresses available.
- Supported position: Check the current high availability documentation and the project's release notes for changes to IPv6 support before you rely on them.
- Ingress and DNS path: Map how users, CI systems and webhooks reach the API server from outside the cluster, since those paths may also be IPv6-only.
- Git and registry access: Confirm the repo-server can reach Git hosts and Helm repositories over the protocol they support.
- Alternative target: If IPv6 cannot be added, decide whether Argo CD moves to a different cluster, a separate management cluster, or stays on the current design under a documented exception.
Before planning further, get written confirmation from your network team and from the vendor documentation about the protocol support you are relying on.
How to move to HA without losing applications
This sequence moves a single-replica Argo CD onto the HA manifests by backing up its state, proving the target build in staging, and cutting over with a verified rollback path, so existing Applications keep syncing throughout.
Export and back up all Argo CD state
Your platform team exports Applications, AppProjects, repository and cluster Secrets, the argocd-cm and argocd-rbac-cm ConfigMaps, and any notification or SSO settings from the running namespace. Store the export in version control or a backup location outside the cluster and encrypt it, because the Secrets contain credentials. Confirm the backup is complete by listing each object type and comparing counts with the live namespace. The step is done when you can restore the export into an empty test namespace and see the same Applications and projects appear.
Confirm target version and upgrade notes
Choose the Argo CD release you will run on the HA manifests and read its upgrade notes against your current version. If you are also crossing a major boundary, such as 2.14 to 3.0, review the RBAC, logs access, resource tracking and repository configuration changes first, because they change behavior for users and Applications. Check the release process documentation for which minor versions still receive patch releases. The output is a written version decision with a list of configuration changes you must make before cutover.
Build the HA install in staging
Deploy the HA manifests for your chosen version into a staging cluster that matches production's node count and network path. The HA documentation requires at least three nodes because of pod anti-affinity rules, and IPv6-only clusters are not supported, so confirm both before you start. Apply your restored configuration, repository Secrets and cluster registrations, then set ARGOCD_API_SERVER_REPLICAS to match your argocd-server replica count and ARGOCD_CONTROLLER_REPLICAS for the application controller. Done when all components are Ready and the staging instance reconciles a test Application.
Validate SSO, RBAC and repository access
Test each login path your teams use, whether bundled Dex connectors or a direct OIDC provider, and confirm that group claims map to the same Argo CD roles as before. Check that the admin user is disabled once SSO works, as the user management guide recommends. Verify that every repository in the restored Secrets can be fetched and that each AppProject still limits source repositories and destination clusters. Record the results in a checklist. The step is done when a non-admin user with each role can perform exactly the actions they could perform in production.
Run a parallel check against production
Point the staging instance at a read-only view of production Applications, or register a subset of non-critical clusters, and compare sync status, health and rendered manifests with the live instance. Do not let both controllers write to the same resources at the same time. Investigate any drift in rendered output before cutover, because differences in Helm, Kustomize or plugin behavior between versions are a common source of unexpected changes. The output is a comparison report showing that manifests render identically for a representative set of Applications.
Cut over the API server and controllers
Plan a maintenance window if your change process requires one, and confirm the approach with the vendor documentation for your version. Stop the single-replica controller before the HA controller takes ownership of the same clusters, then point DNS, ingress or the load balancer at the new argocd-server service. Monitor Application sync and health for the first reconciliation cycle and be ready to point traffic back to the old instance. The cutover is complete when all Applications show the expected status under the HA controller and no resources are being reconciled by two controllers.
Retire the old single replica
After a stable observation period agreed with your change board, scale down or remove the old single-replica deployment and its Redis instance, and remove any leftover cluster or repository registrations that point to it. Keep the pre-cutover backup for the retention period your policy requires. Confirm there are no remaining references to the old service in ingress, monitoring or CI webhooks. The step is done when the old instance is gone, the new instance is the only controller of record, and the backup is stored and tested for restore.
What drives the cost and effort of an HA move
This table lists the factors that change how much work an HA move takes and what to ask for in a quote. Read each row against your own installation, since the same change can be a small task in one environment and a long one in another. The main takeaway is that cluster count, Helm and Kustomize use, and node capacity usually matter more than the HA manifests themselves.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Number of clusters and applications | More clusters and Applications mean more sync checks, more sharding decisions and a longer cutover window. Controller sharding is more involved once several clusters are registered. | Count of registered clusters and Applications, the sharding approach, and whether validation covers every Application or a sample |
| Repositories and Helm or Kustomize use | Each repo-server render path must be re-verified after the move. Repos with heavy Helm or Kustomize generation take longer to test and tune. | Inventory of repositories, Helm charts and Kustomize overlays, and the test plan for manifest generation |
| SSO and RBAC complexity | Ingress URL changes can break OIDC redirect URIs and Dex callbacks. Group-to-role mappings must be rechecked after the API server is replicated. | List of identity connectors, redirect URIs to update, and the RBAC policy review scope |
| Custom plugins | Plugins that run inside the repo-server or depend on specific pod layout need testing against the HA component layout before cutover. | Plugin inventory, whether each plugin is a sidecar or a legacy configuration, and the test cases for each |
| Ingress and TLS changes | Moving to multiple API server replicas usually means revisiting the Service, Ingress and certificate setup. Each change affects users and CI webhooks. | Current ingress controller, certificate source, and the list of external systems calling the Argo CD API or webhooks |
| Node capacity availability | HA manifests need at least three nodes because of pod anti-affinity rules. Missing nodes or tight capacity can force a node pool change, which adds effort and lead time. | Node count and size per cluster, capacity headroom, and who provisions new nodes and when |
| Change control and approval steps | Production change windows, CAB reviews and rollback approvals add waiting time and documentation work. Each approval gate extends the schedule. | Required approval gates, change record templates, and the number of rehearsal runs expected before production |
| Team Kubernetes skill | Teams new to Redis HA, pod disruption behavior or Argo CD internals need more guidance and review. Experienced teams can run more of the work themselves. | Division of work between your staff and the partner, handover scope, and training or pairing included |
What usually goes wrong during a non-HA to HA switch
Most failed switches come from a small set of predictable problems: duplicate controllers, scheduling constraints, lost credentials, identity drift and network assumptions. Each card below names one of these and the check that prevents it before the cutover window opens.
Two controllers reconciling the same resources
Running the HA manifests next to the existing single-replica installation, or applying them over it with a second controller left active, lets two application controllers fight over the same Applications. Resources then flap between states and sync history becomes unreadable. Before you apply anything, confirm that exactly one Argo CD instance manages each Application, and plan the switch so the old controller is scaled down or removed in the same change window. Illustrative: an Application that shows Progressing for hours often has a second controller behind it.
Anti-affinity blocking scheduling
The HA manifests use pod anti-affinity rules, so Argo CD components will not all schedule on a cluster with fewer than three nodes. Pods can sit in Pending while the old deployment is already scaled down, which turns a planned change into an outage. Check node count, taints, free capacity and any node selectors on the target cluster before you scale anything, and confirm that the platform team can add capacity or adjust the rules before the window.
Losing repository and cluster credentials
Repository credentials and registered cluster secrets live in Kubernetes objects. If the migration recreates the namespace, restores a partial export, or rebuilds Argo CD with a new Helm release name, Applications can lose the Git access and cluster access they depend on. Export every repository and cluster Secret with a labeled inventory, compare the list after the move, and run a sync on a non-critical Application before the rest are touched.
RBAC or SSO breaking after the change
Changing the deployment often changes the external URL, the OIDC redirect URI or the Dex configuration, so logins fail or users land in the wrong role. Group-to-role mappings in argocd-rbac-cm can also drop out if that ConfigMap is not carried over. Record the current SSO settings and role mappings, verify a test user's access in a staging copy, and keep the local admin account available until SSO is confirmed working, then disable it as the user management guidance recommends.
IPv6-only clusters
The HA documentation states that IPv6-only clusters are not supported for HA manifests. A cluster that was fine for a single replica can fail the move if its networking is IPv6-only, and the failure may only appear once pods are scheduled across nodes. Confirm the address families of the cluster and its services before planning the switch, and if the cluster is IPv6-only, treat the HA move as a networking project with its own decision and test.
Dropped webhooks and DNS references
Git webhooks, CI jobs and internal scripts often point at the old Argo CD service name, ingress host or IP address. After the switch, those callers fail silently and Applications only refresh on the polling interval, so teams assume deploys are stuck. List every webhook, script and DNS record that references the Argo CD endpoint, point them at the new endpoint in the same window, and trigger a test refresh from each source.
Questions teams ask before moving Argo CD to HA
How much does moving Argo CD to HA cost?
The cost is the labor to plan, change and verify the installation, plus the infrastructure the HA layout needs. No public price is attached to this work, so the figure depends on your scope. The main drivers are the number of clusters and Applications Argo CD manages, whether SSO and repository secrets already exist, how many environments need a test run first, and whether your nodes can host the HA layout. Infrastructure is recurring: the HA manifests need at least three nodes because of pod anti-affinity rules, so the extra nodes carry an ongoing cost. Ask any partner for a fixed-scope quote with the items listed separately: assessment, staging rehearsal, production cutover, rollback test and handover.
How long does an Argo CD HA migration take?
Duration is set by how many environments you have, how much of your configuration is already in Git, and how many change windows you can use. A single instance with few clusters moves faster than one with many registered clusters, custom plugins or manually edited settings. The work runs in stages: confirm the node count, rehearse the change in a non-production copy, then move production with a maintenance window agreed in advance. Ask for a timeline that lists each stage and the approval gates between them, rather than a single date.
What does our team need to provide for the move?
You need to provide access and decisions, not just a Kubernetes cluster. Expect to supply a cluster with at least three nodes that can schedule the HA pods, a reviewed copy of your current Argo CD configuration and Application definitions, the Git repositories and their credentials, the registered cluster list, and the people who approve production changes. You also need a named owner for SSO and the admin account, because the user management documentation recommends using the built-in admin user only for initial setup and disabling it with admin.enabled set to false once local users or SSO are configured. Confirm these items with your partner before work starts.
Can our in-house platform team do the HA move alone?
Often yes, if the team already runs Kubernetes in production and has someone who understands your Argo CD configuration. The work is mostly controlled manifest changes, replica settings and verification, and the official HA documentation describes the components and replica settings directly. The harder parts are the ones that depend on your environment: node capacity, network paths to registered clusters, and how your Applications were created. Teams with no recent Kubernetes change experience, or with heavy customization, often bring in outside help for the rehearsal and cutover. Whichever route you choose, write down who owns the rollback decision before the first change.
Will applications go down during an Argo CD HA cutover?
Applications managed by Argo CD should keep running, because Argo CD is largely stateless and keeps its data in Kubernetes objects. Its main job is reconciling desired state, so a planned pause in reconciliation affects how quickly changes land, not the workloads already running. Redis is a disposable cache, so losing it causes a refresh rather than data loss. The risk comes from mistakes: two controllers reconciling the same resources, or an Application's source or destination changing during the move. Confirm with your change owner that auto-sync is paused for the cutover window, and check that Applications report the expected state after each step.
Is there a rollback path if the HA move fails?
Yes, if you keep the pre-move state. Before changing anything, export and store the Argo CD configuration, the Application and project definitions, the repository and cluster secrets, and the version you run. Then rehearse the rollback in staging, so the team knows how long it takes and which steps reverse the change. Argo CD keeps its data in Kubernetes objects, which makes restoring the earlier manifests the central step. Confirm with your partner whether they will test the rollback before production, and ask who signs off on returning to the single-replica layout.
How does an HA move affect Argo CD upgrades?
Treat the HA move and any version change as separate changes. The Argo CD release process says a minor release ships four times a year and only the three most recent minor versions receive patch releases, so an HA move on an old version forces an upgrade soon after. Major upgrades, such as the 2.14 to 3.0 path, carry breaking changes, including repository definitions moving into Kubernetes Secrets and a new RBAC claim for Dex. Doing both in one window multiplies the risk. Most teams move to HA on their current supported version first, verify it, and then plan the upgrade path separately.
How DeployOpen scopes and delivers the HA move
DeployOpen delivers the move from a single-replica Argo CD to the HA installation under a written, fixed scope agreed before any work starts. The scope names the target cluster, the Argo CD version being moved to, the manifests and overlays that will be used, the node pool that will host the three-node anti-affinity layout, and the applications and clusters that must keep syncing throughout. It also lists what is out of scope, such as SSO redesign, repo-server tuning or controller sharding for many clusters, so that those items are not absorbed silently into the price. Every deliverable, from the rendered HA manifests to the cutover runbook and the handover pack, is named in that document with an acceptance check. DeployOpen runs this work inside your own clusters and accounts, and it does not publish a price list. A quote follows from the written scope, so the questions to bring to a proposal are how many clusters and applications are affected, whether a staging cluster exists, and who on your side approves the change window.
Before anything touches production, the move is rehearsed in a staging copy built from a recent export of your Argo CD settings, including the argocd-cm, argocd-rbac-cm and repository Secrets, and the application objects. The rehearsal checks the things that most often break in practice: whether the cluster has enough schedulable nodes for the anti-affinity rules, whether the ARGOCD_API_SERVER_REPLICAS and ARGOCD_CONTROLLER_REPLICAS values match the replica counts actually deployed, and whether SSO login and project RBAC still work after the change. The output is a timed runbook with a go or no-go checkpoint, a rollback step for each stage, and the exact commands your operators will run. Confirm with your team which change window and approval steps apply, since those set how much time the runbook can use.
After cutover, DeployOpen verifies sync status, health and login for a representative set of applications, then hands over architecture notes, the runbook as executed, the replica and sharding settings, and the Redis and backup procedures your operators will own. Ongoing support, version upgrades and continuous testing can be covered by a retainer, which is optional and priced separately. Upgrades matter here because the project's release process supports only the three most recent minor versions with patch releases, so a plan for keeping within that window should be part of the handover. Ask any partner to state in the proposal which of these items recur and which are one-time.
