Kustomize → Helm, 가장 쉽게 변환하는 방법

프로젝트를 운영하다 보면 처음에는 Kustomize를 사용하다가, 이후에는 Helm으로 전환해야 하는 경우가 있다.
특히 여러 환경(dev, stage, prod)을 관리하거나 재사용 가능한 Chart를 만들어야 할 때 Helm이 더 편리한 경우가 많다.

이번 글에서는 기존 Kustomize 프로젝트를 Helm Chart로 변환하는 가장 간단한 방법을 정리한다.

 

 

---

 

왜 Helm으로 변경할까?

 

Kustomize는 Kubernetes에서 기본적으로 지원하며 간단한 오버레이 관리에 적합하다.

하지만 다음과 같은 상황에서는 Helm이 더 유리하다.

• 여러 프로젝트에서 동일한 템플릿을 재사용해야 하는 경우
• values.yaml만 변경하여 환경별 배포를 관리하고 싶은 경우
• 버전 관리(Chart Version)가 필요한 경우
• Helm Repository를 통해 배포하고 싶은 경우
• CI/CD에서 Helm을 사용하는 경우

 

---

기존 Kustomize 구조

예를 들어 다음과 같은 구조라고 가정한다.

kustomize/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

---

 

1. 현재 YAML 생성

먼저 Kustomize가 최종적으로 생성하는 YAML을 확인한다.

kustomize build overlays/dev > output.yaml

또는

kubectl kustomize overlays/dev > output.yaml

이렇게 하면 실제 Kubernetes에 적용되는 모든 YAML이 하나의 파일로 생성된다.

 

---

 

2. Helm Chart 생성

새로운 Helm Chart를 생성한다.

helm create my-chart

생성되는 구조는 다음과 같다.

my-chart/
├── Chart.yaml
├── values.yaml
└── templates/

기본으로 생성되는 예제 파일들은 필요하지 않다면 삭제해도 된다.

rm -rf templates/*

 

---

 

3. YAML 복사

앞에서 생성한 output.yaml을 리소스별로 분리하여 templates 폴더에 넣는다.

예를 들어

templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    configmap.yaml

처럼 구성하면 된다.

이 시점에서는 단순히 YAML을 복사한 상태이므로 Helm 변수는 아직 없다.

 

---

 

4. values.yaml로 변수 분리

기존 YAML에서 자주 변경되는 값들을 values.yaml로 이동한다.

예를 들어 Deployment가 다음과 같다면

spec:
  replicas: 2

containers:
- image: nginx:latest

다음과 같이 수정한다.

spec:
  replicas: {{ .Values.replicaCount }}

containers:
- image: {{ .Values.image.repository }}:{{ .Values.image.tag }}

그리고 values.yaml에는

replicaCount: 2

image:
  repository: nginx
  tag: latest

처럼 작성한다.

환경마다 달라지는 값은 모두 values.yaml로 분리하면 관리가 훨씬 쉬워진다.

 

---

 

5. 환경별 values 파일 생성

Kustomize에서는 overlays를 사용했다면 Helm에서는 values 파일을 사용하면 된다.

예시

values.yaml
values-dev.yaml
values-prod.yaml

배포 시에는 다음과 같이 사용한다.

helm install app . -f values-dev.yaml

또는

helm upgrade --install app . -f values-prod.yaml

---

 

6. 정상 동작 확인

실제 배포 전에 렌더링 결과를 확인하는 것이 좋다.

helm template .

또는

helm template . -f values-dev.yaml

렌더링된 YAML이 기존 Kustomize 결과와 동일한지 비교하면 된다.

 

---

 

자동 변환이 가능할까?

 

아쉽게도 Kustomize를 Helm으로 완전히 자동 변환해 주는 공식 도구는 없다.

그 이유는 두 도구의 동작 방식이 다르기 때문이다.

• Kustomize는 기존 YAML을 Patch하는 방식
• Helm은 Go Template을 이용해 YAML을 생성하는 방식

따라서 대부분의 경우에는 다음 순서로 작업하는 것이 가장 빠르다.

1. kustomize build로 최종 YAML 생성
2. helm create로 Chart 생성
3. templates에 YAML 복사
4. 변경되는 값을 values.yaml로 분리
5. helm template으로 결과 확인

 

---

 

마무리

 

Kustomize에서 Helm으로 전환하는 작업은 생각보다 어렵지 않다.

핵심은 최종 YAML을 먼저 생성한 뒤, 변경되는 부분만 Helm Template으로 치환하는 것​이다.

복잡한 자동 변환 도구를 찾기보다는, kustomize build와 helm create를 활용하여 필요한 변수만 values.yaml로 분리하는 방식이 가장 쉽고 유지보수도 편하다.