[가이드] kt cloud에서 사용하는 Umbrella Helm Chart 설계 전략

Tech Story/DevOps & Container

[가이드] kt cloud에서 사용하는 Umbrella Helm Chart 설계 전략

kt cloud 기술 블로그 2025. 11. 19. 17:05

[ kt cloud Foundation플랫폼팀 이지은 님 ]

📋 요약

여러 Helm Chart를 하나로 묶어 관리하는 Umbrella Helm Chart의 개념과 설계 전략을 소개합니다.

GitOps 환경에서 배포 자동화와 환경별 설정 관리를 효율화하는 실전 가이드를 제공합니다.

#Helm #UmbrellaChart #GitOps #Kubernetes #배포자동화

CI 도입, 그리고 선택의 기로

CI 체계를 처음 도입하면서 가장 먼저 부딪히는 벽 중 하나는 바로 '배포 방식'에 대한 결정입니다. 선언형 배포를 할 것인가? 템플릿 기반 배포를 할 것인가? 많은 분들이 kustomize와 helm 사이에서 고민을 시작합니다. 그리고 여기서 한 걸음 더 나아가면, Helm을 선택했을 때 'Umbrella Helm Chart'라는 구조를 사용할지 말지에 대한 선택도 기다리고 있습니다.

저 역시 CI/CD 기반 배포 자동화를 구성하면서 이 주제로 한참동안 고민했습니다. 우리 회사의 개발팀에 가장 잘 맞고, GitOps 환경에 잘 적용하는 방법은 무엇일까요? 오늘은 이 여정을 처음 시작하시는 분들을 위해, Umbrella Helm Chart의 개념과 제가 고민하고 판단한 기준을 쉽고 자세하게 풀어드릴게요.

Kustomize vs Helm – 간단 비교

항목	Kustomize	Helm
구조	선언형 (kubectl apply -k)	템플릿 기반 (helm install/upgrade)
변수 치환	patches, overlays 활용	values.yaml 활용
학습 난이도	비교적 간단	템플릿 문법 학습 필요
반복 재사용	디렉터리 복제 또는 generator 사용	Chart 재사용 및 dependency 구조 활용
Release 관리	불가능 (kubectl 기준)	helm release 단위로 관리 가능
GitOps 친화성	매우 좋음	Argo CD와 결합 시 Umbrella 구조로 효율적

Kustomize는 단순하고 직관적이지만, 리소스를 컴포넌트 단위로 재활용하거나 조건 분기 처리가 필요한 경우엔 한계를 느끼게 됩니다. Helm은 상대적으로 복잡하지만, 템플릿화와 release 관리에서 강점을 갖고 있죠. 특히 CI/CD에서 다양한 환경을 지원해야 할 때 Helm은 values.yaml 파일만 바꾸면 되기에 훨씬 유연합니다.

두 도구를 함께 사용하는 하이브리드 방식도 가능합니다. 예를 들어 공통 인프라 구성요소는 Helm Chart로 배포하고, 팀 또는 프로젝트별 커스터마이징은 Kustomize overlay로 처리할 수 있습니다. 이 방식은 Helm의 패키징 장점과 Kustomize의 선언형 확장성을 동시에 누릴 수 있습니다. 단, 배포 파이프라인과 디렉터리 구조를 명확히 정의해야 운영상의 혼란을 줄일 수 있습니다. 특히 Argo CD에서는 Kustomize와 Helm을 사용하는 디렉터리 구조는 처리 방식이 다르기 때문에 소스를 각각 Application으로 나눠 관리하는 것이 좋습니다.

Helm을 선택했다면? Umbrella Helm Chart란?

Helm을 프로젝트 전반에 걸쳐 사용하기로 결정했다면, 다음 단계는 Helm Chart를 어떻게 구조화 할 지 입니다. 여기서 등장하는 개념이 바로 Umbrella Helm Chart입니다.

Umbrella Helm은 말 그대로 여러 개의 서브 Helm Chart들을 하나로 묶어서 관리하는 '우산' 같은 역할을 합니다. 마치 monorepo 방식처럼, 하나의 Helm Chart 안에 여러 앱 혹은 컴포넌트를 하위 chart로 종속시키는 구조죠.

예시 구조

umbrella-chart/
├── charts/
│   ├── frontend/      # frontend 앱 chart
│   ├── backend/       # backend 앱 chart
│   └── redis/         # 인프라 컴포넌트 chart
├── values.yaml        # 공통 설정
└── Chart.yaml        # umbrella chart 정의

이 방식의 장점은 프로젝트 규모가 커질수록 더욱 빛을 발합니다. 예를 들어 OpenStack, Kubernetes Add-on, 모니터링 스택처럼 서로 다른 라이프사이클을 가진 서비스들을 각각 독립적으로 정의하면서도, 상위 Umbrella Chart를 통해 배포·업데이트·롤백을 일관성 있게 제어할 수 있습니다. 또한 values.yaml 한 곳에서 공통 변수를 관리할 수 있어 운영 표준화와 유지보수 효율성을 크게 높일 수 있습니다.

Umbrella Helm Chart의 장점

1. 통합 관리와 일괄 배포

여러 앱, 컴포넌트를 한 번의 helm upgrade로 배포할 수 있어 배포 흐름이 단순해집니다. 대규모 시스템에서는 수십 개의 마이크로서비스를 각각 설치·업데이트해야 하는 부담이 큽니다. Umbrella Chart는 상위 차트에서 전체 라이프사이클을 관리하므로 버전 불일치나 의존성 누락을 예방할 수 있고, 장애 발생 시 롤백도 일괄 처리되어 운영 안정성이 높아집니다.

예: helm upgrade --install my-release ./umbrella-chart

2. 환경별 values 분리

운영 환경, 개발 환경, 테스트 환경마다 리소스 요구사항이나 이미지 태그가 달라질 수 있습니다. Umbrella Chart는 환경별 values 파일을 계층적으로 정의할 수 있어 설정 관리가 체계적입니다. 또한 GitOps와 연동하면 브랜치나 디렉토리 기준으로 values를 자동 적용해 환경 전환을 더욱 간편하게 할 수 있습니다.

즉, values-dev.yaml, values-prod.yaml 등으로 환경별 오버라이딩이 쉬워집니다.

helm upgrade --install my-release ./umbrella-chart -f values-dev.yaml

3. 모듈성

공통 인프라 서비스는 한 번 정의해두면 다른 프로젝트에서 그대로 참조해 활용할 수 있습니다. 팀별 요구에 맞춰 특정 sub-chart만 values를 바꿔 커스터마이징하는 것도 가능하므로 중복 코드와 설정을 줄일 수 있어서 재사용성과 확장성이 높다는 장점이 있습니다. 예를 들어 Redis, Nginx, Prometheus 같은 컴포넌트는 공통화하여 여러 프로젝트에서 사용 가능합니다. 이는 특히 대규모 조직에서 표준화된 Helm 레지스트리를 운영할 때 큰 효과를 발휘합니다.

4. GitOps 친화성

Git 리포지토리에는 umbrella chart와 values 파일만 관리하면 되므로 리소스 관리가 단순화됩니다. Argo CD 입장에서는 단일 App 리소스만 등록하면 전체 인프라와 앱을 추적할 수 있어 관리 포인트가 줄어듭니다. 또한 ‘App of Apps’ 패턴보다 의존성 관리가 명확하고 배포 순서 제어도 Helm이 알아서 처리해주기 때문에, CI/CD 파이프라인이 간결하고 안정적으로 유지됩니다.

사용 시 주의사항

1. sub-chart 간 의존성 충돌 주의

Umbrella Chart는 여러 서브 차트를 함께 묶어 쓰다 보니, 각 차트가 필요로 하는 라이브러리나 CRD 버전이 다를 경우 충돌이 발생할 수 있습니다. 예를 들어 동일한 Ingress Controller를 중복 설치하려 하거나 Redis 차트 버전이 달라지면 배포 오류가 생깁니다. 따라서 의존성 관리 파일(Chart.yaml의 dependencies)에서 버전을 명확히 고정하고, 하위 차트 간 충돌 가능성을 미리 검증하는 과정이 꼭 필요합니다.

2. values.yaml 충돌 주의

Umbrella Chart에서는 상위 values.yaml과 각 sub-chart의 values가 병합되면서 최종 설정이 결정됩니다. 하지만 공통 변수와 특정 차트에서만 쓰이는 변수가 혼동될 경우, 원치 않는 덮어쓰기나 설정 누락이 생길 수 있습니다. 이를 방지하려면 네이밍 컨벤션을 정하거나, sub-chart별로 독립된 values 스코프를 유지하는 전략이 필요합니다. 또한 환경별 values 파일을 병합할 때는 helm template --debug로 최종 렌더링 결과를 반드시 검증해야 합니다.

3. 디버깅 난이도 상승

Umbrella Chart는 여러 컴포넌트를 동시에 관리하기 때문에 특정 sub-chart에서 에러가 발생하더라도 로그상에서는 전체 차트 배포 실패로 보일 수 있습니다. 이 경우 실제 문제가 어느 차트에서 발생했는지 추적하기 어렵습니다. 따라서 helm install --dry-run --debug 같은 사전 검증을 습관화하고, 배포 실패 시에는 helm status <release>와 kubectl describe를 함께 확인하여 에러 지점을 좁혀나가야 합니다. 운영 환경에서는 문제 분리와 로그 수집 체계를 별도로 마련하는 것도 권장됩니다.

4. Argo CD에서 helm 값 변경 시 주의

Argo CD는 UI나 CLI에서 helm 파라미터를 override할 수 있지만, 이는 GitOps 철학에 어긋나 관리 일관성이 무너질 수 있습니다. 운영 중 긴급하게 값을 수정해야 할 때는 임시 대응으로 활용할 수 있으나, 반드시 Git 리포지토리에 반영하여 재배포해야 합니다. 권장되는 방식은 values 파일을 Git에 명시적으로 관리하고, Argo CD는 해당 values 파일만 참조하게 두는 것입니다. 이렇게 해야 이력 추적이 가능하고, 팀 단위 협업 시에도 혼란을 줄일 수 있습니다.

어떤 환경에서 사용하면 좋을까?

Umbrella Helm Chart는 여러 컴포넌트와 서비스를 동시에 다루는 대규모 환경에서 강력한 효과를 발휘합니다. 특히 마이크로서비스 아키텍처나 클라우드 네이티브 인프라처럼 공통 모듈과 애플리케이션이 혼합된 구조에 적합합니다. 환경별 values 분리, GitOps 기반 자동화, 배포 일관성 확보가 중요한 경우에 도입하면 운영 효율성을 크게 높일 수 있습니다.

실제 디렉터리 구조 & 예시 코드

umbrella-chart/
├── charts/
│   ├── frontend/
│   │   └── values.yaml
│   ├── backend/
│   │   └── values.yaml
│   └── redis/
│       └── values.yaml
├── values.yaml        # 공통 설정
├── values-dev.yaml    # dev 전용 설정
├── values-prod.yaml   # prod 전용 설정
└── Chart.yaml

Chart.yaml

apiVersion: v2
name: umbrella-chart
version: 0.1.0
dependencies:
  - name: frontend
    version: 1.0.0
    repository: "file://charts/frontend"
  - name: backend
    version: 1.0.0
    repository: "file://charts/backend"
  - name: redis
    version: 1.0.0
    repository: "file://charts/redis"

values-dev.yaml

frontend:
  replicaCount: 1
backend:
  image:
    tag: dev
redis:
  auth:
    enabled: false

Argo CD에서 Umbrella Helm Chart 활용 팁

1. 하나의 App으로 전체 구성 배포

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: umbrella-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/your-repo.git
    targetRevision: main
    path: umbrella-chart
    helm:
      valueFiles:
        - values-dev.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

2. 서브차트 단위 파라미터 조정은 되도록 하지 말기

Argo CD에서 values override보다 Git 내 values.yaml로 직접 관리 추천

3. 서브차트가 많아질 경우 디렉토리 가독성 확보 필수

charts 디렉터리 안에 앱/인프라 별로 폴더 구분을 명확히 해주세요

실습: Umbrella Helm Chart 실습 환경 만들기 (from scratch)

목표: frontend, backend, redis처럼 3개 차트를 만들고, 그걸 umbrella chart로 묶어서 Helm CLI로 배포해보기

Step 1. 테스트용 차트 만들기

mkdir -p ~/helm-lab/charts
cd ~/helm-lab/charts

# frontend 차트 만들기
helm create frontend

# backend 차트 만들기
helm create backend

# redis 차트 만들기 (간단하게)
helm create redis

Step 2. umbrella chart 만들기

cd ~/helm-lab
mkdir umbrella-chart
cd umbrella-chart

# Chart.yaml 생성
cat <<EOF > Chart.yaml
apiVersion: v2
name: umbrella-chart
version: 0.1.0
description: A Helm Umbrella Chart Example
dependencies:
  - name: frontend
    version: 0.1.0
    repository: "file://../charts/frontend"
  - name: backend
    version: 0.1.0
    repository: "file://../charts/backend"
  - name: redis
    version: 0.1.0
    repository: "file://../charts/redis"
EOF

# values.yaml 생성
cat <<EOF > values.yaml
frontend:
  replicaCount: 1

backend:
  replicaCount: 2

redis:
  architecture: standalone
EOF

Step 3. 의존성 업데이트 및 설치

# 의존성 업데이트 (subchart 연결)
helm dependency update .

# dry-run 확인 (설치 전 템플릿 확인)
helm install test-umbrella . --dry-run

# 실제 설치
helm install test-umbrella .

Step 4. 확인

helm list

kubectl get all -l app.kubernetes.io/instance=test-umbrella

Step 5. 테스트 리소스 삭제

helm uninstall test-umbrella

결론

복잡한 운영 환경과 다양한 배포 조건을 고려할 때, 템플릿 기반의 Helm은 선언형 툴보다 더 유연한 대응이 가능합니다. 특히 Umbrella Helm Chart는 여러 앱과 인프라를 하나의 구조로 묶어 배포함으로써, GitOps 환경에서의 통합 관리와 일관성을 확보할 수 있죠.

처음엔 설정이 번거로울 수 있지만, 명확한 디렉터리 설계와 values 관리 기준만 잘 잡아두면 확장성과 유지보수 측면에서 큰 이점을 얻게 됩니다.

kt cloud NEXT에서도 각 개발팀의 배포를 Umbrella Helm Chart 기반으로 표준화할 계획입니다.

kt cloud NEXT처럼, 여러 팀 단위 배포의 일관성과 확장성을 고민 중이라면 지금 이 구조를 도입해보는 것도 좋습니다.

❓ 자주 묻는 질문 (FAQ)

Q. Umbrella Helm Chart는 일반 Helm Chart와 어떻게 다른가요?

A. Umbrella Helm Chart는 여러 개의 독립적인 서브 Helm Chart들을 하나의 상위 차트로 묶어 관리하는 구조예요.
일반 Helm Chart가 하나의 애플리케이션(또는 논리적 서비스 단위)을 배포하는 역할이라면, Umbrella Chart는 Chart.yaml의 dependencies 항목을 통해 frontend, backend, redis 같은 여러 컴포넌트를 함께 다룰 수 있어요.

이렇게 구성하면 상위 values.yaml에서 공통 설정을 통합 관리할 수 있고, helm install 또는 helm upgrade 한 번으로 여러 서비스를 일괄적으로 배포할 수 있어 운영 효율이 크게 높아져요. 특히 마이크로서비스처럼 여러 구성요소가 함께 배포되어야 하는 환경에서 배포 일관성과 관리 편의성을 확보하는 데 큰 장점이 있어요.

저작자표시 비영리 변경금지 (새창열림)

'Tech Story > DevOps & Container' 카테고리의 다른 글

[분석] ArgoCD 3.0이 선언한 GitOps 새로운 시대: 주요 업데이트 기능 완벽 해부 (0)	2025.10.16
[사례연구] kt cloud OpenStack GitOps 배포 전략: Genestack 기반 CI/CD 자동화 구축 과정 (1)	2025.08.05
[기술가이드] cgroup v2 의 eBPF로 마스터하는 컨테이너 리소스 제어 (1)	2025.05.27
[기술가이드] Kubernetes 환경에서 App of Apps로 구현하는 GitOps 실전 전략 (0)	2025.05.15
[기술가이드] 2025년 Kubernetes 관리의 미래: kt cloud Cluster API 아키텍처 완벽 해설 (2)	2025.04.16

현재글[가이드] kt cloud에서 사용하는 Umbrella Helm Chart 설계 전략