GitOps EKS Platform — ArgoCD + ApplicationSet

A production-grade GitOps repository managing Kubernetes workloads across dev, staging, and prod EKS clusters using ArgoCD ApplicationSets. This repo is the single source of truth for all cluster state — no manual kubectl applies in production.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        GitHub Repository                            │
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌────────────────────┐    │
│  │  argocd/     │    │   apps/      │    │   components/      │    │
│  │  install/    │    │   base/      │    │   cert-manager/    │    │
│  │  appsets/    │    │   overlays/  │    │   external-dns/    │    │
│  │  projects/   │    │   templates/ │    │   metrics-server/  │    │
│  └──────┬───────┘    └──────┬───────┘    └─────────┬──────────┘    │
│         │                  │                       │               │
└─────────┼──────────────────┼───────────────────────┼───────────────┘
          │   GitOps sync    │                       │
          ▼                  ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          ArgoCD                                     │
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    ApplicationSet                           │   │
│   │   Generates one Application per service × environment      │   │
│   │   Matrix generator: services[] × clusters[]                │   │
│   └──────────────────────────┬──────────────────────────────────┘   │
│                              │ renders                              │
│              ┌───────────────┼───────────────┐                     │
│              ▼               ▼               ▼                     │
│        [api-svc/dev]  [api-svc/prod]  [worker/dev] ...            │
└──────────────┬───────────────┬───────────────┬─────────────────────┘
               │               │               │
               ▼               ▼               ▼
         EKS Dev          EKS Prod        EKS Staging

Repository Structure

.
├── argocd/
│   ├── install/          # ArgoCD install manifests (Helm values)
│   ├── appsets/          # ApplicationSet definitions
│   └── projects/         # ArgoCD AppProject RBAC definitions
├── apps/
│   ├── base/             # Kustomize base — shared across all environments
│   ├── overlays/
│   │   ├── dev/          # Dev-specific patches (replicas, resources, image tags)
│   │   ├── staging/      # Staging-specific patches
│   │   └── prod/         # Prod-specific patches
│   └── templates/        # Helm chart template for generic microservice
├── clusters/
│   ├── dev/              # Cluster-scoped resources for dev
│   ├── staging/          # Cluster-scoped resources for staging
│   └── prod/             # Cluster-scoped resources for prod
├── components/
│   ├── cert-manager/     # TLS certificate management
│   ├── external-dns/     # Automatic DNS record management
│   ├── metrics-server/   # Pod/node metrics for HPA
│   └── kube-state-metrics/
└── .github/
    └── workflows/        # CI: manifest validation, diff preview

GitOps Workflow

Developer pushes code change
        │
        ▼
GitHub Actions (CI)
  ├── kubeval / kubeconform  (schema validation)
  ├── kustomize build --dry-run
  ├── helm lint
  └── argocd app diff (preview on PR comment)
        │
        ▼ PR merged to main
ArgoCD detects drift (polls every 3 min or via webhook)
        │
        ▼
ArgoCD syncs cluster to match Git state
        │
        ├── Health check passes → sync complete
        └── Health check fails  → ArgoCD rolls back, Slack alert fired

Quick Start

1. Install ArgoCD on your cluster

kubectl create namespace argocd

kubectl apply -n argocd \
  -f argocd/install/namespace.yaml

helm upgrade --install argocd argo/argo-cd \
  --namespace argocd \
  --values argocd/install/values.yaml \
  --wait

2. Bootstrap the ApplicationSet

kubectl apply -f argocd/appsets/microservices-appset.yaml
kubectl apply -f argocd/appsets/components-appset.yaml

ArgoCD will discover all services and environments from this repo and begin syncing.

3. Access the ArgoCD UI

kubectl port-forward svc/argocd-server -n argocd 8080:443
# Open https://localhost:8080

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

Environments

Environment	Cluster Context	Sync Policy	Auto-prune
dev	platform-dev	Automated	Yes
staging	platform-staging	Automated	Yes
prod	platform-prod	Manual (PR)	No

Production syncs require a manual approval in the ArgoCD UI or CLI. This is intentional — automated applies to prod are disabled as a safeguard.

Adding a New Service

1. Copy apps/templates/microservice/ to apps/base/<your-service>/
2. Update kustomization.yaml with your service name and image
3. Create overlays in apps/overlays/{dev,staging,prod}/<your-service>/
4. The ApplicationSet automatically detects the new directory and creates ArgoCD Applications

No changes to the ApplicationSet itself are needed.

Promotion Flow

Build image → push to ECR
      │
      ▼
Update apps/overlays/dev/<service>/kustomization.yaml  (image tag)
      │ PR + merge
      ▼
ArgoCD syncs dev cluster
      │ manual PR after validation
      ▼
Update apps/overlays/staging/<service>/kustomization.yaml
      │ PR + merge
      ▼
ArgoCD syncs staging cluster
      │ manual PR after validation
      ▼
Update apps/overlays/prod/<service>/kustomization.yaml
      │ PR + merge + ArgoCD manual sync
      ▼
ArgoCD syncs prod cluster

Security Notes

• ArgoCD runs with read-only Git access via Deploy Key (no write-back)
• AppProjects scope which repos and clusters each team can deploy to
• Prod syncs require manual approval — no automated apply
• All secrets managed via External Secrets Operator (not stored in Git)
• RBAC: developers can sync dev/staging; SREs can sync prod

Related Repositories

Repo	Purpose
aws-eks-platform	Terraform — VPC, EKS, IAM
gitops-eks-platform (this repo)	GitOps — workload manifests