Argo CD в CI/CD: от
merge до стабильного rollout

Argo CD как GitOps-контроллер

Сравнивает desired state в Git с live state в Kubernetes и приводит cluster к Git по заданной политике. Поддерживает plain-YAML, Kustomize, Helm, Jsonnet, custom config management plugins.

---

Sync policy

Поле syncPolicy.automated:

• prune: true — удаляет ресурсы, исчезнувшие из Git;
• selfHeal: true — восстанавливает ручные изменения в кластере;
• allowEmpty: false (default) — защищает от пустого манифеста, который удалил бы всё.

Оба поля prune и selfHeal по умолчанию false (безопасное поведение); enabled для automated-политики по умолчанию true. Без selfHeal ручные изменения в кластере не триггерят sync; с selfHeal контроллер повторяет sync после timeout ~5 секунд. Auto-sync срабатывает только когда Application в статусе OutOfSync, и одна попытка на уникальную пару commit SHA + параметры (после неудачного sync повтор на тот же SHA не делается).

source: argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/

Argo CD по умолчанию поллит Git каждые 3 минуты (timeout.reconciliation: 120s + jitter до 60s в argocd-cm). Для мгновенной реакции на push настраивают webhooks, а интервал поллинга увеличивают (15m, 1h); timeout.reconciliation: 0 полностью выключает поллинг (не рекомендуется).

source: argo-cd.readthedocs.io/en/stable/faq/

Доп. опции в syncOptions: CreateNamespace=true, PrunePropagationPolicy=foreground, ServerSideApply=true, Replace=true, RespectIgnoreDifferences=true.

targetRevision: HEAD — антипаттерн в production: ссылается на «последний коммит» дефолтной ветки и нарушает воспроизводимость. Использовать тег или SHA.

---

Sync phases, waves и hooks

Sync-операция делится на фазы: PreSync → Sync → PostSync, плюс SyncFail при провале. Внутри каждой фазы порядок применения ресурсов задают sync waves — annotation argocd.argoproj.io/sync-wave с целым числом. По умолчанию все ресурсы и hooks получают wave 0; wave может быть отрицательным, чтобы выполниться раньше остальных (например CRD → operator → workload).

source: argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/

Порядок применения Argo CD определяет по цепочке: фаза → номер wave (от меньшего к большему) → kind ресурса → имя. Между волнами контроллер выдерживает задержку 2 секунды (настраивается через ARGOCD_SYNC_WAVE_DELAY), давая другим контроллерам время отреагировать. Applying идёт с первой волны, где есть OutOfSync или unhealthy-ресурс, и повторяется, пока все фазы и waves не станут healthy и synced. То есть следующая wave не стартует, пока ресурсы предыдущей не стали healthy.

source: argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/

Resource hooks — обычные Kubernetes-манифесты (чаще Pod/Job/Argo Workflow) с annotation argocd.argoproj.io/hook:

• PreSync — до применения манифестов; провал останавливает весь sync (миграции БД);
• Sync — вместе с основным потоком;
• PostSync — после того как все ресурсы Sync-фазы стали healthy (smoke/integration tests);
• SyncFail — cleanup при провале sync (доступен с v1.2);
• Skip — Argo CD не применяет ресурс;
• PostDelete — после удаления всех ресурсов Application (очистка внешних ресурсов).

source: argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/

Lifecycle hook-ресурса задаёт annotation argocd.argoproj.io/hook-delete-policy:

• BeforeHookCreation — старый hook удаляется перед созданием нового (default, если политика не указана);
• HookSucceeded — удалить после успешного выполнения;
• HookFailed — удалить после провала.

source: argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
    argocd.argoproj.io/sync-wave: "-1"
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: registry.example/migrate:1.4.2
        command: ["/app/migrate", "up"]

---

Drift detection и rollback

Argo CD непрерывно сравнивает Git и cluster. При расхождении:

• статус OutOfSync;
• selfHeal возвращает к Git автоматически;
• ручной откат — git revert коммит и sync.

Прямой откат на предыдущий деплой:

argocd app history demo-app
argocd app rollback demo-app <history-id>

При включённом auto-sync CLI/API откажется выполнять rollback (FailedPrecondition) — сначала нужно отключить auto-sync (argocd app set --sync-policy none), иначе controller сразу вернёт состояние к Git; только UI предлагает отключить его автоматически.

---

ApplicationSet

Шаблонизация Application для multi-cluster / multi-tenant:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: tenants
spec:
  generators:
  - list:
      elements:
      - name: team-a
        cluster: prod
      - name: team-b
        cluster: prod
  template:
    metadata:
      name: '{{name}}'
    spec:
      project: default
      source:
        repoURL: https://git.example/apps.git
        targetRevision: v1.4.2
        path: 'apps/{{name}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{name}}'

Полный набор генераторов (9):

Generator	Что делает
List	Fixed-список key/value элементов
Cluster	Application по кластерам, зарегистрированным в Argo CD
Git	Читает files или directory-структуру в Git-репозитории
Matrix	Комбинирует параметры двух других генераторов (декартово произведение)
Merge	Сливает параметры 2+ генераторов; последующие переопределяют базовый
SCM Provider	Через API SCM (GitHub и т.п.) авто-обнаружение репозиториев в организации
Pull Request	Через API SCMaaS находит открытые PR в репозитории
Cluster Decision Resource	Кластеры выбираются кастомной CR-логикой
Plugin	Параметры через RPC HTTP-запросы к плагину

Все генераторы поддерживают фильтрацию через Post Selector (selector по labels сгенерированных параметров).

source: argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/

---

App-of-apps (cluster bootstrapping)

Паттерн, где один «корневой» Application состоит только из других Application. При sync родителя декларативно создаются/синхронизируются/удаляются дочерние приложения — удобно для bootstrapping нового кластера сразу набором инструментов (ingress, cert-manager, monitoring и т.д.).

source: argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: bootstrap
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example/bootstrap.git
    targetRevision: v1.4.2
    path: apps            # директория с манифестами дочерних Application
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Возможность создавать Application в произвольных Projects — admin-level: доступ к репозиторию корневого приложения должен быть только у администраторов.

source: argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/

App-of-apps vs ApplicationSet: app-of-apps — статичный список дочерних Application в Git; ApplicationSet генерирует Application из шаблона по генераторам (list/cluster/git/matrix/…), что лучше масштабируется на multi-cluster/multi-tenant без ручного дублирования манифестов.

---

Базовый Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo-app
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    path: guestbook
    targetRevision: v0.5.0   # тег или SHA, не HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true

---

Операционные команды

argocd app get demo-app
argocd app sync demo-app
argocd app history demo-app
argocd app rollback demo-app 12
argocd app diff demo-app

---

Автоматизация обновления образов

Argo CD сам по себе не следит за registry — новый тег образа кто-то должен записать в desired state. Два подхода:

1. Argo CD Image Updater — отдельный контроллер, который автоматически обновляет образы workload'ов, управляемых Argo CD. Конфигурируется annotations на Application: argocd-image-updater.argoproj.io/image-list (список образов с constraint) и <alias>.update-strategy. Работает только с приложениями на Kustomize или Helm (нужны image-параметры).

source: argocd-image-updater.readthedocs.io/en/stable/

Стратегии обновления:

Strategy	Поведение
semver (default)	Наибольшая версия в рамках constraint (напр. 1.x)
newest-build	Образ с самой свежей датой сборки (бывш. latest); тег произвольный — SHA и т.п.
alphabetical	Последний тег в алфавитном порядке (бывш. name)
digest	Последний запушенный digest мутабельного тега

source: argocd-image-updater.readthedocs.io/en/stable/basics/update-methods/

Write-back методы:

• argocd (default) — правит source-параметры Application в кластере, аналог argocd app set --parameter .... Псевдо-persistent: при удалении/пересоздании Application изменения теряются.
• git — коммитит override в файл .argocd-source-<appName>.yaml в путь манифестов, изменения переживают пересоздание Application и остаются в Git.

source: argocd-image-updater.readthedocs.io/en/stable/basics/update-methods/

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prod
  annotations:
    argocd-image-updater.argoproj.io/write-back-method: git
    argocd-image-updater.argoproj.io/image-list: api=registry.example/api:1.x
    argocd-image-updater.argoproj.io/api.update-strategy: semver

source: argocd-image-updater.readthedocs.io/en/stable/configuration/applications/

2. Бот-PR (Renovate / Dependabot) — внешний бот открывает PR с bump тега/digest в манифесте, изменение проходит review/CI и мержится, после чего Argo CD синхронизирует. Плюс: обновление проходит тот же approval-gate, что и остальной код (совместимо с принципом «изменения только через Git-операции»); Image Updater с write-back argocd этот gate обходит. Renovate/Dependabot — не часть Argo CD, детали по их документации.

---

Progressive delivery: Argo Rollouts

Argo Rollouts — Kubernetes-контроллер и набор CRD для продвинутых стратегий деплоя; заменяет Deployment ресурсом Rollout (те же spec.template, плюс spec.strategy). Интегрируется с ingress-контроллерами и service mesh для постепенного сдвига трафика.

source: argoproj.github.io/argo-rollouts/

• Canary — трафик на новую версию наращивается порциями (setWeight + pause), с мониторингом метрик между шагами.
• Blue-Green — параллельно stable (blue) и preview (green); переключение трафика после проверки новой версии.
• Analysis / AnalysisTemplate — автоматическая оценка выкатки по запросам к метрикам; провал → автоматический rollback без ручного вмешательства.
• Metric providers: Prometheus, Datadog, New Relic, Wavefront, Kayenta, Graphite, InfluxDB и др.
• Traffic management: NGINX, AWS ALB, Istio, Ambassador, APISIX, Kong, Traefik.
• Experiments — параллельный прогон версий для сравнения.

source: argoproj.github.io/argo-rollouts/

Связка с GitOps: Rollout — обычный манифест в Git, Argo CD его синхронизирует; canary-шаги и analysis выполняет контроллер Rollouts, а не Argo CD.

---

Guardrails

• pre-merge: lint/scan/tests/policy (OPA/Kyverno);
• разделение окружений и promotion strategy через теги/ветки;
• запрет targetRevision: HEAD в prod;
• runbook для git revert и argocd app rollback.

---

Ссылки

• Argo CD Documentation
• Sync Options
• Sync Phases and Waves
• Resource Hooks
• Automated Sync Policy
• ApplicationSet Generators
• App of Apps / Cluster Bootstrapping
• Argo CD Image Updater
• Argo Rollouts