Helm은 Kubernetes에서 가장 널리 사용되는 패키지 매니저이자 템플릿 엔진이다.
하지만 서비스가 성장하면서 개발 환경(dev), 스테이징(stage), 프로덕션(production) 등 환경이 분리되기 시작하면 Helm만으로는 환경마다 값이 달라지는 설정들을 관리하기가 점점 번거로워진다.

예를 들어, replica 수, 리소스 제한, 스토리지 설정 등은 환경 별로 달라지는 경우가 대부분이다.
반대로 서비스 이름, Port, Infisical Secret 등은 환경 별로 달라지지 않는다.

어떤 것은 같고, 어떤 것은 달라서 특별한 도구가 없다면 Dev, Stage, Production 환경마다 Helm Chart가 있어야 한다.

하지만 환경마다 전체 Helm Chart를 관리하는 방식은 시간이 지날수록 복잡해지고, 점점 크기가 비대해지는 문제가 생기곤 한다.

이를 해결하기 위해 Kustomize를 활용해 Helm Chart의 환경별 구성을 보다 직관적이고 유연하게 관리하는 방식을 도입했다.

Kustomize는 아래 두 가지 기능이 핵심으로 위에서 언급한 문제점을 해결할 수 있다.

1. 패치(Patch)를 이용한 선언적 변경
2. 환경별 오버레이 구성(environment overlay structure)

Base Chart를 구성하고, 환경별로 필요한 값만 Kustomize overlay로 덮어씌우는 방식으로 구성하면 훨씬 깔끔하고 유지보수하기 좋은 구조가 된다.

대략적인 구조는 아래와 같다.

base에 변하지 않는 기본 부분을 정의하고,
overlays에는 환경마다 변하는 부분을 Patch 하는 방식으로 변경부분만 정의함으로써 중복 코드를 최소화하여 환경 간 배포 설정을 구성할 수 있다.

kustomize/
  base/
    kustomization.yaml
    deployment.yaml
    service.yaml
  overlays/
    dev/
      deployment/
        user-deployment-patch.yaml
        auth-deployment-patch.yaml
        inference-deployment-patch.yaml
        ...
      service/
        user-service-patch.yaml
        auth-service-patch.yaml
        inference-service-patch.yaml
      kustomization.yaml
    stage/
      ...
      kustomization.yaml
    prod/
      ...
      kustomization.yaml

kustomize/
  base/
    kustomization.yaml
    deployment.yaml
    service.yaml
  overlays/
    dev/
      deployment/
        user-deployment-patch.yaml
        auth-deployment-patch.yaml
        inference-deployment-patch.yaml
        ...
      service/
        user-service-patch.yaml
        auth-service-patch.yaml
        inference-service-patch.yaml
      kustomization.yaml
    stage/
      ...
      kustomization.yaml
    prod/
      ...
      kustomization.yaml

(deployment 내부 일부 생략, stage, prod도 생략)

Kustomize에는 kustomization.yaml 파일이 있다.
이 파일은 “이 환경에서는 어떤 리소스를 기준으로, 어떤 패치를 적용할 것인가?”를 선언하는 환경 구성의 핵심 엔트리포인트(entrypoint) 역할을 한다.

Helm의 values.yaml이 템플릿에 값을 넣어주는 파일이라면,
Kustomize의 kustomization.yaml은 리소스를 조합하고 패치하는 규칙을 정의한 메타 파일이라고 이해하면 된다.

kustomize/base/kustomization.yaml에는 Base 폴더에 들어있는 Base Resource를 명시한다.

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml
  ...

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml
  ...

kustomize/overlays/{env}/kustomization.yaml에는 resources에는 Base를 명시한다. 기본적으로 적용될 파일을 명시하는 과정이다.

그 후, patches에는 위에 덮어씌워질 파일과 리소스 정보를 함께 명시해준다.

resources:
  - ../../base

patches:
  - path: service/user-deployment-patch.yaml
    target:
      kind: Deployment
      name: user-deployment
  - path: service/auth-deployment-patch.yaml
    target:
      kind: Deployment
      name: auth-deployment
  ...

resources:
  - ../../base

patches:
  - path: service/user-deployment-patch.yaml
    target:
      kind: Deployment
      name: user-deployment
  - path: service/auth-deployment-patch.yaml
    target:
      kind: Deployment
      name: auth-deployment
  ...

resources와 patches로 환경마다 다른 패치를 선언적으로 쉽게 적용할 수 있다.

Kustomize를 사용하면 환경 간 실수로 잘못된 값을 적용할 가능성이 줄어든다.
또한, 변경점이 있을 때 Base의 경우에는 환경 별로 수정할 필요도 없다.

특히 Kustomize는 GitOps와 함께 사용할 때 시너지 효과가 좋다.
우리는 ArgoCD를 사용해서 CI/CD 환경을 운영하고 있는데, Kustomize와 통합되어 환경별로 자동 배포 라인까지 구성 가능하다.

Kustomize는 단순히 Kubernetes 리소스를 조합하는 도구를 넘어서, 환경별 구성 레이어를 만드는 데 매우 강력한 도구다.

Helm Chart는 그대로 유지하면서 환경별 차이만 Kustomize로 패치하는 구조는 코드 유지보수성, 배포 안전성, 협업 효율성 면에서 큰 장점을 준다.

환경이 dev, stage, production로 나뉘어 있고, Helm Chart를 유지하면서도 환경별 구성 차이를 명확히 관리하고 싶다면 Kustomize는 사실상 필수 도구에 가깝다.

우리는 이 조합을 통해 설정 관리 문제를 크게 줄였고, CI/CD 파이프라인과 통합하여 더욱 단순하고 지속 가능한 개발/배포 구조를 만들 수 있었다.