ArgoCD GitOps Deployment Guide

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes. It automatically syncs and deploys applications from Git repositories to your Kubernetes clusters. This guide will help you understand ArgoCD and set up your first GitOps deployment.

Quick Start for Beginners

If you're new to ArgoCD, here's a simple example to get you started:

1. Install ArgoCD in your Kubernetes cluster
2. Create an Application that points to your Git repository
3. Watch ArgoCD sync your application automatically

# Example ArgoCD Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-username/your-repo
    targetRevision: HEAD
    path: k8s-manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

What is ArgoCD

ArgoCD provides:

• GitOps Workflow: Uses Git as the single source of truth
• Automatic Synchronization: Continuously monitors and syncs applications
• Multi-Environment Support: Deploy to multiple clusters and namespaces
• Web UI: Visual interface for managing applications
• CLI Tools: Command-line interface for automation
• Rollback Capabilities: Easy rollback to previous versions

What is GitOps

GitOps is a methodology where:

• Git is the source of truth for your infrastructure and applications
• Declarative descriptions define the desired state
• Automated processes ensure the actual state matches the desired state
• Continuous monitoring detects and corrects drift

GitOps Benefits

• Version Control: All changes are tracked in Git
• Audit Trail: Complete history of deployments
• Collaboration: Team members can review changes via pull requests
• Security: Git's access controls apply to deployments
• Consistency: Same process across all environments

ArgoCD Architecture

Core Components

1. ArgoCD Server

• Web UI and API server
• Handles authentication and authorization
• Manages application state

2. ArgoCD Application Controller

• Monitors Git repositories
• Compares desired vs actual state
• Performs synchronization operations

3. ArgoCD Repository Server

• Caches Git repository data
• Provides repository access to other components

4. ArgoCD Dex Server

• Handles authentication (optional)
• Integrates with external identity providers

Installation

Using kubectl

# Create namespace
kubectl create namespace argocd

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

# Wait for pods to be ready
kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd

Using Helm

# Add ArgoCD Helm repository
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# Install ArgoCD
helm install argocd argo/argo-cd -n argocd --create-namespace

Access ArgoCD UI

# Port forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

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

Basic Concepts

Application

An Application in ArgoCD represents a deployment of an application from a Git repository to a Kubernetes cluster.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-application
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/repo
    targetRevision: HEAD
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: production

Project

A Project is a logical grouping of Applications with shared configuration and permissions.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
spec:
  description: "My application project"
  sourceRepos:
    - "https://github.com/example/*"
  destinations:
    - namespace: "production"
      server: https://kubernetes.default.svc
    - namespace: "staging"
      server: https://kubernetes.default.svc

Sync Policy

Defines how ArgoCD should synchronize the application.

syncPolicy:
  automated:
    prune: true # Remove resources not in Git
    selfHeal: true # Automatically fix drift
  syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground

Application Configuration

Source Configuration

source:
  repoURL: https://github.com/example/repo
  targetRevision: HEAD # Branch, tag, or commit
  path: k8s-manifests # Path to manifests in repo
  helm: # Helm-specific config
    valueFiles:
      - values.yaml
    parameters:
      - name: image.tag
        value: v1.0.0

Destination Configuration

destination:
  server: https://kubernetes.default.svc # Cluster URL
  namespace: production # Target namespace
  name: my-cluster # Cluster name (optional)

Sync Policy Options

syncPolicy:
  automated:
    prune: true # Delete resources not in Git
    selfHeal: true # Auto-sync when drift detected
  syncOptions:
    - CreateNamespace=true # Create namespace if missing
    - PrunePropagationPolicy=foreground
    - PruneLast=true
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

Common Use Cases

1. Simple Web Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/web-app
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: web-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

2. Multi-Environment Deployment

# Staging Environment
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-staging
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/app
    targetRevision: develop
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: staging
  syncPolicy:
    automated:
      prune: true

---
# Production Environment
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-production
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/app
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

3. Helm Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: helm-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/helm-charts
    targetRevision: HEAD
    path: charts/my-app
    helm:
      valueFiles:
        - values.yaml
        - values-production.yaml
      parameters:
        - name: image.tag
          value: v2.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: production

ArgoCD CLI Usage

Install ArgoCD CLI

# macOS
brew install argocd

# Linux
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

Common CLI Commands

# Login to ArgoCD
argocd login localhost:8080

# List applications
argocd app list

# Get application details
argocd app get my-app

# Sync application
argocd app sync my-app

# Create application
argocd app create my-app \
  --repo https://github.com/example/repo \
  --path k8s \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# Delete application
argocd app delete my-app

Best Practices

1. Repository Structure

Organize your Git repository with clear structure:

my-app/
├── k8s/
│   ├── base/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── kustomization.yaml
│   └── overlays/
│       ├── staging/
│       │   └── kustomization.yaml
│       └── production/
│           └── kustomization.yaml
├── helm/
│   └── my-app/
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
└── README.md

2. Use Projects for Organization

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: web-apps
  namespace: argocd
spec:
  description: "Web applications project"
  sourceRepos:
    - "https://github.com/company/web-*"
  destinations:
    - namespace: "web-*"
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ""
      kind: Namespace
  namespaceResourceWhitelist:
    - group: "apps"
      kind: Deployment
    - group: ""
      kind: Service

3. Implement Proper Sync Policies

syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground
    - RespectIgnoreDifferences=true

4. Use Health Checks

spec:
  source:
    repoURL: https://github.com/example/repo
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  healthChecks:
    - apiVersion: v1
      kind: Service
      name: my-service
      namespace: default

Troubleshooting

Common Issues

1. Application Stuck in Progressing State

# Check application status
argocd app get my-app

# Check events
kubectl get events -n argocd

# Check application controller logs
kubectl logs -n argocd deployment/argocd-application-controller

2. Sync Failures

# Check sync status
argocd app sync my-app --dry-run

# Force sync
argocd app sync my-app --force

# Check resource health
argocd app get my-app --show-resources

3. Repository Access Issues

# Test repository access
argocd repo get https://github.com/example/repo

# Add repository with credentials
argocd repo add https://github.com/example/repo \
  --username myuser \
  --password mypass

Debug Tips

1. Check Application Status: Use argocd app get <app-name> to see detailed status
2. Review Logs: Check ArgoCD controller and server logs
3. Validate Manifests: Ensure your Kubernetes manifests are valid
4. Test Repository Access: Verify ArgoCD can access your Git repository
5. Check Permissions: Ensure ArgoCD has proper RBAC permissions

Common Beginner Mistakes

1. Incorrect Repository URL

# ❌ Wrong - using SSH URL without proper setup
source:
  repoURL: git@github.com:example/repo.git

# ✅ Correct - use HTTPS URL
source:
  repoURL: https://github.com/example/repo

2. Missing Namespace

# ❌ Wrong - namespace doesn't exist
destination:
  server: https://kubernetes.default.svc
  namespace: my-namespace  # This namespace doesn't exist

# ✅ Correct - create namespace or use existing one
destination:
  server: https://kubernetes.default.svc
  namespace: default

3. Wrong Path Configuration

# ❌ Wrong - path doesn't exist in repository
source:
  repoURL: https://github.com/example/repo
  path: non-existent-path

# ✅ Correct - use actual path in repository
source:
  repoURL: https://github.com/example/repo
  path: k8s-manifests

Beginner Tips

1. Start Simple: Begin with basic applications before complex multi-environment setups
2. Use Web UI: The ArgoCD web interface is great for learning and debugging
3. Test Locally: Validate your Kubernetes manifests locally before committing
4. Monitor Sync Status: Always check if applications are syncing correctly
5. Use Projects: Organize applications using ArgoCD projects
6. Read Documentation: ArgoCD has excellent official documentation

Resources

• ArgoCD Official Documentation
• GitOps Principles
• ArgoCD GitHub Repository
• ArgoCD Best Practices
• Kubernetes Documentation

---

This documentation provides a comprehensive guide to ArgoCD GitOps deployment. For advanced configurations and enterprise features, refer to the official ArgoCD documentation.