쿠버네티스 실습: GitOps 기반 배포 자동화 (Argo CD 완전 가이드)

쿠버네티스 실습: GitOps 기반 배포 자동화 (Argo CD 완전 가이드)

앞선 글에서는 Velero를 활용해 클러스터의 백업 및 복구를 자동화했습니다.
이번 글에서는 GitOps 개념을 실습으로 구현합니다.
즉, “Git 저장소에 Push만 하면 자동으로 쿠버네티스에 배포되는 시스템”을 만드는 것입니다.
이를 위해 가장 널리 사용되는 오픈소스 툴 Argo CD를 사용합니다.

---

1) GitOps란 무엇인가?

GitOps는 **‘Git을 단일 진실 소스로 사용하는 배포 방식’**입니다.

기존 방식 GitOps 방식

CI/CD 파이프라인이 직접 kubectl apply 실행	Argo CD가 Git 상태를 주기적으로 동기화
배포 실패 시 직접 롤백	Git의 이전 커밋으로 롤백
클러스터 상태 불명확	Git과 실제 클러스터 상태 자동 비교
운영자 중심 배포	코드 중심, 선언적 인프라 관리

결국, **“배포를 사람의 손이 아닌 Git 커밋으로 제어한다”**는 철학이 GitOps의 핵심입니다.

---

2) Argo CD 설치

2-1. 네임스페이스 생성

kubectl create namespace argocd

2-2. Argo CD 설치

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

2-3. 설치 확인

kubectl get pods -n argocd

예상 출력:

NAME                                 READY   STATUS    AGE
argocd-server-xxxxxx                 1/1     Running   2m
argocd-repo-server-xxxxxx            1/1     Running   2m
argocd-application-controller-xxxxxx 1/1     Running   2m

---

3) Argo CD 접근 설정

3-1. 포트 포워딩

kubectl port-forward svc/argocd-server -n argocd 8080:443

웹 접속: https://localhost:8080

3-2. 초기 관리자 비밀번호 확인

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

→ 아이디: admin
→ 비밀번호: 위 명령 결과

---

4) Git 저장소와 연동

반응형

4-1. Git 리포 구조

fuelstation-gitops/
  ├── base/
  │   ├── backend-deployment.yaml
  │   ├── frontend-deployment.yaml
  │   ├── postgres-statefulset.yaml
  │   ├── redis-deployment.yaml
  │   └── ingress.yaml
  ├── overlays/
  │   ├── dev/
  │   └── prod/

각 환경(dev/prod)은 values나 kustomize로 설정 차이만 두는 구조입니다.

---

5) Argo CD Application 생성

argo-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: fuelstation
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com//fuelstation-gitops.git'
    targetRevision: main
    path: overlays/dev
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: team-a
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

적용:

kubectl apply -f argo-app.yaml

---

6) 자동 동기화 테스트

1. GitHub 저장소의 YAML 수정 후 커밋/푸시
2. Argo CD 대시보드에서 자동 Sync가 진행됨
3. 몇 초 내로 클러스터 리소스가 자동 업데이트

수동 배포(kubectl apply) 없이 Git 커밋 = 배포 트리거 가 됩니다.

---

7) 롤백 (GitOps 방식)

Argo CD는 Git 커밋 단위로 상태를 기억합니다.

• 문제가 발생했을 경우:
• git revert <commit_id> git push origin main
• Argo CD가 자동으로 이전 상태로 복원.

→ 배포 이력 관리와 장애 대응이 모두 Git 하나로 통합됩니다.

---

8) Helm과의 통합

Argo CD는 Helm Chart도 직접 관리할 수 있습니다.

source 설정 예시:

source:
  repoURL: 'https://github.com//fuelstation-helm.git'
  targetRevision: main
  chart: fuelstation-app
  helm:
    values: |
      image.backend: myrepo/nestjs:latest
      image.frontend: myrepo/nextjs:latest

→ Git 커밋으로 Helm Chart 배포 버전 관리까지 가능.

---

9) GitOps 파이프라인 구조 요약

개발자 → Git Commit → GitHub → Argo CD → Kubernetes
             ↑
             └── Helm Chart or Manifest 관리

• Velero: 배포 전 백업
• Argo CD: Git 변경 자동 동기화
• Prometheus Alertmanager: 문제 발생 시 Slack 알림
• Grafana / Kiali / Jaeger: 관찰성 확보

이로써 배포·복구·모니터링·알림이 완전 자동화된 DevOps 구조를 완성했습니다.

---

10) 정리

• Argo CD를 이용하면 Git 저장소 커밋만으로 자동 배포 가능
• syncPolicy.automated 설정으로 self-heal, prune 기능까지 자동화
• Git을 “단일 진실 소스(Single Source of Truth)”로 사용 → 운영 신뢰성 극대화
• Helm, Kustomize, Plain YAML 모두 지원

다음 글에서는 GitOps + Velero + Prometheus를 결합한 재해복구(Disaster Recovery, DR) 전략을 구축하여
클러스터 장애 발생 시 자동 복원 및 알림 트리거링 구조를 완성하겠습니다.

---

 

쿠버네티스,ArgoCD,GitOps,자동배포,Helm,Kustomize,DevOps,지속적배포,CD파이프라인,K8s실습

 

 

제안된 보강 내용 & 수정 포인트

아래는 원본 플로우를 유지하면서, 더 실무적이고 정확한 설명을 추가하면 좋을 부분들입니다.

✅ 보강 포인트 & 참고 자료

항목 보강 제안 참고 자료

자동 동기화 (syncPolicy.automated)	자동 동기화를 설정할 수 있으며, prune 및 selfHeal 옵션을 같이 지정할 수 있다는 설명을 넣기	Argo CD 공식 문서 “Automated Sync Policy” (argo-cd.readthedocs.io) Codefresh 설명 “Automatic Pruning / Self-Healing 옵션” (Codefresh)
Prune / 삭제 처리 주의사항	Git에서 리소스를 제거했을 때 클러스터에서도 삭제되게 하려면 prune: true를 설정해야 한다는 주의 설명	Codefresh 문서 “Automatic Pruning” (Codefresh) StackOverflow 경험 사례 (Stack Overflow)
Sync 옵션 커스터마이즈	syncOptions (예: Prune=false, ApplyOutOfSyncOnly 등) 을 설정해서 일부 리소스 제외하거나 동작 방식 조정할 수 있다는 설명 추가	Argo CD 문서 “Sync Options” (argo-cd.readthedocs.io) Medium 글 “Sync Policies and Options” (Medium) Tutorial on sync options (kubernetes-tutorial.schoolofdevops.com)
RBAC / 멀티 테넌시	여러 팀이 클러스터를 같이 쓰는 경우, Argo CD의 Project / RBAC 설정을 활용하는 방법 설명 추가	Red Hat 블로그 “Using GitOps & ArgoCD with RBAC” (레드햇)
오류/문제 사례 추가	자동 동기화가 작동 안 할 때, 동기화 감지만 되고 실행은 안 되는 문제 사례나 해결책 추가	StackOverflow “argocd not able to sync automatically” (Stack Overflow)
Helm / Kustomize 통합 설명 보강	이미 Helm 통합 예시 있으므로, “GitOps + Helm + values override” 보다 구체적인 예시까지 넣기	DigitalOcean 튜토리얼 “Use Argo CD to deploy via GitOps“ (DigitalOcean)

---

🔄 보강된 통합 예시 (일부 발췌)

아래는 본문의 일부를 이런 보강을 반영한 예시입니다.

---

자동 동기화 및 Prune / Self-Heal 옵션

Argo CD에서는 syncPolicy.automated 속성으로 자동 동기화를 설정할 수 있고, 그 안에 다음 옵션들을 줄 수 있습니다:

spec:
  syncPolicy:
    automated:
      prune: true           # Git에서 제거된 리소스를 클러스터에서도 삭제
      selfHeal: true        # 클러스터 상태가 Git 상태와 달라지면 자동 복구

기본적으로 자동 동기화가 활성화되면 리소스 삭제를 자동으로 하지 않으므로, prune: true 옵션이 필요합니다. (Codefresh)
selfHeal: true는 클러스터 내에서 수동 변경이 발생할 경우 자동으로 Git 상태로 복귀시키는 기능입니다. (Medium)

또한, 특정 자원을 자동으로 삭제하지 않게 하려면 syncOptions를 활용할 수 있습니다:

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
  syncOptions:
    - PrunePropagationPolicy=background
    - ApplyOutOfSyncOnly=true

syncOptions를 통해 Prune 방식이나 동기화 방식 등을 세밀하게 조정할 수 있습니다. (argo-cd.readthedocs.io)

---

RBAC / Argo CD 프로젝트 기반 권한 제어

운영 환경에서는 여러 팀이 하나의 클러스터를 사용할 수 있으므로, Argo CD의 Project와 RBAC 설정을 사용해 권한을 분리하는 패턴이 중요합니다. 예를 들어:

• 각 팀별 Git 리포지토리 접근 제어
• 프로젝트 단위 네임스페이스 제한
• 서비스 계정별 권한 범위 지정

Red Hat 블로그에서는 이러한 권한 제어 방식을 설명하고 있습니다. (레드햇)

---

오류 사례 예시: 자동 동기화가 안 되는 경우

자동 동기화를 설정했음에도 Argo CD가 Sync 버튼을 수동으로 눌러야만 반영되는 경우가 있는데, 이는 syncPolicy 설정 누락 또는 Git 커밋 감지 주기 제한 등이 원인일 수 있습니다. (Stack Overflow)

이럴 경우 다음을 점검해 봐야 합니다:

1. spec.syncPolicy.automated이 enabled: true로 설정되어 있는지
2. prune / selfHeal 옵션이 적절하게 설정되어 있는지
3. Git 리포지토리와 브랜치, 경로 설정이 올바른지
4. Argo CD의 리포지토리 접근 권한 또는 Secret 설정 오류 여부
5. 동기화 주기 (리소스 감지 주기) 설정이 너무 길지 않은지

---

✅ 정리된 개선된 흐름 요약 (업데이트된 글 구성)

최종 글 구성은 다음 흐름을 유지하되 보강 내용을 포함하면 좋겠습니다:

1. GitOps 개념 & Argo CD 소개
2. Argo CD 설치 / 초기 설정
3. Argo CD 접근 방법 (UI, CLI, 인증)
4. Git 리포지토리 구조 및 환경 분리 (base/overlays 또는 Helm 방식)
5. Application 리소스 정의 + syncPolicy 옵션 설명 (prune, selfHeal, syncOptions)
6. 자동 동기화 테스트 및 Git 커밋 → 배포 흐름
7. 오류 대응 & 디버깅 팁
8. RBAC / 멀티 테넌시 / Project 설정
9. Helm 통합 방식 예시
10. GitOps + Velero + Observability + Argo CD 통합 구조 요약
11. 다음 글 예고: GitOps + Velero 재해복구 연계 등

---