ArgoCD & GitOps:

 

ArgoCD & GitOps: The Complete Guide to GitOps on Kubernetes

📅 Published: July 2026
⏱️ Estimated Reading Time: 25 minutes
🏷️ Tags: GitOps, Argo CD, Kubernetes, Continuous Delivery, DevOps

---

Introduction: What is GitOps?

GitOps is a way of managing infrastructure and applications where Git is the single source of truth. Everything you deploy—applications, configurations, infrastructure—is defined in Git. The cluster continuously pulls from Git and ensures the running state matches what's declared.

Think of GitOps as a thermostat for your infrastructure. You set the desired temperature (your Git repository), and the system continuously works to maintain it. If someone manually changes the temperature (makes a change directly in the cluster), the thermostat notices the drift and corrects it.

Why GitOps matters:

• Auditability: Every change is in Git, with commit history, PR reviews, and approvals

• Consistency: Environments always match their declared configuration

• Fast rollbacks: Revert a commit, and the cluster follows

• Security: Reduced direct cluster access, no stored credentials in CI/CD

• Self-healing: The cluster automatically fixes drift and manual changes

Key GitOps principles:

Principle	Description
Declarative	Entire system defined in code
Versioned	Git is the source of truth
Automated	Changes apply automatically
Continuous	Drift detection and correction
Auditable	Full history of every change

---

Part 1: What is Argo CD?

Argo CD is a declarative, GitOps continuous delivery tool specifically designed for Kubernetes. It continuously monitors your cluster and compares the live state against the desired state defined in your Git repository.

If the live state deviates (OutOfSync), Argo CD can either alert you or automatically sync the cluster back to the desired state.

Why Argo CD stands out:

• Kubernetes-native: Built specifically for K8s, not an afterthought

• Multi-tool support: Plain YAML, Kustomize, Helm, Jsonnet

• Multi-cluster: Manage deployments across many clusters

• Visual UI: Real-time view of application health and sync status

• Pull-based: Cluster pulls from Git, no need to open inbound ports

• Audit trail: Complete history of events and API calls

---

Part 2: Argo CD Architecture

Core Components

Argo CD runs as a set of controllers and services in your cluster:

text

┌─────────────────────────────────────────────────────────────────┐
│                        Argo CD Cluster                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │               Application Controller                     │    │
│  │  Monitors apps, compares live vs desired state          │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │                 API Server                               │    │
│  │  Web UI, CLI, and API endpoints                         │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │              Repository Server                           │    │
│  │  Caches Git repos, generates manifests                  │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │                 Redis                                    │    │
│  │  In-memory cache for manifest generation                │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │              Dex Server                                  │    │
│  │  OpenID Connect provider (SSO integration)             │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │          Notifications Controller                        │    │
│  │  Sends alerts to Slack, Email, Webhooks                │    │
│  ├─────────────────────────────────────────────────────────┤    │
│  │         ApplicationSet Controller                        │    │
│  │  Automates multi-cluster, multi-environment apps       │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

How Argo CD Works

The GitOps loop works like this:

1. Declare: You define your application manifests in Git

2. Pull: Argo CD pulls the manifests from Git

3. Compare: Argo CD compares Git state against running cluster state

4. Detect: If there's drift, application shows as OutOfSync

5. Sync: You sync manually or automatically to reconcile

6. Monitor: Argo CD continuously watches for new changes

Pull-based architecture: Unlike traditional CI/CD (push-based), Argo CD uses a pull-based model. The cluster initiates the connection to Git, not the other way around. This is more secure because you don't need to open inbound firewall ports or grant Git repositories access to your private clusters.

---

Part 3: Installing Argo CD

Prerequisites

Before you start, you need:

• A running Kubernetes cluster (Minikube, Kind, or any cloud cluster)

• kubectl configured to talk to your cluster

• A Git repository with your application manifests

Option 1: Quick Install

bash

# Create the argocd namespace
kubectl create namespace argocd

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

# Check that all pods are running
watch kubectl get pods -n argocd

Access the Argo CD UI

Port-forward to access the UI:

bash

# Forward the Argo CD server port
kubectl port-forward svc/argocd-server -n argocd 8080:443

Then open your browser to https://localhost:8080.

Get the initial admin password:

bash

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

Login with username admin and the retrieved password. Change the password immediately.

Option 2: Install via CLI

bash

# Install Argo CD CLI
brew install argocd  # macOS
# or download from releases page

# Login
argocd login localhost:8080 --username admin --password <your-password> --insecure

Option 3: Managed Argo CD (Azure)

Azure provides Argo CD as a managed cluster extension, which simplifies installation and lifecycle management. It also integrates with Microsoft Entra ID for SSO and supports workload identity federation for accessing Azure resources like ACR without storing long-lived secrets.

---

Part 4: Creating Your First Application

Prepare Your Git Repository

Create a GitHub repo with Kubernetes manifests. Example deployment.yaml and service.yaml:

deployment.yaml:

yaml

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

service.yaml:

yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: LoadBalancer

Push these files to your repository.

Create an Application via Web UI

1. In the Argo CD UI, click New App

2. Fill in the details:

Field	Value
Application Name	nginx-app
Project	default
Repository URL	your GitHub repo
Revision	HEAD
Path	path/to/manifests
Cluster	https://kubernetes.default.svc
Namespace	default
Sync Policy	Manual (for now)

3. Click Create

Create an Application via CLI

bash

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

Sync (Deploy) the Application

After creation, the app shows as OutOfSync—it hasn't been deployed yet.

Sync via UI:

1. Click on the app

2. Click Sync → Synchronize

Sync via CLI:

bash

argocd app sync guestbook

---

Part 5: GitOps in Action

Auto-Sync

Configure Argo CD to automatically sync when Git changes.

In the UI, when creating the application, set:

• Sync Policy: Automated

• Prune Resources: Yes (deletes resources removed from Git)

• Self-Heal: Yes (fixes manual changes)

Test it:

1. Edit deployment.yaml, change replicas from 2 to 3

2. Push to Git

3. Argo CD detects the change and auto-syncs

4. Run kubectl get deployment nginx-deployment to confirm

Self-Heal

If someone manually changes something in the cluster, Argo CD reverts it.

Test it:

bash

# Manually scale the deployment
kubectl scale deployment nginx-deployment --replicas=5

# Check what Argo CD does
kubectl get deployment nginx-deployment
# After a few seconds, Argo CD reverts it back

Auto-Prune

If you delete a resource from Git, Argo CD removes it from the cluster.

Test it:

1. Delete service.yaml from Git

2. Push the change

3. The service is automatically removed from the cluster

---

Part 6: Advanced Patterns

ApplicationSet for Multi-Cluster Deployments

ApplicationSet automates creating applications across multiple clusters and environments.

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
spec:
  generators:
  - list:
      elements:
      - cluster: staging
        url: https://staging-cluster-api
      - cluster: production
        url: https://prod-cluster-api
  template:
    metadata:
      name: '{{cluster}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/guestbook.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{url}}'
        namespace: default

Helm with GitOps

Helm charts integrate seamlessly with GitOps. Argo CD can render Helm charts directly from Git.

yaml

spec:
  source:
    repoURL: https://github.com/org/my-app.git
    targetRevision: HEAD
    chart: my-app-chart
    helm:
      valueFiles:
        - values-production.yaml

Sync Hooks for Complex Rollouts

Use PreSync, Sync, and PostSync hooks for blue/green or canary deployments.

yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: myapp:latest
        command: ["/migrate-db.sh"]
      restartPolicy: Never

---

Part 7: Argo CD vs Other GitOps Tools

Feature	Argo CD	Flux
UI	✅ Native Web UI	❌ Limited
Multi-cluster	✅ ApplicationSet	✅ Kustomize/Helm
SSO Integration	✅ OIDC, SAML, LDAP	✅ OIDC
Rollback	✅ Any commit	✅ Any commit
Webhook support	✅ GitHub, GitLab, Bitbucket	✅ GitHub, GitLab
Helm	✅ Supported	✅ Supported
Kustomize	✅ Supported	✅ Supported
Pull-based security	✅ Yes	✅ Yes

Argo CD is generally preferred when you need a rich UI, advanced multi-cluster management, and deep integration with CI/CD systems. Flux is simpler and often chosen for lightweight setups.

---

Argo CD Commands Cheat Sheet

bash

# Get application status
argocd app list
argocd app get guestbook

# Sync an application
argocd app sync guestbook

# Rollback to a previous version
argocd app rollback guestbook 2

# View application history
argocd app history guestbook

# Set auto-sync policy
argocd app set guestbook --sync-policy automated --auto-prune --self-heal

# Login via CLI
argocd login localhost:8080 --username admin --password <pass>

# Change admin password
argocd account update-password

---

GitOps Best Practices

Structure Your Repositories

• Single repo per environment: Separate dev, staging, prod

• Directory-per-application: Keep manifests organized

• Kustomize/Helm overlays: Manage environment differences

Security

• Use workload identity federation instead of long-lived secrets

• Integrate with SSO for authentication

• Use RBAC to control who can sync what

• Never store secrets in plain Git—use Sealed Secrets or External Secrets

Observability

• Monitor application health status in Argo CD UI

• Set up notifications for sync failures

• Audit logs for all API calls and events

---

Summary

Concept	Description
GitOps	Git as the single source of truth for infrastructure and applications
Argo CD	Kubernetes-native GitOps continuous delivery tool
Pull-based	Cluster pulls from Git (more secure than push)
Drift detection	Argo CD continuously monitors and fixes drift
ApplicationSet	Multi-cluster, multi-environment automation
Sync hooks	Pre/Post hooks for complex rollouts

GitOps with Argo CD transforms how you deploy applications on Kubernetes. It makes deployments auditable, version-controlled, and self-healing. Start small with a single application, then expand to multi-cluster and multi-environment management.

---

Learn More

Practice GitOps with Argo CD in our interactive labs:
https://devops.trainwithsky.com