Argo CD · Architecture
OpenTofu installs the initial chart; argocd-self becomes the steady-state owner. The root app-of-apps reads apps/ using yaml-envsubst, which discovers app.yaml files. Child sources render support manifests while excluding app.yaml, values.yaml, and variables.yaml. The bootstrap values define replicated server/controller/repo-server roles and Redis HA with Sentinel.
Component boundaries
- Source
- Git / shared variables
- Root app-of-apps
- Reconcile
- yaml-envsubst / Helm rendering
- Replicated Argo controllers + Redis HA
- Desired state
- Child Applications
- Kubernetes API → resources
State and recovery contract
Git reconstructs desired state. Preserve repository credentials, Argo authentication secrets, the sealing key, and bootstrap state. Redis is control-plane support state rather than a backup of application databases.
Availability and failure behavior
Availability classification: Partially HA overall: replicated API/rendering and Redis HA design; reconciliation and SSO are not proven by those counts.
This is an interpretation of the checked-in configuration, assuming the declared replicas are healthy, separated as intended, and their required dependencies are reachable. It is not a live-health result or a completed failure drill.
What supplies redundancy
| Component | Declared layout | Mechanism |
|---|---|---|
| API server | 2 replicas; hard anti-affinity | New UI/API requests can use the surviving server. |
| Repo server | 2 replicas; hard anti-affinity | Either can render Git inputs when Git and the plugin are available. |
| Application controller | 2 Deployment replicas; hard anti-affinity; zero-surge, one-unavailable rollout; dynamic round-robin cluster distribution; 5-second heartbeat | Rollouts fit the two eligible general workers without requiring a third pod. A failed controller’s cluster assignment can move to a surviving controller. This upstream feature is alpha and requires a reconciliation drill. |
| Redis HA | 3 chart members; quorum toleration | Sentinel/proxy behavior follows the pinned chart; it is distinct from the bespoke app Redis scripts. |
| Authentication | Native OIDC to Authentik; Dex disabled | Either API server can perform discovery and code exchange without a singleton broker. Authentik, ingress, DNS, and PostgreSQL must remain available. |
How a failure is handled
API and manifest-rendering requests can retry on the surviving replicas. Redis failover depends on the chart’s HA configuration. Dynamic cluster distribution enables heartbeat-based reassignment of a failed controller’s cluster. This changes the controller from a StatefulSet to a Deployment; the chart migration must be reviewed before reconciliation. Native OIDC removes Dex from the login path. General Argo roles remain on the general workers; only the assigned Redis voters retain quorum-taint access. The Redis proxies use two replicas restricted to the general workers. Authentication still depends on Authentik and PostgreSQL promotion; failed in-progress requests may require a retry.
Failure scenarios
| Failure | Expected behavior and remaining dependency |
|---|---|
| One main worker | Surviving API/rendering replicas and direct OIDC can serve requests; replacement replicas may remain Pending until the failed general worker returns; RTX is not overflow capacity. Authentik primary loss requires database promotion, and an affected controller shard must be reassigned after missed heartbeats. Already-running applications normally do not stop just because Argo cannot reconcile them. |
| RTX worker only | A Redis HA member may use the tainted worker because of its toleration. The whole RTX host also carries the legacy external Kubernetes API endpoint. Configure the optional Talos API VIP to remove that external-client dependency; in-cluster API discovery has a separate path. |
| A second failure before recovery | Outside the stated single-failure envelope; assess remaining data copies, quorum, endpoints, and capacity before further maintenance. |
An RTX worker VM failure is not the same as an RTX Proxmox host failure. The latter also removes its control-plane VM and, unless the optional Talos VIP is enabled, the configured external API address. Read the physical failure-domain explanation before making a whole-host HA claim.
Upgrades and voluntary maintenance
Server/repo-server/proxy and application-controller rollouts use zero surge and one unavailable. This lets each two-replica hard anti-affinity group roll across the two general workers without waiting for an impossible third placement; one controller may be unavailable briefly during rollout. Server, repo-server, and application-controller PDBs require one available replica during voluntary eviction. Plugin subPath changes require repo-server replacement. PDBs do not prevent abrupt node failure or override a Deployment rollout strategy.
What prevents a stronger HA claim
Git connectivity, the legacy external API endpoint when VIP is unset, auxiliary singletons outside the login path, and controller reassignment bound complete control-plane availability. A surviving web UI does not prove that manifests are being applied.
What would improve the availability contract
Configure the optional Talos API VIP, reserve eligible failover capacity, and measure both direct OIDC login and reconciliation of the affected cluster during a controlled worker loss. Follow the staged Dex migration in the administrator guide before switching an existing installation.
These are operational/design requirements, not changes made to the deployment by this documentation. The shared availability reference explains election, replication, durability, recovery time, and shared dependencies; the manifest links below identify this service’s source.
Configuration ownership
apps/argocd/ owns this service’s Kubernetes resources. Hostnames, addresses, versions, node names, and volume sizes belong in apps/variables.yaml. Runtime settings stored in a product database need that product’s backup and administration procedure.
Continue
Read the deployment guide for dependency order, initial credentials, and integration work. The official documentation explains the upstream product; the topology above describes this repository.