Skip to content

Cloud-native GitOps with ArgoCD

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes. It synchronizes applications from Git repositories to your cluster automatically.

Overview

GitOps Principles: - Infrastructure and applications defined in Git - Git is the single source of truth - Automated synchronization detects and corrects drift - Full audit trail through Git history

Benefits: - Declarative application management - Version control for infrastructure - Automated deployments - Easy rollbacks - Better collaboration and compliance

Installation

Quick Start

# Create namespace
kubectl create namespace argocd

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

# Access the UI (port-forward)
kubectl port-forward svc/argocd-server -n argocd 8080:443

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

Visit https://localhost:8080 with admin and the password above.

helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd -n argocd --create-namespace \
  --values values.yaml

Use a clear separation between base manifests and environment-specific overlays:

gitops-repo/
├── README.md
├── base/                    # Base Kubernetes manifests
│   ├── namespace.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
├── overlays/                # Environment-specific patches
│   ├── dev/
│   │   ├── kustomization.yaml
│   │   └── replicas.yaml
│   ├── staging/
│   │   ├── kustomization.yaml
│   │   └── replicas.yaml
│   └── prod/
│       ├── kustomization.yaml
│       ├── replicas.yaml
│       └── ingress.yaml
└── argocd-apps/            # ArgoCD Application definitions
    ├── app-dev.yaml
    ├── app-staging.yaml
    └── app-prod.yaml

Creating an Application

Manual Creation via UI

  1. Navigate to Applications → + NEW APP
  2. Fill in details:
  3. Application name: my-app
  4. Project: default
  5. Repository URL: https://github.com/myorg/gitops-repo
  6. Revision: main
  7. Path: overlays/prod
  8. Cluster URL: https://kubernetes.default.svc
  9. Namespace: prod
  10. Click CREATE
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/gitops-repo
    targetRevision: main
    path: overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  syncPolicy:
    automated:
      prune: true      # Delete resources not in Git
      selfHeal: true   # Auto-sync on cluster drift
    syncOptions:
    - CreateNamespace=true

Apply with: 

kubectl apply -f argocd-apps/app-prod.yaml

Synchronization

Manual Sync

# Via CLI
argocd app sync my-app

# Via UI: Click "SYNC" button

Automatic Sync

syncPolicy:
  automated:
    prune: true       # Auto-prune resources not in Git
    selfHeal: true    # Auto-sync when cluster drifts

Webhook Trigger (Faster than Polling)

GitHub → Settings → Webhooks → Add webhook: - Payload URL: https://argocd.example.com/api/webhook - Content type: application/json - Trigger on: Push events

Best Practices

  1. Separate repos by concern:
  2. One repo for apps, one for infrastructure

  3. Cleaner permissions and CI/CD workflows

  4. Use Kustomize or Helm for overlays: 

    # kustomization.yaml
bases:
- ../../base
patchesStrategicMerge:
- replicas.yaml

  5. Implement RBAC: 

    apiVersion: v1
kind: AppProject
metadata:
  name: staging
spec:
  sourceRepos:
  - 'https://github.com/myorg/*'
  destinations:
  - namespace: 'staging'
    server: https://kubernetes.default.svc

  6. Monitor drift with notifications:

  7. Slack/Teams integration for sync failures

  8. Email alerts for manual interventions

  9. Use branch protection:

  10. Require PR reviews before merging to main
  11. Enforce tests before deploy

Troubleshooting

Issue Cause Solution
App stuck in "Syncing" Network issues or large deployments Check argocd-application-controller logs
"Repository not accessible" SSH key or credentials missing Register repo with SSH key in UI
Resources not syncing Path mismatch or missing namespace Verify Git path and namespace in spec
Drift detected constantly Auto-sync disabled Enable selfHeal: true

Advanced Configuration

Multiple Clusters

destinations:
- server: https://kubernetes.default.svc        # Local cluster
  namespace: prod
- server: https://staging-cluster.example.com   # Remote cluster
  namespace: prod

Notifications (Slack Example)

# Install Notifications extension
kubectl apply -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml

# Configure Slack integration (see ArgoCD docs)

See Also