[k8s] Helm Argo CD 마이그레이션: GitOps 전환 전략과 실제 사례

목차

• 왜 Helm Argo CD 마이그레이션을 고민하게 될까요?
• Helm과 Argo CD의 역할 차이부터 정리해보겠습니다
• GitOps 전환 전에 먼저 점검할 것들
• 실전 구현: Helm 기반 배포를 Argo CD로 옮기는 단계
• 1. 저장소 구조를 먼저 정리합니다
• 2. Argo CD Application 리소스를 만듭니다
• 3. CI/CD 책임을 분리합니다
• 4. 환경별 선언을 분리합니다
• ⚠️ Helm Argo CD 마이그레이션 중 자주 겪는 문제와 해결법
• 문제 1. 기존 Helm 릴리스와 Argo CD가 충돌합니다
• 문제 2. 값 파일 경로가 꼬입니다
• 문제 3. Secret 관리가 애매합니다
• 문제 4. 자동 동기화가 부담스럽습니다
• 검증: 전환이 제대로 됐는지 어떻게 확인할까요?
• 전환 결과: 무엇이 좋아졌고, 무엇은 여전히 남을까요?
• 실무에서 추천하는 Helm Argo CD 마이그레이션 전략
• 정리와 FAQ
• 자주 묻는 질문

Helm Argo CD 마이그레이션: GitOps 전환 전략과 실제 사례

Helm Argo CD 마이그레이션 이야기는 생각보다 많은 팀이 한 번쯤 부딪히는 주제입니다. 처음엔 Helm(헬름, 쿠버네티스 패키지 매니저)만으로도 배포가 꽤 잘 돌아가거든요. 그런데 서비스가 늘어나고, 환경이 dev/stage/prod로 나뉘고, 누가 언제 어떤 값을 바꿨는지 추적해야 하는 순간부터 슬슬 복잡해집니다. 저도 홈랩과 실무 환경에서 비슷한 과정을 겪었는데요. 처음엔 CI에서 helm upgrade --install만 잘 돌면 끝인 줄 알았는데, 실제로 써보니까 배포 이력 관리, 드리프트(drift, 선언 상태와 실제 상태의 불일치) 감지, 롤백 기준 정리가 점점 더 중요해지더라고요.

특히 GitOps 전환, Kubernetes CI/CD, Argo CD 도입 사례를 찾는 분들이 공통으로 묻는 게 있습니다. "기존 Helm 차트(chart, 배포 템플릿 묶음)를 버려야 하나요?"인데요. 결론부터 말씀드리면, 꼭 그렇지는 않습니다. 제가 직접 해보니 Helm을 유지한 채 Argo CD(아르고 CD, Git 기반 쿠버네티스 지속 배포 도구)로 제어 레이어만 바꾸는 방식이 가장 현실적이었습니다. 오늘은 그 Helm Argo CD 마이그레이션 전략을 단계별로 풀어보겠습니다.

기존 CI 중심 배포 흐름에서 GitOps 기반 선언형 운영으로 바뀌는 구조를 한눈에 보여주는 아키텍처 이미지입니다.

왜 Helm Argo CD 마이그레이션을 고민하게 될까요?

쉽게 말해 Helm은 배포를 잘하게 해주는 도구이고, Argo CD는 원하는 상태를 계속 맞춰주는 운영 도구에 가깝습니다. 둘은 경쟁 관계라기보다 역할이 다릅니다. 여기서 중요한 포인트! Helm만 쓸 때는 보통 CI 파이프라인이 배포를 직접 실행합니다. 예를 들어 GitHub Actions나 Jenkins에서 이미지 빌드 후 Helm으로 클러스터에 적용하는 식이죠.

문제는 운영이 길어질수록 이런 질문이 생깁니다.

• 지금 클러스터 상태가 Git에 있는 선언과 정말 같은가요?
• 누가 수동으로 kubectl edit 했는지 추적 가능한가요?
• 운영 환경 값이 언제 바뀌었는지 리뷰 가능한가요?
• 동일한 앱을 여러 클러스터에 일관되게 배포하고 있나요?

저도 처음엔 이게 뭔가 싶었는데, 결국 핵심은 배포 자동화보다 운영 상태의 일관성이었습니다. GitOps는 Git 저장소를 단일 진실 공급원(single source of truth, 기준 원본)으로 두고, 클러스터가 그 상태를 따라가게 만드는 방식입니다. 이 구조로 바꾸면 "배포 명령을 누가 실행했는가"보다 "Git에 무엇이 머지되었는가"가 기준이 됩니다.

Helm과 Argo CD의 역할 차이부터 정리해보겠습니다

이 부분을 헷갈리면 Helm Argo CD 마이그레이션이 꼬입니다. 저도 초반에 Helm 차트 구조부터 뒤엎으려다가 삽질 좀 했습니다 ㅎㅎ 사실 그렇게까지 할 필요는 없더라고요.

항목	Helm	Argo CD
주요 역할	애플리케이션 패키징과 템플릿 렌더링	Git 기반 선언 상태 동기화
배포 방식	명령 실행 중심	상태 감시 및 자동 동기화
변경 추적	릴리스 이력 중심	Git 커밋과 머지 이력 중심
운영 적합성	단순 배포에 강함	멀티 환경, 멀티 클러스터 운영에 강함
함께 사용 여부	가능	Helm 소스를 그대로 사용할 수 있음

즉, Helm Argo CD 마이그레이션은 "Helm을 버리고 Argo CD로 갈아탄다"가 아니라, "Helm 차트를 유지하면서 Argo CD가 그 차트를 배포하게 만든다"에 더 가깝습니다. 이 관점으로 접근하면 난이도가 확 내려갑니다.

GitOps 전환 전에 먼저 점검할 것들

실전 들어가기 전에 아래는 꼭 확인하시는 걸 권장드립니다. 이거 안 보고 들어가면 중간에 엉킵니다.

1. 현재 Helm 차트 구조: 공용 차트인지, 앱별 차트인지 확인합니다.
2. values 분리 수준: 환경별 values-dev.yaml, values-prod.yaml 같은 파일이 정리되어 있는지 봅니다.
3. 시크릿 관리 방식: Secret(시크릿, 민감 정보 리소스)을 Git에 어떻게 둘지 결정해야 합니다.
4. 배포 주체: 기존 CI가 배포까지 하는지, 아니면 빌드만 하는지 분리합니다.
5. 클러스터 접근 권한: Argo CD가 대상 네임스페이스(namespace, 논리적 격리 영역)에 배포 가능한지 확인합니다.

제가 실제로 써보니까 가장 많이 막히는 건 시크릿과 값 파일 구조였습니다. 차트가 지저분해도 일단 굴러가긴 하는데, GitOps 전환 시점에는 그 지저분함이 그대로 운영 리스크로 드러나거든요.

실전 구현: Helm 기반 배포를 Argo CD로 옮기는 단계

1. 저장소 구조를 먼저 정리합니다

보통은 애플리케이션 코드 저장소와 배포 선언 저장소를 분리하거나, 최소한 배포 디렉터리를 명확히 나눕니다. 저는 운영 가시성을 위해 배포 저장소를 분리하는 편을 선호합니다.

repo/
  charts/
    myapp/
      Chart.yaml
      templates/
      values.yaml
  environments/
    dev-values.yaml
    prod-values.yaml
  argocd/
    myapp-dev.yaml
    myapp-prod.yaml

기존에 CI에서 직접 실행하던 명령은 대략 이런 형태였을 겁니다.

helm upgrade --install myapp ./charts/myapp \
  --namespace myapp \
  -f environments/prod-values.yaml

이제부터는 이 실행 책임을 Argo CD에 넘길 겁니다.

2. Argo CD Application 리소스를 만듭니다

Argo CD에서는 Application(애플리케이션, 배포 대상 정의) 리소스로 어떤 Git 경로를 어떤 클러스터와 네임스페이스에 동기화할지 선언합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/repo.git
    targetRevision: main
    path: charts/myapp
    helm:
      valueFiles:
        - ../../environments/prod-values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

여기서 prune은 Git에서 제거된 리소스를 클러스터에서도 정리해 주는 옵션이고, selfHeal은 누군가 수동 변경한 상태를 다시 선언 상태로 맞춰주는 기능입니다. 드디어 됐다! 싶은 순간이 바로 이 self-heal이 처음 동작할 때였어요. 수동 핫픽스가 다시 원래 선언값으로 돌아오는 걸 보니, 운영 기준이 확실히 잡히더라고요.

Argo CD Application이 Git 저장소의 Helm 차트와 환경별 values 파일을 어떻게 참조하는지 설명하는 구성 이미지입니다.

3. CI/CD 책임을 분리합니다

Kubernetes CI/CD를 GitOps 스타일로 바꿀 때 중요한 건 CI가 더 이상 클러스터에 직접 배포하지 않도록 하는 겁니다. CI는 이미지 빌드와 테스트, 이미지 태깅(tagging, 버전 표기), 그리고 필요한 경우 values 파일 업데이트까지만 담당하게 만드는 게 깔끔합니다.

예를 들어 이런 흐름이 됩니다.

1. 애플리케이션 이미지 빌드
2. 컨테이너 레지스트리(registry, 이미지 저장소)에 푸시
3. 배포 저장소의 이미지 태그 업데이트
4. Git 머지
5. Argo CD가 변경 감지 후 동기화

이 구조가 익숙해지면, "배포 버튼"보다 "리뷰된 Git 변경"이 훨씬 신뢰할 만한 기준이 됩니다.

4. 환경별 선언을 분리합니다

dev와 prod를 하나의 values 파일로 억지로 버티면 나중에 꼭 터집니다. 환경별로 분리하고, 차이가 큰 값은 명시적으로 드러내는 편이 좋습니다.

image:
  repository: ghcr.io/example/myapp
  tag: "1.2.3"

replicaCount: 3

ingress:
  enabled: true
  host: myapp.example.com

여기서 중요한 건 애플리케이션 코드는 이미지로, 운영 설정은 Git 선언으로 나누는 감각입니다. 이게 정리되면 배포 사고가 꽤 줄어듭니다.

⚠️ Helm Argo CD 마이그레이션 중 자주 겪는 문제와 해결법

이 섹션은 정말 경험담 위주입니다. 책처럼 깔끔하게 흘러가지 않더라고요.

문제 1. 기존 Helm 릴리스와 Argo CD가 충돌합니다

처음 Argo CD가 같은 리소스를 관리하려고 들어오면 annotation(어노테이션, 부가 메타데이터)이나 라벨 기준이 달라 충돌하는 경우가 있습니다. 기존 릴리스를 갑자기 지우기보다, 먼저 현재 리소스와 선언 상태가 최대한 같도록 맞춘 뒤 전환하는 게 안전합니다.

• 기존 Helm values와 Argo CD가 참조할 values를 동일하게 맞춥니다.
• 리소스 이름 규칙이 달라지지 않도록 차트 값을 점검합니다.
• 전환 시점에는 변경 폭을 최소화합니다.

문제 2. 값 파일 경로가 꼬입니다

Helm CLI에서는 되던 상대 경로가 Argo CD에서 안 먹는 경우가 있습니다. 저장소 구조를 너무 복잡하게 잡으면 이런 문제가 잦아집니다. 저도 처음엔 공용 차트, 서브모듈, 환경 저장소 분리까지 한 번에 밀어붙였다가 경로 지옥을 봤습니다. 실제로는 처음 전환은 단순한 구조가 정답이더라고요.

문제 3. Secret 관리가 애매합니다

이건 정말 팀 표준이 필요합니다. GitOps 전환을 한다고 해서 Secret 평문을 Git에 넣으면 안 되겠죠. 외부 시크릿 연동이나 별도 암호화 워크플로를 먼저 정하는 편이 좋습니다. 확실하지 않은 구성은 전환 범위에서 잠시 분리하는 것도 방법입니다.

문제 4. 자동 동기화가 부담스럽습니다

prod에서 바로 automated sync를 켜는 게 불안할 수 있습니다. 저도 그랬습니다. 그래서 처음엔 dev만 자동 동기화하고, prod는 수동 동기화로 시작한 뒤 점진적으로 넘겼습니다. 이런 식의 단계적 도입이 Argo CD 도입 사례에서 꽤 현실적인 패턴입니다.

검증: 전환이 제대로 됐는지 어떻게 확인할까요?

Helm Argo CD 마이그레이션이 끝났다고 말하려면 최소한 아래는 확인해야 합니다.

1. Git 변경이 Argo CD에서 감지되는지 확인합니다.
2. Application 상태가 Synced와 Healthy로 보이는지 확인합니다.
3. 수동 변경을 넣었을 때 self-heal이 동작하는지 봅니다.
4. 불필요한 리소스 삭제 시 prune이 예상대로 동작하는지 확인합니다.

kubectl get applications -n argocd
kubectl get pods -n myapp
kubectl describe application myapp-prod -n argocd

실제로 써보니까 여기서 가장 만족도가 높았던 건 운영 가시성이었습니다. 예전에는 "배포는 된 것 같은데 왜 상태가 이렇지?" 하고 CI 로그, Helm 이력, 클러스터 상태를 따로 봐야 했거든요. Argo CD로 넘어오니 적어도 선언 기준과 실제 상태를 같은 화면에서 보는 감각이 생겼습니다. 이거 진짜 편하더라고요.

Git 변경 후 애플리케이션이 Synced, Healthy 상태로 안정화된 모습을 보여주는 검증용 이미지입니다.

전환 결과: 무엇이 좋아졌고, 무엇은 여전히 남을까요?

좋아진 점은 명확합니다.

• 배포 기준이 Git으로 통일됩니다.
• 운영 변경 이력이 Pull Request 리뷰와 함께 남습니다.
• 드리프트 감지가 쉬워집니다.
• 멀티 환경 운영이 예측 가능해집니다.

반대로 남는 과제도 있습니다.

• 차트 품질이 나쁘면 GitOps로 옮겨도 그대로 드러납니다.
• 시크릿 전략은 별도로 정교하게 설계해야 합니다.
• 운영팀과 개발팀이 Git 변경 책임을 어떻게 나눌지 합의가 필요합니다.

즉, GitOps 전환은 마법이 아니라 운영 원칙을 코드와 프로세스로 고정하는 작업에 가깝습니다. 그래서 도구 도입보다 팀 합의가 더 중요할 때도 많습니다.

실무에서 추천하는 Helm Argo CD 마이그레이션 전략

혹시 이런 경험 있으신가요? 한 번에 다 바꾸려다가 더 복잡해지는 경우요. 저는 그래서 아래 순서를 추천드립니다.

1. 기존 Helm 차트와 values 파일부터 정리합니다.
2. dev 환경에만 Argo CD를 먼저 붙입니다.
3. CI에서 배포 단계를 제거하고 선언 업데이트만 남깁니다.
4. 운영 검증 후 prod는 수동 sync로 시작합니다.
5. 문제 없으면 자동 동기화 범위를 넓힙니다.

이 접근은 보수적이지만 실패 비용이 낮습니다. 특히 Kubernetes CI/CD를 운영 중인 팀이라면, "배포 명령을 옮긴다"가 아니라 "운영 제어권을 Git으로 옮긴다"는 관점이 중요합니다.

정리와 FAQ

정리하면, Helm Argo CD 마이그레이션의 핵심은 기존 Helm 자산을 최대한 살리면서 GitOps 전환을 달성하는 겁니다. 저도 처음엔 Helm을 걷어내야 하나 고민했었는데, 실제로는 Helm을 잘 유지하는 쪽이 훨씬 현실적이었습니다. Argo CD 도입 사례를 보면 멋진 아키텍처보다도, 작은 범위에서 안전하게 시작한 팀이 오래 갑니다.

다음 글에서는 ApplicationSet(ApplicationSet, 여러 Application을 템플릿으로 관리하는 기능)이나 멀티 클러스터 운영 패턴도 다뤄볼 예정입니다. 이전 글에서 다룬 Ingress(인그레스, 외부 트래픽 진입점)와 네임스페이스 분리 전략을 같이 보시면 더 이해가 쉬우실 겁니다.

자주 묻는 질문

• Q. Helm을 완전히 버려야 하나요?
  A. 아닙니다. Helm 차트를 그대로 두고 Argo CD가 이를 배포하게 만드는 방식이 일반적입니다.
• Q. 자동 동기화는 바로 켜도 될까요?
  A. dev부터 켜고 prod는 수동으로 시작하는 편이 안전했습니다.
• Q. GitOps 전환의 첫 번째 우선순위는 뭔가요?
  A. values 구조 정리와 시크릿 관리 기준 수립입니다.

Helm 중심 배포와 Argo CD 기반 GitOps 운영의 차이, 장점, 도입 순서를 한 장으로 정리한 요약 이미지입니다.

마지막으로 한 줄만 덧붙이면, GitOps는 도구를 바꾸는 프로젝트가 아니라 운영 습관을 바꾸는 작업입니다. 그래서 천천히, 하지만 기준은 단단하게 잡고 가는 게 맞습니다. 저도 그렇게 돌고 돌아서 정착했습니다.

📚 함께 읽으면 좋은 글

• OpenTelemetry K8s 마이그레이션: Prometheus 공존 전략과 함정
• Cilium vs Calico 네트워킹 성능 실측 비교
• Knative 성능 벤치마크, 실제 트래픽 증가에 따른 서빙 체크 포인트
• rsyslog Loki 마이그레이션: 레거시 로그 시스템 현대화 경험
• CentOS 7에서 AlmaLinux 9로: 성공적인 서버 마이그레이션 전략과 실제 경험