Argo CD: A GitOps Continuous Delivery Tool for Kubernetes – Architecture, Features, Installation, and Usage Guide

Argo CD is a Kubernetes‑native continuous deployment tool that follows the declarative GitOps model, automatically synchronizing and deploying applications whenever the Git repository changes.

It uses the Git repository as the single source of truth for the desired application state and supports multiple Kubernetes manifest types, including Kustomize, Helm charts, Ksonnet applications, Jsonnet files, plain YAML/JSON manifests, and custom config‑management plugins.

Architecture

Argo CD runs as a Kubernetes controller that continuously watches running applications, comparing the live state with the desired target state defined in the Git repo. When a drift is detected, the application is marked as OutOfSync , and Argo CD reports the differences while offering tools to sync the state manually or automatically.

The main components are:

API Service : a gRPC/REST service exposing interfaces for the Web UI, CLI, and CI/CD systems. It handles application management, status reporting, operation execution (sync, rollback, custom actions), repository and cluster credential storage, authentication/authorization, RBAC, and Git webhook listening.

Repository Service : an internal service that caches Git repositories locally and generates Kubernetes manifests based on the provided repository URL, revision, application path, and template configuration (parameters, Ksonnet environment, Helm values, etc.).

Application Controller : a Kubernetes controller that watches applications, detects OutOfSync states, and triggers synchronization, invoking user‑defined lifecycle hooks (PreSync, Sync, PostSync).

Features

Automatic deployment of applications to specified target environments.

Support for multiple configuration/templating tools (Kustomize, Helm, Ksonnet, Jsonnet, plain YAML).

Multi‑cluster management.

SSO integration (OIDC, OAuth2, LDAP, SAML 2.0, GitHub, GitLab, Microsoft, LinkedIn).

Multi‑tenant RBAC policies.

Rollback to any configuration stored in Git.

Health status analysis of application resources.

Automatic config detection and visualization.

Manual or automatic synchronization to the desired state.

Web UI providing a real‑time view of application activity.

CLI for automation and CI integration.

Webhook integration (GitHub, BitBucket, GitLab) and AccessTokens for automation.

PreSync, Sync, PostSync hooks for complex deployment strategies (blue/green, canary).

Audit of application events and API calls.

Prometheus metrics.

Core Concepts

Application : a CRD representing a set of Kubernetes resources defined by manifests.

Application source type : the tool used to build the application (e.g., Helm, Kustomize).

Target state : the desired state expressed in the Git repository.

Live state : the actual state of resources running in the cluster.

Sync status : indicates whether the live state matches the target state.

Sync : the process of reconciling the live state to the target state.

Health : the overall health of the application (running, degraded, etc.).

Installation

Prerequisite: a Kubernetes cluster reachable via kubectl . Install the latest stable version (v2.0.4) with:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.0.4/manifests/install.yaml

For a high‑availability deployment, use the HA manifest:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.0.4/manifests/ha/install.yaml

After installation, verify the pods:

kubectl get pods -n argocd

You can disable authentication for simple use cases with the --disable-auth flag via a patch to the argocd-server deployment.

Install the CLI by downloading the latest release:

VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
argocd version

The initial admin password is stored in the secret argocd-initial-admin-secret in the argocd namespace:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo

Log in via the UI ( argocd.k8s.local ) or CLI:

argocd login argocd.k8s.local

Cluster Configuration

To deploy to external clusters, register the cluster with Argo CD using its API server address (e.g., https://kubernetes.default.svc ) and the command:

argocd cluster add CONTEXTNAME

Creating an Application

Example repository: https://github.com/argoproj/argocd-example-apps.git . Create the app via CLI:

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

Or create it through the Web UI by clicking +New App , filling in the repository URL, revision, path, and destination cluster/namespace.

Deploying the Application

Since the sync policy is set to Manual , the app remains OutOfSync until you trigger a sync.

Sync via CLI:

argocd app sync guestbook

Or click the Sync button in the UI. After synchronization, the resources appear in the cluster:

kubectl get pods
kubectl get svc

The article concludes with a preview of upcoming Argo CD practices.