GitOps와 Argo CD로 쿠버네티스 배포 자동화하기

GitOps란

GitOps는 Git 리포지토리를 "단일 진실의 원천"으로 사용해 인프라와 애플리케이션 배포를 관리하는 방법론입니다. Git 커밋 = 배포 자동화가 핵심입니다.

ArgoCD 설치

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 초기 비밀번호 확인
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

리포지토리 구조

gitops-repo/
├── apps/
│   └── my-app/
│       ├── base/
│       │   ├── deployment.yaml
│       │   └── kustomization.yaml
│       └── overlays/
│           ├── staging/
│           └── prod/
└── argocd/
    └── applications/

ArgoCD Application 정의

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-prod
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/my-org/gitops-repo
    targetRevision: main
    path: apps/my-app/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true      # Git에서 삭제된 리소스 자동 제거
      selfHeal: true   # 클러스터 직접 변경 시 자동 복원

Kustomize 환경별 설정

# overlays/prod/kustomization.yaml
resources:
- ../../base

images:
- name: my-app
  newTag: v1.2.3

patches:
- path: patch-replicas.yaml

CI/CD 파이프라인 연동

- name: Update GitOps Repo
  run: |
    git clone https://github.com/my-org/gitops-repo
    cd gitops-repo/apps/my-app/overlays/prod
    kustomize edit set image my-app=my-registry/my-app:${{ github.sha }}
    git add -A
    git commit -m "chore: update to ${{ github.sha }}"
    git push

GitOps는 배포 자동화를 넘어 운영 방식의 패러다임 전환입니다. 클러스터에서 무슨 일이 벌어지는지 Git 히스토리만으로 완전히 추적할 수 있게 됩니다.

시크릿 관리 — GitOps의 최대 난제

"모든 걸 Git에"가 원칙이지만 비밀번호·키를 평문으로 커밋하면 안 됩니다. 대표적 해법:

규모가 커지면 — App of Apps & 멀티클러스터

애플리케이션이 수십 개가 되면 ArgoCD Application을 또 다른 Application으로 관리하는 App of Apps 패턴이나 ApplicationSet으로 선언을 템플릿화합니다. 여러 클러스터(스테이징/프로드/리전별)도 단일 ArgoCD에서 타깃으로 관리할 수 있습니다.

드리프트 감지와 롤백

selfHeal: true는 클러스터에서 누군가 kubectl edit로 직접 바꿔도 Git 상태로 자동 복원합니다. 장애 시 롤백은 단순히 Git revert — 이전 커밋으로 되돌리면 ArgoCD가 동기화합니다. 배포 이력=Git 히스토리라는 GitOps의 가장 큰 장점입니다.

장애 증상별 진단 분기표

ArgoCD 운영에서 실제로 마주치는 상황별 진단 경로입니다.

Application이 OutOfSync·Degraded에서 멈출 때

Argo CD 운영에서 자주 만나는 상태는 동기화를 눌러도 계속 OutOfSync로 남거나, 동기화는 됐는데 Health가 Degraded인 경우입니다.

원인

• 컨트롤러·웹훅이 필드를 자동으로 채워(예: HPA가 바꾼 replicas, 웹훅이 주입한 어노테이션) Git과 계속 차이가 남
• CRD가 적용되기 전에 해당 커스텀 리소스를 먼저 적용하려다 실패
• 새 Pod가 readiness를 통과하지 못해 롤아웃이 끝나지 않음

진단 명령

argocd app get myapp --refresh
argocd app diff myapp              # Git과 클러스터의 실제 차이
kubectl -n myapp get events --sort-by=.lastTimestamp | tail -20
kubectl -n myapp rollout status deploy/api

해결

• 컨트롤러가 관리하는 필드는 Application의 ignoreDifferences에 등록합니다(예: HPA 사용 시 Deployment의 /spec/replicas).
• CRD와 커스텀 리소스는 sync wave 어노테이션(argocd.argoproj.io/sync-wave)으로 적용 순서를 지정합니다.
• Degraded는 Argo CD 문제가 아니라 워크로드 문제이므로, 이벤트와 Pod 로그로 원인을 확인한 뒤 Git에서 수정합니다(클러스터 직접 수정은 다음 동기화 때 되돌려짐).

자주 묻는 질문 (FAQ)

Q. ArgoCD와 Flux 중 무엇을 쓰나요? UI·멀티테넌시·App of Apps가 강점인 ArgoCD, 경량·GitOps 툴킷 조합이 강점인 Flux. 대시보드와 RBAC가 중요하면 ArgoCD가 진입장벽이 낮습니다.

Q. selfHeal을 켜면 위험하지 않나요? 긴급 수동 패치가 즉시 되돌려질 수 있으니, 운영 정책상 "변경은 항상 Git을 통해서만" 한다는 규율이 전제되어야 합니다. 그게 GitOps의 핵심이기도 합니다.

에디터 노트 — 현장에서는

GitOps 도입 초기에 가장 자주 깨지는 건 ArgoCD가 아니라 '사람의 습관'입니다. 급하면 누군가 kubectl edit로 직접 고치고, 그 순간 Git과 클러스터가 어긋납니다. selfHeal을 켜자 그 변경이 자동 롤백돼 '왜 내 수정이 사라지냐'는 항의가 빗발쳤죠. 결국 GitOps는 도구가 아니라 '변경은 무조건 PR로'라는 규율이 정착돼야 굴러갑니다. 도구는 그 규율을 강제하는 장치일 뿐입니다.

참고 자료

• Argo CD 공식 문서
• OpenGitOps — GitOps 원칙