Scaling the Argo CD API server and Redis for a growing platform team
The two components to size first as your Argo CD grows are the API server (argocd-server) and Redis (argocd-redis). The API server carries every UI and CLI session, so its replica count determines how many people can work in Argo CD at once without slowdowns. Redis holds the cache that the controllers and API server read from, so its layout determines whether that cache stays available when a single pod fails. The high availability guide recommends three or more argocd-server replicas and setting ARGOCD_API_SERVER_REPLICAS to match that count. This setting matters beyond capacity: the login rate limit is divided across replicas, so the number you set changes how many failed logins each replica allows before throttling. Confirm the current rate-limit keys and defaults for your release in the guide before you change the replica count.
You usually need this work when more people log in each quarter, when UI or CLI requests start timing out during busy periods, or when a single Redis pod restart causes visible cache trouble. The HA manifests preconfigure argocd-redis for exactly three Redis servers or Sentinels, so a planned Redis layout should start from that baseline rather than from a custom count. Ask your platform team to measure current login volume, peak concurrent sessions and API latency during syncs before changing anything. Also confirm the node count you have, because the HA manifests need at least three nodes for their pod anti-affinity rules, and that limit applies to the replicas you add here.
This work does not solve slow manifest generation, long Git refreshes or controller backlogs. Those problems sit with the repo-server and the application controller, so raising API server replicas will not speed up a stuck sync. Plan repo-server sizing and controller sharding as separate work, and watch for their signs in your metrics before blaming the API server. Also treat Redis as a disposable cache: scaling it improves availability of cached state, but the source of truth stays in Kubernetes objects and Git. Test a Redis pod failure in a non-production cluster so you know how the UI and controllers behave during the failover window.
Which scaling option fits which growth pattern
This table compares the API server replica settings, the login rate limit split, the three-server Redis layout in the HA manifests and external Redis. Read each row against your user count, application count and the Redis operating model your team already runs, then confirm the items in the last column before you size the install.
| Option | When it fits | What it changes and what to confirm |
|---|---|---|
| Single argocd-server replica | Small team with few UI and CLI users and no uptime requirement for the UI | One pod serves all logins and API calls. Confirm that a brief UI outage during node drains or upgrades is acceptable to your change process. |
| Three or more argocd-server replicas with ARGOCD_API_SERVER_REPLICAS matched | Many concurrent UI and CLI users, or a team that needs the API to stay up during node maintenance | The HA guide recommends three or more replicas and setting ARGOCD_API_SERVER_REPLICAS to the same count. Confirm the value matches the replica count after every scale change, or the login limit will be wrong. |
| Login rate limit divided across replicas | Environments where many users sign in at once, such as after an SSO outage or a shared-login morning | The login rate limit is divided across replicas, so each replica enforces its share. Confirm with your SSO and identity team how many failed logins are expected in a burst before you tune the limit. |
| Three-server Redis layout in the HA manifests | Growing numbers of applications and clusters, where a single cache becomes a single point of failure | argocd-redis in the HA manifests is preconfigured for exactly three Redis servers or Sentinels. Confirm the storage class and node spread allow the three servers to land on separate nodes. |
| External Redis service | Organizations that already run a supported Redis platform with monitoring, backup and patching standards | Moves the cache out of the cluster and into your Redis operating model. Confirm the platform supports the Redis features Argo CD needs, the failover behavior and who patches and monitors it. |
| Controller-to-Redis traffic review | Large application counts where the application controller and API server share heavy cache traffic | Adds network policy and latency checks between controllers, the API server and Redis. Confirm the network path, TLS settings and resource limits on the Redis pods before adding more replicas. |
How to set up the API server and Redis in HA
This sequence takes an Argo CD installation from the default manifests to a high availability layout where the API server and Redis tolerate a node or pod loss, and where the controllers still reach the cache.
Confirm the three-node minimum
Before applying anything, the platform team confirms the target cluster has at least three schedulable nodes. The HA manifests use pod anti-affinity rules, so with fewer nodes the extra replicas stay Pending instead of spreading out. Confirm that the cluster runs IPv4 or dual-stack networking, because the HA documentation states that IPv6-only clusters are not supported. Done means a node listing shows three or more Ready nodes that the Argo CD namespace can schedule onto.
Apply the HA manifests for the namespace
The platform engineer applies the Argo CD high availability manifests to the Argo CD namespace, using the same install method and version used for the rest of the installation. Keep the image tag identical across all components so the API server, repo-server, application controller and Redis do not drift. Done means every Deployment and StatefulSet reports its desired replica count and the pods reach Running on separate nodes.
Scale argocd-server to three replicas
Set the argocd-server Deployment to at least three replicas, as the HA guide recommends. Scaling the Deployment alone is not enough, because the API server needs to know how many peers share the login rate limit. Confirm that each replica has its own pod, that the Service endpoints list all of them, and that no two replicas share a node when the cluster has enough nodes to satisfy anti-affinity.
Set ARGOCD_API_SERVER_REPLICAS to match
Set the ARGOCD_API_SERVER_REPLICAS environment variable on the API server so it equals the number of argocd-server replicas. The HA guide uses this value to divide the login rate limit across replicas, so a mismatch makes the effective limit either too strict or too loose. Record the value in the same change that scales the Deployment, so a later scale-up or scale-down updates both. Done means the running pods show the variable with the expected number.
Confirm the three-server Redis layout
Check that argocd-redis is running as the HA layout, with three Redis servers or Sentinels, which is how the HA manifests are preconfigured. Confirm that each Redis pod is on a different node and that a Sentinel or failover mechanism elects a primary. Because Redis is a disposable cache in Argo CD, a failover should cause a cache refresh rather than data loss, but confirm this behavior in your release notes. Done means three Redis pods are Ready and one primary is reported.
Test login and UI after a failover
Simulate a failure by deleting one argocd-server pod and, separately, the current Redis primary in a non-production cluster. During each event, sign in through the UI and run a CLI login against the same server, then open an Application page. Log the time to first successful response for each check. Done means logins and page loads succeed during and after each failover, and any errors clear without manual intervention. If logins fail while the rate limit is hit, revisit the replica count and the environment variable.
Check controller-to-Redis connectivity
Confirm that every application controller replica can reach the Redis service and authenticate with the password stored in the Argo CD secret. Look for connection errors in controller logs and confirm that application status updates continue after a Redis failover. Network policies that restrict traffic to Redis are a common cause of failures here, so verify them against the controller and API server pods. Done means controller logs show successful connections and application status keeps refreshing after the failover test.
How the login rate limit changes when replicas grow
The login rate limit on the Argo CD API server is not a fixed number you can read once and forget. The HA guide says that when ARGOCD_API_SERVER_REPLICAS is set, the limit is divided across the API server replicas, so the value you get per pod depends on how many replicas you run and whether that environment variable matches the actual replica count. If the variable says three and you run five, or the variable is missing, your effective login throttling is different from what you planned. Set the variable to the number of argocd-server replicas as part of the same change that scales the deployment, and treat any later replica change as a login-behavior change too.
The rate limit is a trade-off. A tight limit slows password guessing and credential stuffing against local accounts and the login path, which matters most when local users or the admin account are still enabled. A loose limit lets many SSO users sign in together at a shift change, a start-of-quarter access review or after a cluster restart, when a burst of browser redirects and CLI logins can hit the API server at once and see sign-ins fail. Decide which risk is more expensive in your environment, then document the choice next to your SSO and admin settings. Disabling the built-in admin user with admin.enabled set to false reduces the brute-force surface regardless of the limit.
Do not assume the limit protects you or that it is too strict until you have measured it. Confirm the current settings with the HA guide, then run a controlled login burst against a non-production instance with the replica count you plan to run, using a load tool and a representative mix of SSO and CLI logins. Record how many attempts succeed and fail at each replica count, and repeat the test after every scaling change. Ask your identity provider team how many concurrent sign-ins they expect at peak, and compare that figure with the measured results before you choose the final values.
Security and operational risks of a scaled API server and Redis
A scaled Argo CD control plane exposes more API endpoints, more credentials and more cached state to operate safely. The cards below cover the authentication, transport, credential handling and cache assumptions that stay in force as you add replicas, and the checks to run before you rely on them.
JWT-only API authentication
Argo CD authenticates API requests only with JSON Web Tokens, so every UI session, CLI call and automation client depends on token issuance and expiry being handled correctly. When you add API server replicas, confirm that all replicas validate tokens against the same signing configuration, so a request is accepted or rejected the same way no matter which pod receives it. Ask your team who may generate tokens for service accounts and how long those tokens remain valid.
TLS between Argo CD components
Argo CD uses TLS for traffic between its own components, not only at the external ingress. As you scale the API server, repo-server and Redis, verify that certificates are issued, rotated and trusted by every component that connects to another, and that a failed certificate fails closed. Test a certificate rotation in a staging environment before it is needed in production.
Credential redaction in responses and logs
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. Treat that as a default to verify rather than a guarantee for your setup: check the logs your log platform collects from each API server replica, and confirm that custom plugins, webhook handlers and debug settings do not print secrets. Include a redaction check in your rollout test plan whenever you change logging levels.
Redis holds no source of truth
Argo CD keeps its data in Kubernetes objects and treats Redis as a disposable cache. Losing Redis should slow the UI and trigger a rebuild of cached state, not lose applications or configuration. Plan your recovery runbooks around that assumption, and make sure your backups cover the Kubernetes objects and Git repositories instead of Redis contents.
Disabling the admin user after SSO
The built-in admin user is meant for initial setup. Once local users or SSO are configured, set admin.enabled to false so that a shared password cannot bypass your identity provider and its audit trail. Before you disable it, confirm that at least one SSO administrator can sign in and hold the RBAC role needed to re-enable access if your identity provider is unavailable.
Monitoring replica health during failover
Replica counts only protect you if failover behaves as expected. Watch the health of each argocd-server and argocd-redis pod, and confirm that a pod restart does not interrupt active sessions in ways your users cannot recover from. Rehearse a node drain with your anti-affinity rules and check that the three-node layout still schedules pods during maintenance.
Questions teams ask before scaling the API server and Redis
What does it cost to scale the Argo CD API server and Redis?
Cost comes from two places: the labor to size, change and verify the installation, and the infrastructure that runs the extra replicas. The labor is largely one-time, while the extra nodes, compute and storage recur for as long as the installation runs. Costs go up when the cluster has few spare nodes, when the identity provider needs integration work, or when change control requires separate approvals for each step. Ask any partner for a quote that lists the scope in writing, the environments covered (staging and production), the infrastructure changes and who pays for each. DeployOpen does not publish a price list, and a quote follows from the written scope.
How long does a sizing and HA change take?
Duration depends on the number of users, the number of applications, how many clusters Argo CD manages, and how much of the environment must be changed at once. The HA guide sets the baseline shape: three or more argocd-server replicas, with ARGOCD_API_SERVER_REPLICAS set to match, and argocd-redis preconfigured for exactly three Redis servers or Sentinels. Teams with three nodes ready, a tested Git and identity setup and a clear change window finish faster than teams that must first add nodes or agree on a rollout plan. Ask for a timeline tied to the written scope and to the staging validation steps, not to a generic estimate.
What must our team provide before the work starts?
Plan to provide the following before work starts:
- Clusters where Argo CD will run, with access and a named owner for each
- Enough nodes for pod anti-affinity, since the HA manifests need at least three nodes, and IPv6-only clusters are not supported
- Your identity provider details, such as an existing OIDC provider or the source for Dex connectors, and the group claims you will map to roles
- Change windows for staging and production, plus approvers for each step
- Load data, including user counts, application counts and cluster counts, so sizing decisions rest on your numbers
Confirm the exact list with the partner during scoping, because it depends on your environment.
Can our in-house platform team size and scale Argo CD by itself?
Yes, a team with Kubernetes operations experience and access to a staging cluster can usually handle the HA manifests, replica settings and Redis layout using the official documentation. The harder parts are the ones that touch your environment: node capacity, network policy, identity claims, and how the change fits into your release calendar. Teams that lack recent Kubernetes or Redis operations experience, or that must show change evidence to auditors, often bring in a partner for the design and verification steps. Whichever path you choose, assign one owner for sizing decisions and test the login rate limit and Redis failover in staging before production.
How do Argo CD upgrades affect API server replicas and Redis?
Upgrades change the manifests you run, so replica counts and Redis settings must be checked against the new release. Minor releases ship four times a year and only the three most recent minor versions receive patch releases, so plan to move forward regularly rather than waiting. The 2.14 to 3.0 upgrade notes also changed how RBAC and repository configuration behave, which affects users who log in through the API server. Review the upgrade notes for each target version, confirm that ARGOCD_API_SERVER_REPLICAS still matches the replica count, and rerun login and Redis failover tests after the upgrade in staging.
What signs show the API server or Redis needs more capacity?
Watch for slow UI and CLI responses during busy periods, login attempts that fail because the rate limit is reached, and Redis-related delays that show up as slow application status updates. A useful check is whether load rises with the number of users, applications or clusters. Confirm the thresholds and dashboards with your monitoring team, because the right values depend on your workload. Changes should be tested in staging with a load profile that matches your production use.
When should we hire an outside partner for this work?
Hire a partner when the work needs design decisions your team has not made before, when your change control requires documented evidence, or when your staff cannot take the time to test properly. A partner is also useful when the scope spans identity, multiple clusters and the Redis layout at once. DeployOpen plans, implements, hardens and documents self-hosted open-source platforms inside your own infrastructure, and most engagements are fixed-scope with scope, deliverables and timelines agreed in writing before work starts. Ongoing support and upgrades are available as retainers.
Keeping the API server and Redis on a supported release
Scaling the API server and Redis only pays off if the Argo CD release underneath them still receives fixes. The Argo CD release process ships a minor release four times a year, once every three months, and only the three most recent minor versions receive patch releases. Before you copy replica counts or Redis settings into a production values file, pick the minor line you will run and confirm it is still inside that window. A layout tuned for a version that has already left the patch window leaves you carrying security and bug fixes on your own. Check the current status on the Argo CD releases page on GitHub, which lists the latest patch versions and any release candidate in progress. Record the minor version and the date you checked it in your change record, because the answer changes every quarter.
Plan to repeat that check on a schedule rather than treating the scaled layout as finished. Each new minor line can change the manifests, the default settings and the expected RBAC model, so the API server and Redis configuration you tested last quarter may not be the one you need next quarter. Major upgrades need the most attention. The 2.14 to 3.0 upgrade notes changed how update and delete permissions apply to applications, required an explicit logs permission, made annotation-based resource tracking the default, and moved repository definitions into Kubernetes Secrets. Those are reasons to schedule a test upgrade on a non-production copy that includes your replica settings and the ARGOCD_API_SERVER_REPLICAS value, not reasons to avoid upgrading. Run the test with a realistic set of users and applications so you see how login behavior and the login rate limit behave under the new version.
Two practical decisions follow. First, set an owner for tracking releases and a window for applying patch releases to the scaled deployment, so that a security patch does not wait for the next planned change. Second, keep the API server replica count, the Redis topology and the rate limit settings in version-controlled configuration that moves with the Argo CD version, so an upgrade does not silently reset them. Ask your delivery partner or platform team to show which of these settings were changed from the default manifests and why, so that a later upgrade reviewer can see the intent behind each change.
How DeployOpen scopes and delivers Argo CD scaling work
Scaling the API server and Redis touches sizing, login behavior, high availability and controller traffic at once, so the work is scoped in writing before any change is made. The cards below describe how that scope is agreed, checked in your own infrastructure, documented and kept current after handover.
Fixed scope agreed in writing
Before work starts, DeployOpen and your team agree in writing which Argo CD installation is in scope, how many users and applications it serves, which clusters it deploys to, and what the deliverables are. The scope names the API server replica count, the Redis layout and the verification steps. Ask for the scope to state which items are excluded, such as repo-server tuning or controller sharding, so those do not surface as surprise change requests.
Sizing checks on your infrastructure
Sizing is measured in the client's own cluster, not estimated from a template. DeployOpen reviews how many people log in through the UI and CLI, how many applications exist, and how the API server behaves under that load. Confirm the chosen replica count matches the ARGOCD_API_SERVER_REPLICAS setting, because the login rate limit is divided across replicas and a mismatch changes how many logins are allowed.
Redis HA layout verification
The HA manifests preconfigure argocd-redis for three Redis servers or Sentinels, so the layout is checked against that default before any change. DeployOpen confirms the pods land on separate nodes under the anti-affinity rules, that failover works when a Redis pod is removed, and that the cluster has enough nodes to satisfy the spread. Ask whether your platform team has capacity for three nodes, since the HA documentation requires at least that many.
Controller-to-Redis traffic review
Application controllers read and write application state through Redis, so a large number of applications increases traffic on the cache. DeployOpen reviews controller connections, network policies between namespaces and TLS settings for that path, and watches for signs that Redis is the bottleneck, such as slow sync or stalled refreshes. The output is a written note of what was measured and what should be tuned later.
Failover and restart testing
A high availability design is only confirmed once failures are simulated. DeployOpen plans controlled tests that remove an API server replica, restart a Redis pod and drain a node, then records how logins, UI sessions and sync operations behave during each event. Ask for the test steps and expected results to be written into the scope, and agree who in your team observes and signs off each test.
Handover documentation and runbook
The handover includes the final configuration, the sizing decisions and their reasons, the Redis and API server layout diagrams, and a runbook for common failures. Documentation records which values were set and why, such as the replica count and login limit, so future changes can be reviewed against the original sizing. Confirm the format and location of the documents in the written scope before work begins.
Retainer for upgrades and support
Argo CD ships a minor release four times a year, and only the three most recent minor versions receive patch releases, so the installation needs a planned upgrade rhythm. A retainer covers ongoing support, upgrades and re-checks of sizing as the number of users and applications grows. Ask what response expectations the retainer includes and how upgrade windows are scheduled, since these are agreed in the retainer terms rather than assumed.
