0to1developer log
WIKIArgoCD

프로젝트

플레이북

도구

AI

기본기

프론트

백엔드

인프라

플레이북

ArgoCD

Git에 적힌 것과 실제 클러스터를 견주고, 다르면 그 차이를 메운다.

ArgoCDGitOpsCDKubernetes배포인프라 기초
인프라백엔드 입문6분

한눈에

  • 버튼이 아니라 감시자 — Git과 클러스터를 계속 대조한다
  • Synced = Git과 클러스터가 같다 / Healthy = Pod이 잘 떠 있다. 둘은 다른 얘기
  • 손으로 kubectl 을 쳐서 바꿔 놔도 OutOfSync 로 잡힌다
  • 되돌리기의 정석은 git revert. UI 롤백은 Git이 그대로라 다시 어긋난다
  • Jenkins가 클러스터 자격증명을 안 들어도 되게 만드는 장치이기도 하다
  • 자동 동기화 · 셀프힐 · 가지치기는 처음엔 꺼 두고 시작하는 편이 낫다

Jenkins가 이미지를 굽고 values.yaml의 태그를 고치는 데서 끝났다. 그 다음을 맡는 것이 ArgoCD다.

버튼이 아니다

ArgoCD 화면에 SYNC 버튼이 있어서 "누르면 배포되는 것"으로 기억하기 쉽다. 수동 동기화로 설정하면 실제로 그걸 누른다. 하지만 본질은 다르다.

Git에 적힌 것과 실제를 견주고, 다르면 차이를 메운다
Git에 적힌 것과 실제를 견주고, 다르면 차이를 메운다

manifest 레포를 계속 지켜보다가, Git에 적힌 것과 실제 클러스터가 다르면 그 차이를 메운다. 자동 동기화를 켜 두면 아무도 안 눌러도 반영된다.

그리고 ArgoCD가 Pod을 직접 재생성하지도 않는다. Deployment를 갱신하는 데까지가 ArgoCD고, 그 다음은 쿠버네티스가 롤링 업데이트로 처리한다.

뱃지 둘은 다른 얘기다

뱃지무엇을 말하나
Synced / OutOfSyncGit과 클러스터가 같은가
Healthy / Degraded / ProgressingPod이 실제로 잘 떠 있는가

Synced인데 Degraded일 수 있다. 시킨 대로 배포는 됐는데 앱이 죽어 있는 경우다. 이미지 태그는 맞게 바뀌었는데 그 이미지가 부팅에 실패하는 상황이 흔하다.

반대로 OutOfSync인데 Healthy일 수도 있다. 지금 도는 것은 멀쩡한데 Git에 새 버전이 올라온 상태다.

둘을 같이 봐야 무슨 일인지 갈린다.

GitOps라는 말

이 방식을 GitOps라고 한다. 요지는 Git이 진실의 원천이라는 것이다.

지금 클러스터에 뭐가 떠 있는지 알려면 manifest 레포만 보면 된다
누가 서버에 들어가 손으로 바꿔 놔도 OutOfSync 로 드러난다
되돌리기가 git revert 다. 배포 이력이 곧 커밋 이력이다
CI 서버가 클러스터 자격증명을 안 들어도 된다

마지막 항목이 폐쇄망에서 특히 크다. Jenkins가 뚫려도 운영 클러스터로 바로 이어지지 않는다.

Application 하나가 무엇을 가리키나

ArgoCD의 단위는 Application이다. 화면의 카드 하나가 이것이다.

spec:
  source:
    repoURL: https://gitlab.example.com/team/my-app-manifest
    targetRevision: main          # 어느 브랜치·태그를 볼 것인가
    path: charts/base-chart       # 레포 안 어디를 볼 것인가
    helm:
      valueFiles: [../../envs/prod/values.yaml]
  destination:
    server: https://k8s.example.com
    namespace: my-app

읽는 자리(repo · revision · path)와 놓는 자리(cluster · namespace)를 짝지은 것이 전부다. 환경이 둘이면 Application도 둘이고, 대개 values 파일만 다르다.

targetRevision을 HEAD로 두면 그 브랜치의 최신을 계속 따라간다. 태그로 못 박아 두면 사람이 태그를 옮길 때만 배포된다. 운영은 후자가 안전하다.

세 가지 스위치

처음 붙일 때 헷갈리는 옵션 셋이다.

옵션켜면처음엔
Auto SyncGit이 바뀌면 자동으로 적용꺼 두고 눈으로 보며 시작
Self Heal손으로 바꾼 것을 Git 상태로 되돌린다꺼 둔다. 긴급 조치가 되돌려지면 곤란하다
PruneGit에서 지운 리소스를 클러스터에서도 지운다꺼 둔다. 켜면 실수로 지운 것이 실제로 지워진다

셋 다 켜는 것이 최종 목표이긴 하다. 다만 순서가 있다. 파이프라인을 믿을 수 있게 된 다음에 하나씩 켠다.

되돌리는 법 셋

방법무엇을 하나언제
values.yaml의 태그를 옛 값으로 고쳐 커밋Git이 진실이므로 이게 정석대부분
ArgoCD History에서 이전 리비전으로 롤백클러스터만 되돌린다급할 때만
git revert 후 파이프라인 재실행소스까지 되돌린다코드 자체가 문제일 때

두 번째를 쓰면 반드시 Git도 맞춰 놔야 한다. Git은 그대로 새 버전이라 다음 동기화 때 문제가 다시 배포된다. Self Heal이 켜져 있으면 몇 초 만에 되돌아온다.

자주 걸리는 것

계속 OutOfSync 인데 diff 가 비어 보인다 — 쿠버가 자동으로 채우는 필드를 ArgoCD가 차이로 읽는 경우다. ignoreDifferences 로 그 필드를 뺀다
Synced 인데 앱이 옛날 것 — 태그를 latest 로 두면 매니페스트가 안 바뀌어 ArgoCD가 할 일이 없다고 판단한다
Progressing 에서 안 끝난다 — 새 Pod 이 readiness 를 못 넘기고 있다. 롤링 업데이트가 멈춰 선 상태다
레포는 봤는데 Application 이 안 뜬다 — path 나 valueFiles 경로 오타. 렌더 자체가 실패한 것이라 로그를 봐야 한다

손으로 익히려면

맥에서 k3d 클러스터 하나에 ArgoCD를 깔고, 로컬 Git 레포를 바라보게 걸어 보면 감이 온다.

values.yaml의 replicaCount를 1에서 3으로 고쳐 커밋하고, 아무것도 안 눌렀는데 Pod이 셋으로 늘어나는 것을 보는 것. 그게 이 도구의 전부다.

전체 배포 흐름은 DevOps와 CI/CD에 있다.