GitOps с Argo CD

Вы научитесь строить pull-based GitOps delivery с Argo CD, ограничивать источники и destinations через AppProject, управлять sync policy и диагностировать drift и ошибки reconciliation.

• desired, live и target state
• Application и AppProject
• automated sync, prune и selfHeal
• health, sync status и Conditions
• promotion через Git

Git хранит reviewed desired state. Argo CD периодически рендерит target state, сравнивает его с live state Kubernetes и синхронизирует различия. CI публикует immutable artifact и предлагает изменение Git; in-cluster controller выполняет deploy.

Synced означает совпадение target и live manifests, Healthy — работоспособность по health assessment. Приложение может быть Synced, но Degraded, либо OutOfSync, но Healthy. Оба измерения проверяются независимо.

Application связывает repository/path/revision с destination cluster/namespace и sync policy. AppProject является security boundary: ограничивает sourceRepos, destinations, допустимые kinds и project roles.

default AppProject изначально разрешает любые repositories, clusters и kinds, поэтому для multi-tenant production создавайте отдельные проекты с allowlist. Repository credentials и cluster credentials не должны находиться в Application manifest.

automated.enabled включает автоматическую синхронизацию Git change. prune удаляет управляемые ресурсы, исчезнувшие из Git. selfHeal исправляет изменения только в live cluster даже без нового commit. allowEmpty=false защищает от случайного удаления всех ресурсов.

Ручное scale будет восстановлено только при selfHeal=true. Prune расширяет blast radius ошибки Git, поэтому используйте approvals, protected branches, sync windows и PruneLast. Orphaned resources и finalizers требуют осознанной политики удаления.

PreSync hooks выполняются до обычных ресурсов, Sync вместе с основной фазой, PostSync после Healthy, SyncFail при ошибке. Annotation argocd.argoproj.io/sync-wave задаёт порядок от меньшего числа к большему.

Hooks должны быть идемпотентны: self-heal и повторный sync могут запустить их снова. Selective sync не запускает hooks, не записывается в history и не поддерживает rollback, поэтому не используйте его как обычный production deployment.

Promotion — изменение immutable image digest или chart revision в отдельном environment overlay через merge request. Staging и production отслеживают разные paths или repositories; один artifact продвигается без rebuild.

В automated application rollback через UI/CLI несовместим с auto-sync: controller снова применит Git. Корректный rollback — revert или новый commit desired state. Для database changes используйте expand/contract и проверенный roll-forward plan.

• Фиксируйте targetRevision на reviewed commit или tag в production
• Разделяйте application source и platform configuration
• Ограничивайте AppProject repositories, destinations и kinds
• Не используйте ignoreDifferences, пока не определён владелец поля
• Проверяйте rendered manifests и policy до merge
• Защищайте repository credentials и используйте read-only deploy keys
• Настраивайте notifications, metrics, SLO и backup Argo CD configuration
• Используйте HA installation для production; учебный install не HA

Установите зафиксированную Argo CD v3.4.6 в локальный kind. --force-conflicts требуется официальному server-side install для владения CRD fields; не переносите этот флаг на application manifests. HA bundle требует минимум три Nodes.

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.4.6/manifests/install.yaml
kubectl wait deployment/argocd-server -n argocd --for=condition=Available --timeout=300s
kubectl wait deployment/argocd-repo-server -n argocd --for=condition=Available --timeout=300s
kubectl wait statefulset/argocd-application-controller -n argocd --for=jsonpath='{.status.readyReplicas}'=1 --timeout=300s
kubectl get pod -n argocd

Сохраните объекты как app-project.yaml и application.yaml. Учебное приложение использует публичный официальный repository; ветка master нужна для drift-упражнения. В production замените её на reviewed commit/tag и свой repository.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: course
  namespace: argocd
spec:
  description: Restricted training project
  sourceRepos:
    - https://github.com/argoproj/argocd-example-apps.git
  destinations:
    - server: https://kubernetes.default.svc
      namespace: guestbook
  clusterResourceWhitelist: []
  namespaceResourceBlacklist:
    - group: rbac.authorization.k8s.io
      kind: Role
    - group: rbac.authorization.k8s.io
      kind: RoleBinding

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: course
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: master
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      enabled: true
      prune: true
      selfHeal: true
      allowEmpty: false
    syncOptions:
      - PrunePropagationPolicy=foreground
      - PruneLast=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 1m

kubectl create namespace guestbook
kubectl apply -f app-project.yaml
kubectl apply -f application.yaml
kubectl wait application/guestbook -n argocd --for=jsonpath='{.status.sync.status}'=Synced --timeout=180s
kubectl wait application/guestbook -n argocd --for=jsonpath='{.status.health.status}'=Healthy --timeout=180s
kubectl get application guestbook -n argocd -o jsonpath='{.status.sync.status}{" "}{.status.health.status}{" revision="}{.status.sync.revision}{"\n"}'
kubectl get deployment,service,pod -n guestbook -o wide
kubectl port-forward -n guestbook service/guestbook-ui 8080:80

Критерий: Application Synced и Healthy, status содержит Git revision, guestbook Deployment Available, Service отвечает через port-forward. Port-forward запускается в отдельном терминале.

Измените replicas напрямую: selfHeal должен вернуть значение из Git. Затем задайте отсутствующую revision, прочитайте Application Conditions и repo-server logs, восстановите источник и выполните очистку.

kubectl scale deployment guestbook-ui -n guestbook --replicas=3
kubectl get application guestbook -n argocd -w
kubectl get deployment guestbook-ui -n guestbook
kubectl get application guestbook -n argocd -o jsonpath='{.status.operationState.syncResult.revision}{"\n"}'
kubectl patch application guestbook -n argocd --type=merge -p='{"spec":{"source":{"targetRevision":"refs/heads/does-not-exist"}}}'
kubectl get application guestbook -n argocd -o jsonpath='{range .status.conditions[*]}{.type}{": "}{.message}{"\n"}{end}'
kubectl logs deployment/argocd-repo-server -n argocd --tail=100
kubectl patch application guestbook -n argocd --type=merge -p='{"spec":{"source":{"targetRevision":"master"}}}'
kubectl wait application/guestbook -n argocd --for=jsonpath='{.status.sync.status}'=Synced --timeout=180s
kubectl delete application guestbook -n argocd
kubectl delete appproject course -n argocd
kubectl delete namespace guestbook

Наблюдайте переходы, а не только финальное состояние. Если manual scale не восстановился, проверьте automated.enabled, selfHeal, refresh и ownership ресурса.

Основные классы: repository authentication/TLS, render error Helm/Kustomize, запрещённый AppProject source или destination, Kubernetes RBAC/admission, apply conflict, failed hook и unhealthy workload.

argocd app get guestbook
argocd app diff guestbook
argocd app history guestbook
argocd app manifests guestbook
argocd app resources guestbook
kubectl get application guestbook -n argocd -o yaml
kubectl events -n argocd --for application/guestbook
kubectl logs statefulset/argocd-application-controller -n argocd --tail=200
kubectl logs deployment/argocd-repo-server -n argocd --tail=200

Цепочка: Application Conditions → sync/health → operationState → resource tree/diff → repo-server при render → application-controller при apply → Kubernetes Events и workload logs. Не нажимайте Sync повторно без новой гипотезы.

• Чем Synced отличается от Healthy?
• Что отдельно делают automated, prune и selfHeal?
• Почему AppProject является security boundary?
• Почему manual scale восстанавливается не всегда?
• Почему Git revert лучше argocd rollback при auto-sync?
• Какие риски у hooks и selective sync?
• Как продвигать один digest между environments?

Модуль освоен, если вы декларативно создаёте ограниченный проект и приложение, наблюдаете self-heal, диагностируете ComparisonError и выполняете promotion/rollback через Git.