GitOps 핵심 도구 ArgoCD 완전 정리 - 개념부터 실전 구축·사용법까지

얼마 전 이 블로그에 Gitea Actions로 CI/CD 파이프라인을 만든 이야기를 썼었다. 코드를 push하면 빌드하고 배포까지 자동으로 되는 걸 보고 뿌듯했는데, 곰곰이 생각해보니 찜찜한 구석이 하나 있었다. "지금 클러스터에 떠 있는 게 진짜 내가 마지막으로 push한 그 상태가 맞나?"를 확인하려면 결국 kubectl get을 쳐봐야 한다는 점이었다. 파이프라인이 뭘 배포했는지는 알아도, 클러스터의 "지금 상태"와 Git의 "정의된 상태"가 항상 일치한다는 보장은 없었다. 이 문제를 해결하는 방식이 바로 GitOps고, 그 대표주자가 ArgoCD다.

ArgoCD가 뭔가요 - GitOps라는 개념부터

ArgoCD는 쿠버네티스용 GitOps 도구다. 한 문장으로 요약하면: "Git 저장소에 있는 내용 = 클러스터의 실제 상태"가 항상 같아지도록 자동으로 맞춰주는 감시자다.

기존에 우리가 쓰던 CI/CD(Gitea Actions, GitHub Actions 등)는 "push 방식"이다. 코드가 바뀌면 파이프라인이 실행되면서 kubectl apply나 kubectl set image 같은 명령을 클러스터에 "밀어넣는다." ArgoCD는 반대로 "pull 방식"이다. ArgoCD가 클러스터 안에서 계속 돌면서, 주기적으로(기본 3분) Git 저장소를 스스로 들여다보고 "어? 저장소 내용이 바뀌었네, 클러스터도 이렇게 맞춰야겠다"며 스스로 끌어와서 적용한다.

Push 방식(Gitea Actions): 코드 변경 → 파이프라인 실행 → 클러스터에 "밀어넣기". 클러스터는 수동적으로 당한다.
Pull 방식(ArgoCD): 코드 변경과 무관하게 ArgoCD가 늘 감시 중 → Git과 클러스터 상태를 비교 → 다르면 스스로 "당겨와서" 맞춘다.

왜 이 차이가 중요한가 - 실제 벌어질 수 있는 일

예를 들어보자. 급한 마음에 kubectl edit deployment로 replica 수를 임시로 늘렸다가 원복하는 걸 깜빡했다고 하자. push 방식 CI/CD는 이 변화를 전혀 모른다. 다음 배포 전까지 클러스터는 "Git엔 없는 상태"로 계속 돌아간다. 이런 게 쌓이면 나중엔 "이 클러스터가 왜 이렇게 설정돼 있지?"를 아무도 설명 못 하는 상태(설정 드리프트)가 된다.

ArgoCD를 쓰면 이 순간 화면에 "OutOfSync"라고 빨갛게 뜬다. 누가 수동으로 뭘 바꿨는지, Git과 뭐가 다른지 diff로 바로 보여준다. 그리고 설정에 따라 자동으로 되돌리거나(Self-Heal), 최소한 "지금 어긋나 있다"는 걸 사람이 놓칠 수 없게 만든다.

장점

드리프트(설정 불일치) 자동 감지

클러스터 상태와 Git 상태를 지속적으로 비교해서 다른 점을 실시간으로 보여준다. "누가 뭘 몰래 바꿨는지"를 추적할 필요가 없다.

클릭 한 번 롤백

ArgoCD가 배포할 때마다 이력을 남기기 때문에, 문제가 생기면 이전 커밋(리비전)으로 UI에서 버튼 한 번 눌러 되돌릴 수 있다. "그때 그 커밋이 뭐였더라"를 git log에서 뒤질 필요가 없다.

클러스터 상태를 한눈에 보는 대시보드

어떤 서비스가 몇 개 파드로 떠 있고, 어떤 파드가 방금 재시작됐고, 어떤 리소스가 서로 어떻게 연결돼 있는지를 그래프 형태로 보여준다. kubectl get을 연달아 치던 걸 웹 화면 하나로 대체한다.

클러스터 안쪽에 자격증명을 안 둬도 됨

push 방식 CI/CD는 파이프라인이 클러스터에 접속할 권한(kubeconfig, 토큰)을 파이프라인 쪽에 들고 있어야 한다. ArgoCD는 반대로 클러스터 "안에서" Git 저장소로 나가서 읽어오기만 하면 되니, 클러스터 접근 권한을 외부(CI 러너 등)에 내보낼 필요가 없다. 보안 관점에서 공격 표면이 하나 줄어든다.

앱이 여러 개, 클러스터가 여러 개여도 한 곳에서 관리

ArgoCD 하나가 여러 Git 저장소, 여러 네임스페이스, 심지어 여러 클러스터를 동시에 감시할 수 있다. "Application"이라는 단위로 각각 등록해두면 전부 한 화면에 모여서 보인다.

구축 방법 - k3s에 ArgoCD 설치하기

단일 노드 k3s 기준으로 실제로 설치하는 순서다.

네임스페이스 만들고 공식 매니페스트 적용

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

파드들이 다 뜰 때까지 기다린다.

kubectl get pods -n argocd -w

초기 admin 비밀번호 확인 설치 직후엔 admin 계정 비밀번호가 시크릿에 자동 생성되어 들어있다.
```
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d
```
로그인 후에는 이 초기 비밀번호를 바로 바꾸는 걸 권장한다(공식 CLI로 argocd account update-password).
UI 접속 경로 만들기 기본 설치는 클러스터 내부에서만 접근되는 상태다. 홈랩처럼 Traefik을 이미 쓰고 있다면 IngressRoute 하나만 추가하면 된다.
```
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: argocd-server
  namespace: argocd
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`argocd.내도메인`)
      kind: Rule
      services:
        - name: argocd-server
          port: 443
  tls:
    certResolver: myresolver
```
(ArgoCD 서버 자체가 내부적으로 TLS를 쓰기 때문에 백엔드 포트는 443, scheme은 https로 맞춰야 한다는 점만 주의하면 된다.)

사용법 - Application 하나 등록해보기

ArgoCD의 핵심 개념은 Application 하나뿐이다. "이 Git 저장소의 이 경로에 있는 매니페스트를, 이 클러스터의 이 네임스페이스에 반영해라"는 선언 하나가 Application이다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mini-portal
  namespace: argocd
spec:
  project: default
  source:
    repoURL: http://172.30.1.25:30300/admin/mini-portal.git
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: portal
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

이 YAML 하나를 kubectl apply -f로 넣으면 끝이다. 여기서 syncPolicy.automated의 두 옵션이 실전에서 제일 중요하다.

selfHeal: true — 누가 kubectl edit로 클러스터를 손으로 고쳐도, ArgoCD가 곧바로 감지해서 Git 상태로 되돌려놓는다. "손으로 고친 설정이 다음 배포 때까지 남아있는" 사고를 원천 차단한다.
prune: true — Git에서 리소스를 삭제하면(예: YAML 파일 삭제) 클러스터에서도 따라서 삭제해준다. 이게 없으면 "Git엔 없는데 클러스터엔 계속 남아있는 고아 리소스"가 쌓인다.

이 두 옵션을 켜두면 정말로 "Git이 곧 클러스터의 유일한 진실"이 된다. 반대로 자동화가 무섭다면 automated 블록을 빼고 수동으로 두면, UI에서 diff를 확인하고 "Sync" 버튼을 직접 눌러야만 반영되는 안전한 모드로도 쓸 수 있다.

마무리

지금 이 홈랩은 아직 Gitea Actions의 push 방식 CI/CD로 잘 돌아가고 있어서 당장 ArgoCD로 전부 갈아탄 건 아니다. 다만 앱 개수가 늘어나고 "이 클러스터 지금 상태가 뭐였더라"를 확인하는 빈도가 늘어날수록, pull 방식의 이 드리프트 감지·자동 복구 개념은 분명 매력적이다. 다음엔 실제로 이 클러스터의 앱 하나를 ArgoCD로 옮겨보는 후기로 다시 찾아올 생각이다.

로그인 후 댓글을 작성할 수 있습니다.