argocd-guide

name	argocd-guide
description	GitOps avec ArgoCD incluant applications, sync, rollbacks, multi-cluster et App of Apps pattern. Se déclenche avec "ArgoCD", "Argo CD", "GitOps", "sync ArgoCD", "application ArgoCD", "App of Apps. Also triggers on "ArgoCD application", "GitOps deployment", "sync and rollback".

ArgoCD Guide

1. Installation et configuration initiale

# Helm (recommandé en prod)
helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --set server.insecure=false \
  --set configs.params."server\.insecure"=false \
  -f argocd-values.yaml

# Récupérer le mot de passe admin initial
argocd admin initial-password -n argocd

# Login CLI
argocd login argocd.example.com --username admin --grpc-web

SSO (Azure AD OIDC) — config minimale dans argocd-cm :

data:
  oidc.config: |
    name: Azure
    issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
    clientID: <app-id>
    clientSecret: $oidc.azure.clientSecret
    requestedScopes: [openid, profile, email]

RBAC — argocd-rbac-cm :

data:
  policy.csv: |
    p, role:developer, applications, sync, */*, allow
    p, role:developer, applications, get, */*, allow
    g, [e-mail], role:developer
  policy.default: role:readonly

---

2. Connecter un repository Git

# SSH key
argocd repo add [e-mail]:org/gitops-repo.git \
  --ssh-private-key-path ~/.ssh/id_ed25519

# HTTPS token
argocd repo add https://github.com/org/gitops-repo.git \
  --username argocd --password <token>

Structure de repo recommandée (monorepo) :

gitops-repo/
├── apps/                   # App of Apps (root)
│   ├── dev/
│   └── prod/
├── manifests/
│   ├── my-app/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev/
│   │       └── prod/
└── infra/
    └── monitoring/

---

3. Déclarer une Application (déclaratif YAML)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-prod
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io   # cascade delete
spec:
  project: production
  source:
    repoURL: [e-mail]:org/gitops-repo.git
    targetRevision: main
    path: manifests/my-app/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: false          # JAMAIS true en prod sans sync window
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground
      - RespectIgnoreDifferences=true
    retry:
      limit: 3
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

Critères sync policy :

Env	auto-sync	prune	selfHeal	Sync window
dev	oui	oui	oui	non
staging	oui	oui	oui	optionnel
prod	non (ou oui)	non	oui	obligatoire

---

4. App of Apps — bootstrapping cluster

# root-app.yaml — appliqué une seule fois manuellement
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: [e-mail]:org/gitops-repo.git
    targetRevision: HEAD
    path: apps/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Le dossier apps/prod/ contient des Application YAML pour chaque workload. ArgoCD les crée en cascade. Un seul kubectl apply -f root-app.yaml bootstrap le cluster entier.

---

5. ApplicationSet — multi-cluster / multi-env

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app-clusters
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: production
  template:
    metadata:
      name: "my-app-{{name}}"
    spec:
      project: production
      source:
        repoURL: [e-mail]:org/gitops-repo.git
        targetRevision: main
        path: "manifests/my-app/overlays/{{metadata.labels.env}}"
      destination:
        server: "{{server}}"
        namespace: my-app

Enregistrer un cluster distant :

# Le context kubeconfig doit pointer sur le cluster cible
argocd cluster add prod-eu-west \
  --name prod-eu-west \
  --label env=production

---

6. Sync waves et hooks

Contrôler l'ordre de déploiement (ex: CRD avant opérateur, migration DB avant app) :

# CRD déployée en wave -1 (avant tout)
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
---
# Job de migration en wave 0
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
---
# App en wave 1
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

---

7. Rollback

# Lister l'historique
argocd app history my-app-prod

# Rollback vers une révision précédente (ID depuis history)
argocd app rollback my-app-prod <revision-id>

# Forcer un sync sur un commit Git précis
argocd app set my-app-prod --revision abc1234
argocd app sync my-app-prod

Après rollback manuel, désactiver l'auto-sync sinon ArgoCD re-synce immédiatement vers HEAD :

argocd app set my-app-prod --sync-policy none

---

8. Secrets — ne jamais stocker en clair dans Git

Outil	Quand l'utiliser
External Secrets Operator	Secrets dans Vault / AWS SSM / Azure Key Vault — recommandé 2026
SOPS + age/KMS	Chiffrement in-repo, rotation manuelle, simple à auditer
Sealed Secrets	Cluster-specific, sans dépendance externe

# ExternalSecret (ESO)
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-creds
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: db-creds
  data:
    - secretKey: password
      remoteRef:
        key: secret/my-app/db
        property: password

---

9. Monitoring et notifications

# Métriques Prometheus exposées par argocd-metrics:8082
# Alertes utiles :
# argocd_app_sync_total{phase="Error"} > 0
# argocd_app_health_status{health_status!="Healthy"} > 0

Notification Slack (argocd-notifications) :

# argocd-notifications-cm
data:
  trigger.on-sync-failed: |
    - when: app.status.operationState.phase in ['Error', 'Failed']
      send: [app-sync-failed]
  template.app-sync-failed: |
    message: |
      App {{.app.metadata.name}} sync FAILED: {{.app.status.operationState.message}}

---

Anti-patterns et pièges

• prune: true en prod sans sync window — supprime des ressources inattendues dès qu'elles disparaissent du repo (oubli d'un fichier = outage).
• Créer des Applications via l'UI ou la CLI seulement — non auditable, disparaît si ArgoCD est recréé. Toujours committer le YAML.
• Stocker des secrets en clair dans le repo GitOps — violation immédiate si le repo est compromis. Utiliser ESO ou SOPS.
• Ignorer les sync waves pour les CRDs — ArgoCD tente de créer des resources custom avant que la CRD existe → erreur de sync.
• Un seul AppProject default pour tous les environnements — perte de l'isolation RBAC. Créer un AppProject par équipe/env.
• targetRevision: HEAD en prod — un merge accidentel se déploie aussitôt. Préférer un tag ou un sha fixe, ou utiliser une sync window.
• health checks manquants pour les CRDs — ArgoCD rapporte Healthy même si l'opérateur est en erreur. Définir un custom health check Lua.

-- Exemple health check Lua pour un CRD custom
hs = {}
if obj.status ~= nil then
  if obj.status.phase == "Ready" then
    hs.status = "Healthy"
  elseif obj.status.phase == "Failed" then
    hs.status = "Degraded"
    hs.message = obj.status.message
  else
    hs.status = "Progressing"
  end
else
  hs.status = "Progressing"
end
return hs

---

Bonnes pratiques 2026

• Utiliser ArgoCD v2.12+ (image pull policy configurable, ApplicationSet matrix generator stable).
• Activer le server-side apply (ServerSideApply=true dans syncOptions) pour éviter les conflits de field managers.
• Préférer Kustomize pour les overlays d'environnement et Helm pour les charts de librairies tierces.
• Brancher Argo Rollouts pour les déploiements progressifs (canary, blue-green) plutôt que les rolling updates natifs K8s.
• Versionner les AppProject et les ApplicationSet dans Git comme toute autre ressource ArgoCD.
• Activer impersonation (ArgoCD 2.10+) pour que chaque Application s'exécute avec un ServiceAccount dédié, limitant le blast radius.