# Argo CD GitOps Stack

> Declarative GitOps continuous delivery tool for Kubernetes with UI and CLI.

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

## Overview

Argo CD is a declarative GitOps continuous delivery tool that revolutionizes Kubernetes application deployment by treating Git repositories as the single source of truth. Originally developed by Intuit and later donated to the CNCF, Argo CD has become the de facto standard for GitOps workflows, enabling teams to manage application lifecycle through Git commits rather than manual kubectl commands or CI/CD pipeline scripts. This comprehensive stack combines the core Argo CD components with Redis for state management and Dex for enterprise authentication, creating a production-ready GitOps platform that can manage thousands of applications across multiple Kubernetes clusters.

This multi-component architecture separates concerns effectively: argocd-server provides the web UI and API gateway, argocd-repo-server handles Git repository operations and manifest generation, argocd-controller continuously monitors and synchronizes application state, while Redis serves as the shared cache and session store. Dex integration enables SSO authentication through LDAP, SAML, OIDC, and other enterprise identity providers, eliminating the need for manual user management. Together, these services create a robust GitOps control plane that automatically detects configuration drift, provides detailed application health monitoring, and enables self-healing deployments.

Platform engineering teams, DevOps engineers managing multiple Kubernetes clusters, and organizations transitioning from traditional CI/CD to GitOps methodologies will find this stack invaluable. Unlike traditional deployment tools like Jenkins or GitLab CI that push changes to clusters, Argo CD operates on a pull model where the controller continuously polls Git repositories and automatically applies changes, providing superior security posture and audit trails. The declarative nature means application configurations are versioned, reviewable through standard Git workflows, and can be rolled back instantly, making it ideal for teams requiring compliance, auditability, and reliable deployment processes.

## Features

- GitOps-based deployments with Git repository as single source of truth for all application configurations
- Declarative application definitions using Kubernetes YAML, Helm charts, Kustomize, or Jsonnet templates
- Real-time application health monitoring with detailed resource status and sync state visualization
- Multi-cluster application management from a single control plane with cluster credential management
- Automated drift detection and self-healing capabilities to maintain desired state continuously
- SSO integration through Dex supporting LDAP, SAML, OIDC, GitHub, Google, and other identity providers
- Resource hooks for pre-sync, post-sync, and sync failure operations enabling advanced deployment patterns
- Application rollback capabilities with Git commit-level granularity for instant recovery from issues

## Use cases

- Multi-environment Kubernetes application delivery with promotion pipelines from dev to staging to production
- Multi-cluster application synchronization for hybrid cloud or disaster recovery scenarios across different regions
- Microservices deployment orchestration with dependency management and coordinated rollouts
- Infrastructure as Code management for Kubernetes operators, CRDs, and cluster-level configurations
- Compliance-driven deployments requiring audit trails and approval workflows through Git-based processes
- Development team self-service application deployment with RBAC controls and namespace isolation
- Disaster recovery automation with Git-based configuration backup and cross-cluster replication capabilities

## Prerequisites

- Minimum 2GB RAM and 2 CPU cores recommended for handling multiple applications and Git repository operations
- Access to a Kubernetes cluster with cluster-admin permissions for initial Argo CD installation and management
- Git repository hosting with webhook capabilities (GitHub, GitLab, Bitbucket) containing application manifests
- Understanding of Kubernetes concepts including deployments, services, ingress, and RBAC configuration
- Network connectivity allowing Argo CD to reach both Git repositories and target Kubernetes clusters
- Valid TLS certificates or willingness to use self-signed certificates for HTTPS web UI access

## docker-compose.yml

```yaml
services:
  argocd-server:
    image: quay.io/argoproj/argocd:latest
    command: argocd-server
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      ARGOCD_REDIS_ADDR: redis:6379
      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
    volumes:
      - argocd_server:/home/argocd
    depends_on:
      - redis
      - argocd-repo-server
    networks:
      - argocd-net
    restart: unless-stopped

  argocd-repo-server:
    image: quay.io/argoproj/argocd:latest
    command: argocd-repo-server
    ports:
      - "8081:8081"
    environment:
      ARGOCD_REDIS_ADDR: redis:6379
    volumes:
      - argocd_repo:/home/argocd
    depends_on:
      - redis
    networks:
      - argocd-net
    restart: unless-stopped

  argocd-controller:
    image: quay.io/argoproj/argocd:latest
    command: argocd-application-controller
    environment:
      ARGOCD_REDIS_ADDR: redis:6379
      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
    volumes:
      - argocd_controller:/home/argocd
    depends_on:
      - redis
      - argocd-repo-server
    networks:
      - argocd-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - argocd-net
    restart: unless-stopped

  dex:
    image: ghcr.io/dexidp/dex:latest
    ports:
      - "5556:5556"
    volumes:
      - ./dex-config.yaml:/etc/dex/config.yaml:ro
    command: dex serve /etc/dex/config.yaml
    networks:
      - argocd-net
    restart: unless-stopped

volumes:
  argocd_server:
  argocd_repo:
  argocd_controller:
  redis_data:

networks:
  argocd-net:
    driver: bridge
```

## .env

```bash
# Argo CD Configuration
ARGOCD_ADMIN_PASSWORD=secure_admin_password

# Dex OIDC Configuration
DEX_GITHUB_CLIENT_ID=xxx
DEX_GITHUB_CLIENT_SECRET=xxx
```

## Usage notes

- Argo CD UI at https://localhost:8443
- Get initial admin password from secret
- Best used with Kubernetes - standalone for testing
- Configure dex-config.yaml for SSO

## Troubleshooting

- Application stuck in 'Progressing' state: Check if Kubernetes resources have sufficient CPU/memory quotas and verify image pull secrets exist
- Repository connection failed with authentication error: Ensure Git credentials are properly configured in Argo CD settings or SSH keys are correctly added
- Sync operation fails with 'resource mapping not found': Update Argo CD to latest version or install required CRDs in target cluster
- Web UI shows 'Unauthorized' after login: Verify Dex configuration matches identity provider settings and callback URLs are correctly configured
- Controller high memory usage: Increase resource limits or reduce application refresh interval in argocd-cm ConfigMap to decrease polling frequency
- Applications not auto-syncing despite configuration: Check webhook configuration in Git repository and verify network connectivity between Git provider and Argo CD

