Argo CD: Complete GitOps Deployment Guide

Learn how to deploy applications to Kubernetes with Argo CD. This complete guide covers installation, Git repositories, Applications, synchronization, auto-sync, rollback, drift detection, secrets and production best practices.

Argo CD is a Kubernetes-native continuous delivery tool that follows the GitOps approach. Instead of deploying applications by manually running commands against a Kubernetes cluster, Argo CD monitors configuration stored in Git and synchronizes the cluster with the desired state.

This makes Git the source of truth for Kubernetes application configuration and gives teams a consistent way to deploy, monitor and roll back workloads.


Developer
    |
    v
Git Repository
    |
    | Desired State
    v
  Argo CD
    |
    | Synchronize
    v
Kubernetes Cluster
    |
    v
Application

In this guide, we will build a practical Argo CD deployment workflow from installation to production-oriented practices.

What Is Argo CD?

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It compares the desired configuration stored in a Git repository with the resources currently running in a Kubernetes cluster.

If the desired and actual states differ, Argo CD can report the difference and, when automated synchronization is enabled, apply the required changes.


Git
 |
 | Desired State
 v
Argo CD
 |
 | Compare
 v
Kubernetes
 |
 +---- Desired State
 |
 +---- Actual State

Why Use Argo CD?

Traditional Kubernetes deployments often rely on CI pipelines executing commands such as:


kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

This works, but as environments become larger, teams may need stronger controls around configuration, auditing, drift detection and deployment consistency.

Argo CD changes the deployment model:


Traditional

CI Pipeline
     |
     v
kubectl apply
     |
     v
Kubernetes


GitOps

Git Repository
     |
     v
Argo CD
     |
     v
Kubernetes

How Argo CD Works

Argo CD continuously monitors the desired state defined by the configured source repository and compares it with the resources running in the destination cluster.


             Git Repository
                    |
                    v
             Desired State
                    |
                    v
                Argo CD
                    |
              Compare State
                    |
             +------+------+
             |             |
          Synced        OutOfSync
             |             |
             v             v
          Nothing        Sync
                           |
                           v
                      Kubernetes

This reconciliation model is one of the fundamental concepts behind GitOps.

Argo CD Architecture

Argo CD consists of several components that work together to manage applications.


                    Git Repository
                         |
                         v
                 Argo CD Repo Server
                         |
                         v
                 Application Controller
                         |
             +-----------+-----------+
             |                       |
             v                       v
       Kubernetes API          Argo CD API
             |                       |
             v                       v
        Cluster Resources       Web UI / CLI

Application Controller

The application controller is responsible for monitoring applications and comparing their desired and live state.

Repo Server

The repository server retrieves application configuration and generates the Kubernetes manifests that Argo CD needs to compare and synchronize.

API Server

The Argo CD API server provides the interface used by the web UI, CLI and other integrations.

Repository

The Git repository contains the declarative configuration that defines the desired state of applications.

Prerequisites

Before installing Argo CD, you should have:

A running Kubernetes cluster.
kubectl configured to access the cluster.
A Git repository containing Kubernetes manifests or a supported templating format.
Basic knowledge of Kubernetes Deployments and Services.

You can verify Kubernetes access with:

kubectl get nodes

You should see the nodes belonging to your Kubernetes cluster.

Installing Argo CD

A common installation method is to create an Argo CD namespace and apply the official installation manifest.

kubectl create namespace argocd

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

Verify that the Argo CD pods are running:

kubectl get pods -n argocd

You should see components such as the API server, repository server and application controller.

Check Argo CD Services

kubectl get svc -n argocd

By default, the Argo CD API server is deployed as a Kubernetes Service. For a lab environment, you can temporarily expose it locally with port forwarding.

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

You can then access the Argo CD interface through the local port.

Installing the Argo CD CLI

The Argo CD CLI can be used to manage applications from the command line.

After installing the CLI for your operating system, verify it with:

argocd version --client

Getting the Initial Admin Password

A fresh Argo CD installation creates an initial administrator credential stored as a Kubernetes Secret.

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

The initial password should be changed and should not be treated as a long-term production credential.

Logging Into Argo CD

After port forwarding, the CLI can connect to the local endpoint.

argocd login localhost:8080 --username admin --insecure

For production environments, use a properly configured TLS endpoint instead of disabling certificate verification.

Creating a Git Repository

Argo CD needs a source containing the desired Kubernetes configuration.

A simple repository might look like:


gitops-repo/
├── deployment.yaml
├── service.yaml
└── namespace.yaml

Example Deployment:

<apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-app
  template:
    metadata:
      labels:
        app: web-app
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80>

Creating a Kubernetes Service

<apiVersion: v1
kind: Service
metadata:
  name: web-app
spec:
  selector:
    app: web-app
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP>

What Is an Argo CD Application?

An Argo CD Application is a Kubernetes custom resource that connects a Git source to a destination Kubernetes cluster and namespace.


Git Repository
      |
      +---- Path
      |
      v
Argo CD Application
      |
      +---- Destination Cluster
      |
      +---- Namespace

Creating an Argo CD Application

The following example connects a Git repository to a Kubernetes namespace:

<apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-app
  namespace: argocd
spec:
  project: default

  source:
    repoURL: https://github.com/example/gitops-repo.git
    targetRevision: HEAD
    path: .

  destination:
    server: https://kubernetes.default.svc
    namespace: web

  syncPolicy: {}>

Replace the repository URL with your actual Git repository.

Understanding the Application Manifest

repoURL

Defines the Git repository containing the application configuration.

targetRevision

Defines the Git revision Argo CD should track, such as a branch, tag or commit reference depending on the chosen workflow.

path

Specifies the directory inside the repository containing the application configuration.

destination

Defines the Kubernetes cluster and namespace where the application should be deployed.

Create the Application

Apply the Application resource to the Argo CD namespace:

kubectl apply -f application.yaml

Check the application:

argocd app list

Understanding Argo CD Application States

Argo CD exposes application health and synchronization information.

Synced

The live Kubernetes resources match the desired configuration.

OutOfSync

The live cluster state differs from the desired state stored in the configured source.

Healthy

The application's resources are considered healthy according to Argo CD's health assessment.

Degraded

One or more resources are not meeting the expected health conditions.

Manual Synchronization

With manual synchronization, Argo CD can detect a difference without immediately applying it.

argocd app sync web-app

This gives operators an explicit point at which the desired configuration is synchronized to the cluster.

Automatic Synchronization

Argo CD can automatically synchronize changes from the configured source.

<syncPolicy:
  automated:
    prune: true
    selfHeal: true>

This enables an automated reconciliation workflow.

Prune

Pruning allows Argo CD to remove resources that are no longer defined in the desired configuration, subject to the application's configuration and sync behavior.

Self-Heal

Self-healing allows Argo CD to reconcile certain manual changes made directly to the cluster when they cause the live state to differ from Git.

Understanding Drift Detection

Drift occurs when the Kubernetes cluster no longer matches the desired state stored in Git.


Git
 |
 | replicas: 3
 v
Argo CD
 |
 v
Kubernetes
 |
 | replicas: 5
 |
 +---- Drift

Argo CD can identify the difference and display the application as out of sync.

With self-healing enabled, Argo CD can reconcile the application back toward the declared configuration.

Deployment Workflow With Argo CD


Developer
    |
    v
Application Code
    |
    v
CI Pipeline
    |
    v
Container Registry
    |
    v
Update Image Reference
    |
    v
Git Repository
    |
    v
Argo CD
    |
    v
Kubernetes

In this architecture, CI is responsible for building and testing the application, while Argo CD handles deployment based on the desired configuration in Git.

Updating an Application Image

Suppose the application currently uses:

image: example/web:v1

The deployment process changes it to:

image: example/web:v2

After the Git change is committed and available to Argo CD, Argo CD detects the new desired state.


Git
 |
 | web:v2
 v
Argo CD
 |
 v
Kubernetes
 |
 v
Rolling Update

Using Tags vs Immutable Image References

Image references should be managed carefully in production.

Mutable tags such as latest can make deployments difficult to reproduce because the tag can point to different image content over time.

A versioned tag or immutable image reference provides stronger traceability.


Avoid:
image: example/web:latest

Prefer:
image: example/web:v2.4.1

Rollback With Git

One of the useful properties of GitOps is that deployment configuration is version controlled.


Commit A
  |
  v
web:v1

Commit B
  |
  v
web:v2

Commit C
  |
  v
web:v3

If version 3 introduces a problem, the desired configuration can be reverted to the known configuration from version 2.


Commit C
   |
   X
   |
   v
Revert
   |
   v
Commit B Configuration
   |
   v
Argo CD
   |
   v
Kubernetes

Always consider database migrations and other stateful changes separately when planning application rollbacks.

Argo CD Projects

Argo CD Projects can be used to organize applications and control what repositories, clusters and resources an application is allowed to use.


Project: Production
      |
      +---- Allowed Repository
      |
      +---- Allowed Cluster
      |
      +---- Allowed Namespaces
      |
      +---- Resource Restrictions

Projects are useful for establishing boundaries between teams and environments.

Managing Multiple Environments

A common GitOps setup contains separate configuration for development, staging and production.


gitops/
├── base/
│   ├── deployment.yaml
│   └── service.yaml
│
└── overlays/
    ├── dev/
    ├── staging/
    └── production/

Kustomize or Helm can be used to manage environment-specific differences.

Argo CD With Helm

Argo CD can deploy applications packaged as Helm charts.


Git
 |
 +---- Helm Chart
 |
 +---- values.yaml
 |
 v
Argo CD
 |
 v
Kubernetes

Environment-specific values can be maintained separately where appropriate.

Argo CD With Kustomize

Kustomize is another common approach for managing Kubernetes configuration in GitOps repositories.


base
 |
 +---- deployment.yaml
 +---- service.yaml
 |
 +----------------+
                  |
       +----------+----------+
       |                     |
      dev                  production

Managing Secrets

One of the most important GitOps security rules is: do not commit plaintext production secrets to Git.

A manifest such as the following should not be treated as a secure secrets-management strategy:


password: SuperSecretPassword

Production environments should use an appropriate secrets-management solution, encryption mechanism or external secret provider.