0to1developer log
WIKIHelm

프로젝트

플레이북

도구

AI

기본기

프론트

백엔드

인프라

플레이북

Helm

쿠버 설정의 모양과 값을 갈라 복붙을 없앤다.

HelmChartvalues.yamlKubernetes배포인프라 기초
인프라백엔드 입문6분

한눈에

  • 차트 = 쿠버 YAML의 템플릿 묶음. values.yaml = 그 빈칸을 채우는 값
  • 서비스가 늘어도 차트는 한 벌. 서비스마다 다른 건 values 뿐
  • 환경(dev·stg·prod)은 values 파일이 가른다. 이미지는 다시 안 만든다
  • replicas·CPU·메모리·이미지 태그가 전부 values.yaml 안에 있다
  • helm template 로 렌더 결과를 먼저 눈으로 보고 적용한다
  • {{ }} 는 Go 템플릿 문법. .Values 가 values.yaml 을 가리킨다

쿠버네티스에 서비스 하나를 올리려면 YAML이 여러 장 필요하다. Deployment, Service, Ingress, ConfigMap, HPA. 서비스가 다섯이면 그게 다섯 벌이 된다.

그런데 다섯 벌을 나란히 놓고 보면 서로 다른 건 이름과 숫자 몇 개뿐이다. 나머지는 전부 같다. 복붙으로 늘리다 보면 어느 순간 다섯 벌이 조금씩 어긋나 있고, 무엇이 의도된 차이이고 무엇이 실수인지 아무도 모르게 된다.

모양과 값을 가른다

Helm이 하는 일은 이 한 가지다.

# templates/deployment.yaml   모양. 값이 빈칸이다
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

# values.yaml   값. 이 파일만 서비스마다 · 환경마다 다르다
replicaCount: 3
image:
  repository: registry.example.com/my-app
  tag: "main-250827-79f1"
  pullPolicy: IfNotPresent
resources:
  requests: { cpu: 500m, memory: 1Gi }
  limits:   { cpu: "2",  memory: 4Gi }

{{ }} 안은 Go 템플릿 문법이다. .Values가 values.yaml을 가리키고, .Chart는 차트 자신의 메타(이름·버전)를 가리킨다.

차트 한 벌에 values 여러 벌

같은 차트에 다른 값을 얹는다. 이미지는 그대로다
같은 차트에 다른 값을 얹는다. 이미지는 그대로다

환경을 가르는 건 파이프라인이 아니라 values 파일이다.

charts/base-chart/          차트 한 벌
  Chart.yaml                이름 · 버전
  values.yaml               기본값
  templates/                모양들

envs/dev/values.yaml        replicaCount 1,  메모리 1Gi
envs/prod/values.yaml       replicaCount 3,  메모리 4Gi

이미지는 환경마다 다시 만들지 않는다. 개발에서 검증한 그 이미지가 그대로 운영에 올라가야 "같은 것을 검증했다"가 성립한다. 다시 빌드하는 순간 검증이 뜻을 잃는다.

값이 겹칠 때 누가 이기나

Helm은 값을 여러 층으로 받는다. 아래로 갈수록 세다.

차트의 values.yaml
차트를 만든 사람이 정한 기본값
-f 로 넘긴 파일
envs/prod/values.yaml 같은 것
--set 으로 넘긴 값
명령줄에서 한 줄만 덮어쓸 때

--set 이 제일 세다는 게 편해 보이지만, 명령줄로 넘긴 값은 Git에 안 남는다. 그래서 실무에서는 되도록 파일로 넘긴다. 지금 도는 것이 어느 값으로 떴는지를 나중에 추적할 수 있어야 하기 때문이다.

적용하기 전에 눈으로 본다

Helm에서 제일 자주 쓰게 되는 명령이다.

helm template my-app ./base-chart -f envs/prod/values.yaml

클러스터에 아무것도 안 하고 렌더 결과만 화면에 뱉는다. 템플릿을 고쳤을 때 실제 YAML이 어떻게 나오는지 먼저 보는 용도다. 들여쓰기가 어긋나거나 값이 비어 null로 나오는 것이 여기서 대부분 잡힌다.

helm install my-app ./base-chart -f envs/prod/values.yaml   # 처음 올릴 때
helm upgrade my-app ./base-chart -f envs/prod/values.yaml   # 이후
helm rollback my-app 3                                      # 3번 리비전으로

ArgoCD를 쓰면 위 install·upgrade를 사람이 안 친다. ArgoCD가 차트와 values를 읽어 렌더하고 적용하는 일까지 한다. 그래도 helm template은 계속 쓴다. 그건 배포가 아니라 확인이다.

자주 걸리는 것

nindent 를 빼먹으면 들여쓰기가 무너진다 — toYaml 의 결과는 여러 줄이라 자리를 맞춰 줘야 한다
값이 없으면 빈칸이 아니라 null 이 박힌다 — default 로 기본값을 주거나 if 로 감싼다
숫자로 쓴 태그가 문자열로 안 읽힌다 — tag: 250827 은 숫자다. 따옴표로 감싼다
차트 버전과 앱 버전은 다른 것이다 — Chart.yaml 의 version 과 appVersion
--set 으로 급하게 고친 값은 다음 배포에서 사라진다

이것만 남기면 된다

Pod을 몇 개 띄울지, CPU와 메모리를 얼마나 줄지, 어느 이미지를 쓸지가 전부 values.yaml 안에 있다. 인프라 설정을 안다는 것은 결국 이 파일의 숫자에 근거를 댈 수 있다는 뜻이다.

그 숫자를 어떻게 정하는지는 쿠버네티스 노트의 자원 배분 절에 있고, 전체 배포 흐름에서 Helm이 어디에 서는지는 DevOps와 CI/CD에 있다.