Mastering Argo CD: A Complete Guide to GitOps on Kubernetes

Background

GitOps was introduced in August 2017 as a workflow that treats a Git repository as the single source of truth for Kubernetes application definitions, configurations, and environments. By storing the desired state in Git, deployments become automated, auditable, and reproducible.

Argo CD Overview

What is Argo CD?

Argo CD is a declarative, GitOps‑based continuous delivery engine for Kubernetes. It continuously monitors a Git repository, compares the live cluster state with the desired state, and can automatically or manually synchronize the two.

Supported Manifest Sources

kustomize applications

Helm charts

Ksonnet applications

Jsonnet files

Plain directories of YAML/JSON manifests

Custom config‑management plugins

Installation and Deployment

1. Install Argo CD in a Kubernetes cluster

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

This creates the argocd namespace and deploys all core components (API server, repo server, controller, and UI).

2. Install the Argo CD CLI

Download the latest binary from the official releases page:

macOS:

brew tap argoproj/tap
brew install argoproj/tap/argocd

Linux:

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

3. Access the Argo CD API server

The API server is not exposed by default. Use port‑forwarding to reach it locally:

kubectl port-forward svc/argocd-server -n argocd --address 0.0.0.0 8080:443

4. Log in with the CLI

The initial admin password is the name of the argocd-server pod. Retrieve it and log in:

# Retrieve pod name
POD=$(kubectl get pod -n argocd -l app.kubernetes.io/name=argocd-server -o jsonpath="{.items[0].metadata.name}")
# Log in (accept insecure TLS for a local test environment)
argocd login localhost:8080 --username admin --password $POD --insecure

Change the password after the first login:

argocd account update-password

5. Register an external cluster (optional)

argocd cluster add

This command creates a ServiceAccount argocd-manager in the target cluster’s kube-system namespace and binds it to a cluster‑admin role, allowing Argo CD to manage resources in that cluster.

6. Create an Application from a Git repository

Example using the official guestbook demo repository:

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

7. Sync (deploy) the Application

# Inspect status
argocd app get guestbook
# Synchronize manifests to the cluster
argocd app sync guestbook

After a successful sync, verify the resources:

kubectl get all -l app=guestbook-ui

Declarative Application Definition

An Argo CD application can be expressed as a native Kubernetes Custom Resource (CRD). The minimal manifest is:

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

Additional fields (e.g., sync policy, health checks, resource pruning) are documented in the official application.yaml reference.

Core Architecture

Argo CD consists of three main components:

API Server – Exposes gRPC/REST endpoints used by the UI, CLI, and CI/CD pipelines. Handles authentication, RBAC, repository access, and webhook listening.

Repository Server – Caches Git repositories, renders manifests (Helm, Kustomize, Jsonnet, etc.), and provides them to the controller.

Application Controller – A Kubernetes controller that continuously watches live resources, compares them with the desired state from Git, reports out‑of‑sync conditions, and executes sync or custom hooks.

Reference URLs

Argo CD official documentation: https://argoproj.github.io/argo-cd/

GitHub releases (binary downloads): https://github.com/argoproj/argo-cd/releases/latest