[GitOps] ArgoCD: Kubernetes GitOps

ArgoCD, Argo CD, GitOps, Application, ApplicationSet, Argo Rollouts, Flux CD

정의

ArgoCD = Kubernetes 의 GitOps 컨트롤러. Git 리포지토리의 manifest 가 source of truth → cluster 가 자동 동기화.

GitOps 원칙

flowchart LR
    Dev[Dev] -->|commit / PR| Git["Git repo<br/>(manifest)"]
    Git --> ArgoCD[ArgoCD]
    ArgoCD -->|continuously sync| Cluster[K8s Cluster]
    Cluster -->|state| Compare
    Git -->|desired| Compare
    Compare -->|drift| ArgoCD

원칙	의미
Git = source of truth	모든 변경 이 git 으로
Declarative	YAML / Helm / Kustomize
Auto-sync	git 변경 → cluster 자동 적용
Auto-healing	manual 변경도 git 으로 복구
Observable	UI / API 로 항상 상태 가시

Application 정의

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/manifests
    targetRevision: main
    path: apps/web/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:
      prune: true       # git 에서 제거된 자원 → 삭제
      selfHeal: true    # 수동 변경 → git 으로 복구
    syncOptions:
      - CreateNamespace=true

동작

sequenceDiagram
    Dev->>Git: commit manifest 변경
    loop 매 3분 (또는 webhook)
        ArgoCD->>Git: pull
    end
    ArgoCD->>Cluster: compare desired vs actual
    alt drift
        ArgoCD->>Cluster: kubectl apply
    end
    ArgoCD-->>Dev: UI 에 sync status

App of Apps 패턴

flowchart TB
    Root[Root Application] --> App1[App: web]
    Root --> App2[App: api]
    Root --> App3[App: worker]
    Root --> App4[App: redis]

Application 자체를 git 에서 관리. 새 service 추가 = git PR 만.

ApplicationSet

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata: { name: cluster-bootstrap }
spec:
  generators:
    - clusters: {}    # 모든 등록된 cluster
  template:
    metadata: { name: '{{name}}-monitoring' }
    spec:
      source:
        repoURL: ...
        path: 'clusters/{{name}}/monitoring'
      destination:
        server: '{{server}}'

수많은 cluster / namespace 에 동일 app 자동 배포.

ArgoCD vs Flux

항목	ArgoCD	Flux
UI	강력	없음 (Weave GitOps UI 별도)
학습 곡선	중간	낮음
단순성	중간	높음
Multi-tenancy	강	보통
Notification	built-in	Alertmanager 통합

2026 시점 ArgoCD 가 더 인기. UI + 다양 source (Helm, Kustomize, Jsonnet, …).

Argo Rollouts (Progressive Delivery)

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata: { name: web }
spec:
  replicas: 10
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 5m }
        - setWeight: 30
        - pause: { duration: 5m }
        - setWeight: 50
        - pause: { duration: 10m }
        - setWeight: 100
      analysis:
        templates:
          - templateName: success-rate

progressive rollout + 자동 metric 분석 + 실패 시 자동 롤백.

CI/CD 분리 (Push vs Pull)

flowchart LR
    subgraph "Push-based (옛)"
        CI1[CI] -->|kubectl apply| Cluster1
    end
    subgraph "Pull-based (GitOps)"
        CI2[CI] -->|update manifest| Git
        Argo[ArgoCD] -->|pull + apply| Cluster2
    end

Pull (GitOps)	Push
안전 (cluster credential 외부 없음)	CI 가 cluster 접근
자동 복구	한 번 실행 후 끝
감사 (git log)	CI history
다중 cluster 쉬움	어렵

흔한 함정

RBAC / Projects

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-backend
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/myorg/*'
  destinations:
    - namespace: backend
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  roles:
    - name: developer
      description: deploy 권한
      policies:
        - p, proj:team-backend:developer, applications, sync, team-backend/*, allow

Project = 권한 경계. namespace / repo / 리소스 종류 제한. Multi-team 환경에서 필수.

Sync Wave & Hooks

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"     # wave 번호: 낮을수록 먼저 sync
    argocd.argoproj.io/hook: PreSync       # PreSync / Sync / PostSync / SyncFail
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

flowchart LR
    W0["Wave 0: CRD, Namespace"] --> W1["Wave 1: ConfigMap, Secret"]
    W1 --> W2["Wave 2: Deployment"]
    W2 --> W3["Wave 3: Ingress"]

wave 번호 낮은 것부터 sync. 같은 wave 내 리소스는 병렬. Hook 은 lifecycle 지점 지정.

Health Check

ArgoCD 가 리소스 상태를 Healthy / Progressing / Degraded 로 자동 판단. 커스텀 health check:

# argocd-cm ConfigMap
resource.customizations.health.mygroup_myresource: |
  hs = {}
  if obj.status.ready == true then
    hs.status = "Healthy"
  else
    hs.status = "Progressing"
  end
  return hs

상태	의미
Healthy	리소스 정상
Progressing	업데이트 중
Degraded	오류, 복구 필요
Suspended	일시 중단
Missing	클러스터에 없음

Argo Image Updater

annotations:
  argocd-image-updater.argoproj.io/image-list: web=myrepo/web
  argocd-image-updater.argoproj.io/web.update-strategy: semver
  argocd-image-updater.argoproj.io/write-back-method: git

container image 새 버전 자동 감지 → git 에 commit → ArgoCD sync. CI 파이프라인 마지막 단계 자동화.

Notification Controller

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
data:
  template.app-sync-succeeded: |
    slack:
      attachments: |
        [{
          "color": "#18be52",
          "title": "{{.app.metadata.name}} 배포 완료"
        }]
  trigger.on-sync-succeeded: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-sync-succeeded]

배포 완료 / 실패 / drift 를 Slack / Teams / PagerDuty 로 알림. argocd-notifications-secret 에 webhook URL 저장.

관련 위키

• gitops-patterns
• github-actions
• k8s-deployment
• helm
• k8s-rbac
• zero-downtime-deployment