Argo CD architecture and Applications¶
Status: AI draft, 2026-11-16. Not yet verified by me. Written from the Argo CD documentation; Argo CD was not installed for these notes, so the commands have no sample output.
In one line¶
Argo CD's repo server renders manifests from Git, its application controller compares them with the cluster and syncs differences, and its API server serves the UI and CLI. Each Application maps a Git path to a cluster namespace within an AppProject, and reports sync status and health separately.
The plain idea¶
Argo CD is the in-cluster agent from GitOps principles. You tell it, with an Application object, "this path in this Git repository should be running in this namespace of this cluster". From then on it keeps comparing the two, shows you any difference, and (if you allow it) applies Git's version.
How it works¶
Components¶
flowchart TD
U["UI, argocd CLI, CI"] --> API["API server: auth (SSO via Dex),<br/>RBAC, serves UI and API"]
API --> AC["Application controller: compares desired<br/>with live state, runs syncs"]
AC --> RS["Repo server: clones Git, renders<br/>Kustomize, Helm or plain YAML"]
RS --> G["Git repositories,<br/>Helm or OCI registries"]
AC --> K["Kubernetes API of each<br/>destination cluster"]
AC --- R["Redis: cache"]
AS["ApplicationSet controller:<br/>generates Applications"] --> AC
| Component | Job |
|---|---|
| API server | gRPC and REST API behind the UI and CLI; authentication, RBAC, webhooks from Git providers |
| Repo server | Keeps a local cache of repositories and generates manifests for a given revision, path and tool settings |
| Application controller | A Kubernetes controller that watches Applications, compares desired and live state, syncs, and runs hooks |
| ApplicationSet controller | Generates Applications from templates (App-of-apps and ApplicationSets) |
| Redis | Cache for rendered manifests and cluster state |
| Dex | Optional SSO connector (OIDC, SAML, GitHub, and others) |
By default Argo CD polls Git every 3 minutes (120 seconds plus up to 60 seconds of jitter); a webhook from the Git provider makes it react at once.
The Application¶
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: sample-app-prod
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: team-a
source:
repoURL: https://git.example.com/platform/config-repo.git
targetRevision: main
path: apps/sample-app/overlays/prod
destination:
server: https://kubernetes.default.svc
namespace: team-a
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
| Field | Meaning |
|---|---|
source |
Repository, revision (branch, tag or commit) and path; Helm or Kustomize settings when needed. sources allows several, such as a chart plus a values repository |
destination |
The cluster (by API URL or registered name) and namespace |
project |
The AppProject that limits what this Application may do |
syncPolicy |
Manual by default; automated with prune and selfHeal options (Sync, hooks and waves) |
finalizers |
Whether deleting the Application also deletes its resources (Deletion, finalizers and safe cleanup) |
Sync status vs health status¶
| Sync status | Meaning |
|---|---|
Synced |
Live resources match what Git renders |
OutOfSync |
Something differs: a new commit, or a change made in the cluster |
Unknown |
Argo CD could not compare (often a rendering or repository error) |
| Health status | Meaning |
|---|---|
Healthy |
Resources work as expected (Deployment fully rolled out, Service has endpoints) |
Progressing |
Not healthy yet but may become so (a rollout in progress) |
Degraded |
Failed: pods crash-looping, a Job failed |
Suspended |
Paused, such as a suspended CronJob or a paused rollout |
Missing |
Defined in Git but not present in the cluster |
The two are independent: an app can be Synced and Degraded (Git's version is applied and is broken) or OutOfSync and Healthy (someone scaled it by hand, and it works). Health is computed from built-in checks per kind, extendable with custom Lua health checks for CRDs.
AppProjects as boundaries¶
An AppProject is the tenancy and safety boundary:
sourceRepos: which repositories its Applications may use.destinations: which clusters and namespaces they may deploy to.- Allowed or denied resource kinds, for example no cluster-scoped resources for application teams.
roles: project-level RBAC for the UI and CLI, mapped to SSO groups.
The built-in default project allows everything; real teams get their own projects.
From commit to cluster¶
sequenceDiagram
participant G as Git
participant A as Argo CD
participant K as Cluster
G->>A: webhook, or poll<br/>every 3 minutes
A->>A: repo server renders<br/>the new revision
A->>K: compare with live objects
A->>A: OutOfSync
A->>K: auto-sync: apply in<br/>phase and wave order
K-->>A: health: Progressing,<br/>then Healthy
A concrete example¶
A platform team runs one Argo CD in a management cluster for three workload clusters:
- Workload clusters are registered as destinations; Argo CD reaches each API server with credentials scoped to what it deploys.
- Each team has an AppProject limiting it to its repository and its namespaces, and no cluster-scoped resources.
- SSO through the company identity provider; project roles map groups to read-only or sync rights.
- A Git webhook makes syncs start within seconds of a merge.
Why not just...?¶
- ...give every team cluster-admin in Argo CD's
defaultproject? Any team's Application could deploy anything anywhere, including over other teams' resources. AppProjects are the boundary. - ...look only at the sync status?
Syncedmeans "matches Git", not "works". Alert on health too. - ...run one Argo CD per cluster? That works and limits blast radius, but multiplies upgrades and dashboards. A central instance is easier to run but becomes a high-value target; choose deliberately.
Commands to know¶
These were not run for this page.
| Command | What it does |
|---|---|
argocd login <server> --sso |
Log in to the API server. |
argocd app list |
Applications with sync and health status. |
argocd app get sample-app-prod |
Details, resources, conditions and last sync result. |
argocd app diff sample-app-prod |
Live vs desired differences. |
argocd app sync sample-app-prod |
Sync now. |
argocd proj get team-a |
A project's allowed sources, destinations and kinds. |
kubectl get applications -n argocd |
Applications as Kubernetes objects. |
kubectl logs -n argocd deploy/argocd-repo-server |
Rendering errors (Helm, Kustomize). |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
Sync status Unknown, ComparisonError |
Repo server | Application conditions, repo server logs | Rendering failed (Helm or Kustomize error), repository unreachable, bad credentials |
| Merge done, Argo CD shows the old revision | Polling | Webhook settings | No webhook; wait up to about 3 minutes, or refresh |
application destination ... is not permitted in project |
AppProject | Project destinations | Namespace or cluster not allowed for that project |
Synced but Degraded |
Workload | Resource tree, pod events | The deployed version itself is broken (Troubleshooting playbook) |
Stuck Progressing |
Health | Which resource | Rollout waiting, or a CRD without a health check |
Interview questions¶
1. Describe Argo CD's main components.
Answer
- API server: UI, CLI and API, auth and RBAC.
- Repo server: clones repositories and renders manifests with Helm, Kustomize or plain YAML.
- Application controller: compares desired and live state, syncs and runs hooks; plus the ApplicationSet controller, Redis and optional Dex.
2. What does an Application define?
Answer
- Source: repository, revision and path (and Helm or Kustomize options).
- Destination: cluster and namespace.
- Project, sync policy, and optionally a finalizer for cascading deletion.
3. What is the difference between sync status and health status?
Answer
- Sync: does the live state match what Git renders?
- Health: are the resources working (rolled out, ready)?
- They are independent; you need both to know a deploy succeeded.
4. What is an AppProject for?
Answer
- A boundary for a team: allowed source repositories, destinations, and resource kinds.
- Project roles for RBAC, mapped to SSO groups.
- Prevents one team's Application deploying into another's namespace or creating cluster-wide objects.
5. How does a commit reach the cluster, and how fast?
Answer
- Argo CD learns of the commit by webhook (seconds) or by polling (about every 3 minutes by default).
- The repo server renders the new revision; the controller finds it OutOfSync.
- With auto-sync it applies in phase and wave order; health then moves from Progressing to Healthy.
6. An Application shows Unknown sync status with a comparison error. What do you check?
Answer
- The Application's conditions for the error text.
- Repo server logs: Helm or Kustomize rendering errors, missing values, bad chart versions.
- Repository access: credentials, network, the path and revision exist.
Try it¶
Without installing Argo CD:
- Write an Application for
apps/sample-app/overlays/stagingwith manual sync, and an AppProject that only allows the config repository and theteam-a-stagingnamespace. - For each of the four combinations of Synced/OutOfSync and Healthy/Degraded, write one real-world cause.
- Draw the component diagram from memory and mark which component needs Git credentials and which needs cluster credentials.
Zoom out¶
Argo CD is a Kubernetes controller like any other: custom resources, a reconcile loop, status conditions (CRDs, operators and admission webhooks). The next pages cover how it orders a sync, how it manages many applications, and how deletion and rollback work.