# Argo CD GitOps

> Declarative continuous delivery for Kubernetes with GitOps workflow.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: argocd-server, argocd-repo-server, argocd-controller, redis, dex
- Tags: gitops, kubernetes, argocd, cd, deployment
- Source: https://docker.recipes/devops/argo-cd-gitops

## Overview

Argo CD is a declarative GitOps continuous delivery tool that brings Git-driven deployment workflows to Kubernetes environments. Originally developed by Intuit and now a CNCF graduated project, Argo CD implements the GitOps methodology where Git repositories serve as the single source of truth for application configurations and deployment states. This approach revolutionizes how teams manage Kubernetes deployments by eliminating manual kubectl commands and configuration drift through automated synchronization between Git repositories and cluster states.

This comprehensive stack combines Argo CD's core components with Redis for caching and Dex for identity management to create a production-grade GitOps platform. The argocd-server provides the web UI and API gateway, argocd-repo-server handles Git repository operations and manifest generation, while argocd-application-controller continuously monitors and reconciles application states. Redis serves as the distributed cache and session store, significantly improving performance for large-scale deployments, while Dex enables enterprise-grade authentication through OIDC, SAML, and other identity providers.

This configuration is ideal for DevOps teams, platform engineers, and organizations seeking to implement mature GitOps practices without the complexity of manual Kubernetes installation. Unlike traditional CI/CD tools that push changes to environments, Argo CD pulls desired state from Git repositories, providing better security, auditability, and disaster recovery capabilities. The stack particularly excels in multi-cluster environments where centralized application lifecycle management and consistent deployment practices are critical for operational efficiency.

## Features

- Declarative GitOps workflow with Git repositories as the source of truth for all deployments
- Real-time application health monitoring with detailed resource status and sync state visibility
- Multi-cluster deployment management from a single Argo CD instance with cluster credential isolation
- Automated drift detection and self-healing capabilities when cluster state deviates from Git
- Pre-sync and post-sync hooks for database migrations, testing, and custom deployment logic
- Role-based access control with project-level permissions and Git repository restrictions
- Application rollback capabilities with Git history-based version management
- SSO integration through Dex supporting OIDC, SAML, GitHub, GitLab, and enterprise identity providers

## Use cases

- Multi-environment Kubernetes deployments with promotion pipelines from dev to staging to production
- Microservices architecture deployment where multiple teams manage independent applications through Git
- Infrastructure as Code management for Kubernetes resources including ingress controllers, monitoring, and security policies
- Multi-cluster application deployment across different cloud providers or regions with consistent configurations
- Disaster recovery scenarios where entire cluster states can be reconstructed from Git repository definitions
- Compliance-driven environments requiring audit trails and approval workflows for production changes
- Development team self-service platforms where developers deploy applications without direct cluster access

## Prerequisites

- Minimum 2GB RAM allocated to Docker (1GB for Argo CD components, 512MB for Redis, plus system overhead)
- Access to Kubernetes cluster with kubectl configured (required for Argo CD to manage applications)
- Git repository with Kubernetes manifests, Helm charts, or Kustomize configurations for applications
- Port 8080 available for Argo CD web interface access
- Basic understanding of Kubernetes concepts including deployments, services, and YAML manifests
- Git repository access credentials and webhook configuration knowledge for automated sync triggers

## docker-compose.yml

```yaml
services:
  argocd-server:
    image: quay.io/argoproj/argocd:v2.9.3
    container_name: argocd-server
    command: argocd-server --staticassets /shared/app
    environment:
      - ARGOCD_SERVER_INSECURE=true
      - REDIS_SERVER=redis:6379
    volumes:
      - argocd-data:/home/argocd
      - ./repositories:/home/argocd/repo
    ports:
      - "8080:8080"
    depends_on:
      - redis
    networks:
      - argocd-network
    restart: unless-stopped

  argocd-repo-server:
    image: quay.io/argoproj/argocd:v2.9.3
    container_name: argocd-repo-server
    command: argocd-repo-server --redis redis:6379
    volumes:
      - argocd-repo:/home/argocd
    depends_on:
      - redis
    networks:
      - argocd-network
    restart: unless-stopped

  argocd-application-controller:
    image: quay.io/argoproj/argocd:v2.9.3
    container_name: argocd-controller
    command: argocd-application-controller --redis redis:6379 --repo-server argocd-repo-server:8081
    volumes:
      - argocd-controller:/home/argocd
    depends_on:
      - argocd-repo-server
    networks:
      - argocd-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: argocd-redis
    volumes:
      - redis-data:/data
    networks:
      - argocd-network
    restart: unless-stopped

  dex:
    image: ghcr.io/dexidp/dex:v2.37.0
    container_name: argocd-dex
    command: dex serve /etc/dex/config.yaml
    volumes:
      - ./dex-config.yaml:/etc/dex/config.yaml:ro
    networks:
      - argocd-network
    restart: unless-stopped

volumes:
  argocd-data:
  argocd-repo:
  argocd-controller:
  redis-data:

networks:
  argocd-network:
    driver: bridge
```

## .env

```bash
# Argo CD
# Note: This is a simplified Docker Compose setup
# For production, deploy to Kubernetes

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

## Usage notes

- Web UI at http://localhost:8080
- Login: admin / (get from secret)
- GitOps continuous delivery
- Sync apps from Git repos
- Best run on Kubernetes

## Troubleshooting

- Application stuck in 'Unknown' health status: Check that Kubernetes cluster is accessible and kubectl context is properly configured in the cluster settings
- ComparisonError with 'unable to load data from /tmp/...' messages: Repository server cannot access Git repository, verify SSH keys or HTTPS credentials in repository configuration
- OutOfSync status despite no visible differences: Enable 'IgnoreExtraneous' resource option or check for resources created outside of Argo CD management
- Redis connection timeouts causing slow UI performance: Increase Redis memory allocation or check network connectivity between Argo CD components and Redis container
- Dex authentication failing with OIDC providers: Verify redirect URIs include http://localhost:8080/auth/callback in your identity provider configuration
- 'permission denied' errors during sync operations: Check that Argo CD service account has appropriate RBAC permissions in the target Kubernetes namespace

