What Is Argo CD? Architecture and Components of the GitOps Continuous Delivery Tool

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes that continuously monitors Git repositories to ensure the live cluster state matches the desired state defined in your manifests.

Argo CD is a declarative, GitOps-based continuous delivery solution designed specifically for Kubernetes environments. According to the argoproj/argo-cd source code, it automates the deployment of applications by continuously watching Git repositories containing your desired state and synchronizing changes to the target clusters. This approach eliminates the need for custom deployment scripts and provides a reliable, auditable pipeline for managing Kubernetes infrastructure and applications.

Core Architecture Components

Argo CD consists of five tightly-coupled components that run as containers within the argocd namespace. They communicate via in-cluster Service objects using gRPC/REST and Kubernetes APIs.

API Server

The API Server exposes a gRPC/REST API used by the Web UI, CLI, and automation tools. It handles application CRUD operations, sync and rollback actions, credential storage, authentication, RBAC, and Git webhook listening. In server/api/server.go, the server implementation manages these endpoints and serves as the central communication hub for all external interactions.

Repository Server

The Repository Server maintains a local cache of Git repositories that hold application manifests. It generates the final Kubernetes manifests given a repository URL, revision, path, and optional templating parameters such as Helm values, Jsonnet, or Kustomize overlays. The core logic resides in reposerver/server.go, which handles manifest generation and caching strategies.

Application Controller

The Application Controller is a Kubernetes controller that continuously compares the live state of each application against the desired state from the repository. It detects OutOfSync conditions and can auto-sync, invoke user-defined lifecycle hooks (PreSync, Sync, PostSync), and enforce health checks. The main reconciliation loop is implemented in controllers/application_controller.go, where the controller watches Application custom resources and triggers deployments when drift is detected.

Web UI and CLI

The Web UI and CLI provide human-friendly interfaces to view application status, trigger manual syncs, and manage projects and clusters. The UI communicates directly with the API Server, while the CLI (argocd) is a thin wrapper around the same API. The entry point for both components is located in cmd/main.go, which initializes the respective binaries.

Dex and Identity Providers

Dex and other identity providers enable optional OIDC-based single sign-on (SSO) through providers like GitHub, Google, or LDAP. This integration supports group-based RBAC and is handled via the API Server’s authentication layer, allowing organizations to enforce existing security policies.

How Argo CD Works: The GitOps Loop

The system operates on a continuous reconciliation loop that ensures cluster state matches Git state:

1. Declare the desired state of an application in a Git repository containing manifests, Helm charts, or Kustomize overlays.
2. Configure an Argo CD Application resource that points to that repository, specific revision, and path.
3. The Application Controller watches the repository via the Repository Server and monitors the live cluster state.
4. When drift is detected, the controller marks the application as OutOfSync and optionally auto-syncs by applying the generated manifests.
5. Sync status, health, and events are stored as Kubernetes custom resources (Application, AppProject) and surfaced via the API Server and UI.

Because the desired state lives in Git, every change is version-controlled, auditable, and can be rolled back by reverting a commit.

Configuring Applications

You can define applications declaratively using YAML or imperatively via the CLI.

Create an Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argo-cd-example-apps
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Apply it using the CLI:

argocd app create guestbook \
  --repo https://github.com/argoproj/argo-cd-example-apps \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace guestbook \
  --sync-policy automated

Check deployment status:

argocd app get guestbook

These commands invoke the API Server, which triggers the Application Controller to reconcile the desired state.

Key Source Files

• cmd/main.go – Entry point for the argocd CLI and server binaries.
• server/api/server.go – Implements the gRPC/REST API used by the UI and CLI.
• reposerver/server.go – Core of the Repository Server handling Git caching and manifest generation.
• controllers/application_controller.go – Main reconciliation loop for Application resources.
• docs/operator-manual/architecture.md – High-level architecture documentation and component diagrams.

Summary

• Argo CD is a declarative GitOps tool that automates Kubernetes deployments by syncing cluster state with Git repositories.
• The architecture consists of five core components: API Server, Repository Server, Application Controller, Web UI/CLI, and optional Dex integration for SSO.
• The reconciliation loop continuously detects drift between live and desired states, supporting auto-sync, health checks, and lifecycle hooks.
• All components run as containers within the argocd namespace and communicate via Kubernetes Services and gRPC/REST APIs.

Frequently Asked Questions

What is Argo CD used for?

Argo CD is used to automate the deployment of Kubernetes applications using GitOps principles. It eliminates manual kubectl commands and custom scripts by automatically applying changes from Git repositories to your clusters, ensuring that your infrastructure remains synchronized with your version-controlled manifests.

How does Argo CD differ from traditional CI/CD tools?

Traditional CI/CD tools typically push changes to clusters using imperative commands within pipelines. Argo CD operates on a pull-based model where the Application Controller continuously monitors repositories for changes and pulls them into the cluster. This agent-based approach is more secure, provides better drift detection, and creates a clear separation between artifact building (CI) and deployment (CD).

What manifest formats does Argo CD support?

Argo CD supports plain YAML or JSON manifests, Helm charts, Kustomize overlays, Jsonnet, and other configuration tools. The Repository Server handles the rendering of these formats into standard Kubernetes manifests before the Application Controller applies them to the cluster.

Where is the Argo CD API Server implemented?

The API Server is implemented in server/api/server.go within the argoproj/argo-cd repository. This file contains the gRPC and REST endpoint definitions that handle authentication, application management, and serve as the integration point for the Web UI and CLI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}