Helm 패키지 매니저 완벽 가이드

Kubernetes 애플리케이션 배포를 위한 Helm 패키지 매니저의 기초부터 실무 활용까지 다룹니다. 차트 구조 이해, 설치 및 업그레이드, 커스텀 차트 작성법을 단계별로 학습합니다.

---

목차

1. Helm_설치_및_기본_개념
2. 차트_구조_이해
3. helm_install_upgrade_rollback
4. Values_파일_활용
5. 커스텀_차트_작성
6. 차트_저장소_관리

---

1. Helm 설치 및 기본 개념

어느 날 김개발 씨는 신규 프로젝트에 투입되어 Kubernetes 클러스터에 여러 애플리케이션을 배포해야 하는 상황에 놓였습니다. YAML 파일을 하나하나 작성하다 보니 벌써 수십 개가 넘어가고, 관리가 점점 힘들어졌습니다.

"이걸 매번 이렇게 해야 하나요?" 선배 박시니어 씨가 웃으며 답했습니다. "Helm을 써보세요."

Helm은 한마디로 Kubernetes를 위한 패키지 매니저입니다. 마치 스마트폰의 앱스토어처럼 복잡한 애플리케이션을 클릭 몇 번으로 설치할 수 있게 해줍니다.

Helm을 사용하면 수십 개의 YAML 파일을 하나의 패키지로 묶어서 버전 관리하고 쉽게 배포할 수 있습니다.

다음 코드를 살펴봅시다.

# Helm 설치 (macOS)
brew install helm

# Helm 설치 (Linux)
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 설치 확인
helm version

# 저장소 추가 (예: Bitnami)
helm repo add bitnami https://charts.bitnami.com/bitnami

# 저장소 업데이트
helm repo update

# 사용 가능한 차트 검색
helm search repo nginx

김개발 씨는 입사 후 첫 번째 큰 프로젝트를 맡게 되었습니다. Kubernetes 클러스터에 웹 서버, 데이터베이스, 캐시 서버, 메시지 큐까지 다양한 컴포넌트를 배포해야 했습니다.

처음에는 열심히 YAML 파일을 작성했습니다. Deployment, Service, ConfigMap, Secret...

파일이 하나둘 늘어나더니 어느새 폴더 안에 수십 개가 쌓여 있었습니다. "이렇게 많은 파일을 어떻게 관리하죠?" 김개발 씨가 한숨을 쉬며 물었습니다.

옆자리의 박시니어 씨가 모니터를 슬쩍 보더니 말했습니다. "Helm이라는 도구가 있어요.

제가 보여드릴게요." 그렇다면 Helm이란 정확히 무엇일까요? 쉽게 비유하자면, Helm은 마치 이케아 가구 조립 설명서와 같습니다.

이케아에서 책장을 사면 수십 개의 부품과 나사가 들어있지만, 설명서 하나로 순서대로 조립할 수 있습니다. Helm도 마찬가지입니다.

복잡한 Kubernetes 리소스들을 하나의 패키지로 묶어서 명령어 하나로 설치할 수 있게 해줍니다. Helm이 없던 시절에는 어땠을까요?

개발자들은 애플리케이션마다 수많은 YAML 파일을 직접 관리해야 했습니다. 개발 환경과 운영 환경에서 값만 다른 거의 동일한 파일을 여러 벌 만들어야 했고, 버전이 바뀔 때마다 모든 파일을 일일이 수정해야 했습니다.

더 큰 문제는 롤백이었습니다. 배포에 문제가 생기면 이전 버전의 파일을 찾아서 다시 적용해야 했는데, 어떤 파일이 어떤 버전인지 추적하기가 매우 어려웠습니다.

바로 이런 문제를 해결하기 위해 Helm이 등장했습니다. Helm에서는 애플리케이션 배포에 필요한 모든 것을 **차트(Chart)**라는 단위로 묶습니다.

차트 안에는 Kubernetes 리소스 템플릿, 기본 설정값, 문서가 모두 포함되어 있습니다. 한 번 만들어둔 차트는 환경에 따라 설정값만 바꿔서 재사용할 수 있습니다.

위의 코드를 살펴보겠습니다. 먼저 Helm을 설치합니다.

macOS에서는 brew 명령어로, Linux에서는 공식 스크립트로 간단히 설치할 수 있습니다. 설치 후 helm version 명령으로 정상 설치를 확인합니다.

그다음 helm repo add 명령으로 차트 저장소를 추가합니다. Bitnami는 잘 알려진 오픈소스 차트 저장소 중 하나입니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 새 프로젝트에 Redis를 추가해야 한다고 가정해봅시다.

Helm 없이라면 Deployment, Service, ConfigMap, PersistentVolumeClaim 등 여러 파일을 직접 작성해야 합니다. 하지만 Helm을 사용하면 helm install my-redis bitnami/redis 한 줄로 프로덕션 수준의 Redis를 바로 배포할 수 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 공식 차트를 그대로 프로덕션에 사용하는 것입니다.

차트의 기본값은 대부분 개발 환경에 맞춰져 있어서 리소스 제한이나 보안 설정이 충분하지 않을 수 있습니다. 따라서 반드시 values.yaml을 검토하고 환경에 맞게 수정해서 사용해야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 바로 Helm을 설치하고 첫 번째 차트를 배포해 보았습니다.

"와, 정말 편하네요!" 수십 개의 YAML 파일이 명령어 한 줄로 정리되는 경험은 그야말로 신세계였습니다.

실전 팁

💡 - helm repo update는 새 차트를 검색하기 전에 항상 실행하세요

• helm search hub 명령으로 Artifact Hub의 모든 공개 차트를 검색할 수 있습니다

---

2. 차트 구조 이해

Helm을 처음 사용해본 김개발 씨는 궁금해졌습니다. "차트 안에는 대체 뭐가 들어있는 거죠?" 박시니어 씨가 터미널에서 차트 하나를 다운로드해서 열어 보여주었습니다.

"차트의 구조를 이해하면 직접 만들 수도 있어요."

Helm 차트는 정해진 디렉토리 구조를 따르는 파일들의 모음입니다. 마치 요리 레시피북처럼 재료 목록(values.yaml)과 조리 방법(templates/)이 체계적으로 정리되어 있습니다.

이 구조를 이해하면 남이 만든 차트를 분석하거나 직접 차트를 만들 수 있게 됩니다.

다음 코드를 살펴봅시다.

mychart/
  Chart.yaml          # 차트의 메타정보 (이름, 버전, 설명)
  values.yaml         # 기본 설정값
  charts/             # 의존성 차트들
  templates/          # Kubernetes 리소스 템플릿
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl      # 템플릿 헬퍼 함수
    NOTES.txt         # 설치 후 표시될 안내 메시지
  .helmignore         # 패키징 시 제외할 파일

박시니어 씨가 화면에 차트 구조를 보여주자 김개발 씨는 고개를 갸우뚱했습니다. "파일이 여러 개 있는데, 각각 어떤 역할을 하는 건가요?" 박시니어 씨가 차근차근 설명하기 시작했습니다.

차트의 구조를 이해하려면 집을 짓는 과정에 비유하면 좋습니다. Chart.yaml은 건축 허가서와 같습니다.

이 건물이 무엇인지, 누가 지었는지, 몇 층짜리인지 기본 정보가 적혀 있습니다. values.yaml은 인테리어 옵션표입니다.

벽지 색상, 바닥재 종류, 가구 배치 등 세부 사항을 선택할 수 있습니다. 그리고 templates/ 폴더는 실제 설계 도면입니다.

이 도면을 바탕으로 집이 지어집니다. 먼저 Chart.yaml을 살펴보겠습니다.

이 파일에는 차트의 이름, 버전, 앱 버전, 간단한 설명 등이 들어갑니다. version은 차트 자체의 버전이고, appVersion은 차트가 배포하는 애플리케이션의 버전입니다.

이 둘을 구분하는 것이 중요합니다. 차트 구조는 그대로인데 앱 버전만 올라갈 수도 있고, 그 반대일 수도 있기 때문입니다.

다음으로 values.yaml입니다. 이 파일은 차트의 모든 설정 가능한 값들을 정의합니다.

레플리카 수, 이미지 이름과 태그, 리소스 제한, 서비스 타입 등 거의 모든 것을 여기서 조절할 수 있습니다. 사용자는 이 파일을 수정하거나 설치 시 --set 옵션으로 값을 덮어쓸 수 있습니다.

가장 중요한 templates/ 디렉토리를 봅시다. 이 폴더 안에는 실제 Kubernetes 리소스를 정의하는 YAML 파일들이 있습니다.

하지만 일반 YAML과 다른 점이 있습니다. Go 템플릿 문법으로 작성되어 있어서 values.yaml의 값을 동적으로 주입할 수 있습니다.

예를 들어 {{ .Values.replicaCount }}라고 쓰면 values.yaml에 정의된 replicaCount 값이 들어갑니다. _helpers.tpl 파일은 특별한 역할을 합니다.

파일 이름이 언더스코어로 시작하면 Helm은 이 파일을 Kubernetes 리소스로 렌더링하지 않습니다. 대신 다른 템플릿에서 재사용할 수 있는 헬퍼 함수들을 정의하는 데 사용합니다.

예를 들어 차트 이름에 릴리스 이름을 붙이는 함수를 한 번 정의해두면 모든 템플릿에서 호출해서 쓸 수 있습니다. NOTES.txt도 빼놓을 수 없습니다.

차트 설치가 완료되면 이 파일의 내용이 터미널에 출력됩니다. 접속 URL을 확인하는 방법, 초기 비밀번호를 얻는 명령어 등 사용자가 알아야 할 정보를 여기에 적습니다.

친절한 차트일수록 NOTES.txt가 잘 작성되어 있습니다. 실제 현업에서는 이 구조를 어떻게 활용할까요?

팀에서 자체 애플리케이션을 배포할 때 먼저 helm create 명령으로 기본 차트 구조를 생성합니다. 그다음 templates/ 안의 파일들을 수정하고 values.yaml에 필요한 옵션들을 추가합니다.

한 번 만들어둔 차트는 개발, 스테이징, 프로덕션 환경에서 values 파일만 바꿔가며 재사용할 수 있습니다. 김개발 씨가 물었습니다.

"charts/ 폴더는 뭔가요?" 박시니어 씨가 답했습니다. "의존성 차트가 들어가는 곳이에요.

예를 들어 우리 애플리케이션이 Redis를 필요로 한다면 Redis 차트를 여기에 넣거나 Chart.yaml에 의존성으로 선언할 수 있어요." 이제 김개발 씨는 차트의 구조가 어떻게 생겼는지 명확하게 이해할 수 있었습니다. "마치 잘 정리된 프로젝트 폴더 같네요!"

실전 팁

💡 - helm show values 차트명 명령으로 차트의 모든 설정 가능한 값을 확인할 수 있습니다

• helm template 명령으로 실제 배포 전에 렌더링된 YAML을 미리 확인하세요

---

3. helm install upgrade rollback

차트 구조를 이해한 김개발 씨는 드디어 첫 배포를 시도했습니다. 하지만 배포하고 나니 새로운 걱정이 생겼습니다.

"버전을 올리려면 어떻게 하죠? 문제가 생기면 롤백은요?" 박시니어 씨가 Helm의 가장 강력한 기능을 알려주려고 합니다.

helm install, helm upgrade, helm rollback은 Helm의 핵심 생명주기 명령어입니다. 마치 게임의 저장 슬롯처럼 Helm은 모든 배포 이력을 리비전으로 관리하여 언제든 이전 상태로 돌아갈 수 있게 해줍니다.

이 세 명령어만 알면 Kubernetes 배포의 80%는 해결됩니다.

다음 코드를 살펴봅시다.

# 차트 설치 (릴리스 이름: my-app)
helm install my-app bitnami/nginx

# 네임스페이스 지정하여 설치
helm install my-app bitnami/nginx -n production --create-namespace

# 설치된 릴리스 목록 확인
helm list

# 차트 업그레이드 (새 버전 또는 설정 변경)
helm upgrade my-app bitnami/nginx --set replicaCount=3

# 릴리스 히스토리 확인
helm history my-app

# 이전 버전으로 롤백 (리비전 번호 지정)
helm rollback my-app 1

# 릴리스 삭제
helm uninstall my-app

김개발 씨는 드디어 첫 Helm 배포를 성공했습니다. helm install 명령어 한 줄에 nginx 서버가 클러스터에 떠있었습니다.

기분 좋게 퇴근했는데 다음 날 출근해보니 기획팀에서 요청이 와 있었습니다. "트래픽이 늘어났으니 서버를 3대로 늘려주세요." 예전 같았으면 Deployment YAML 파일을 열어서 replicas 값을 수정하고 kubectl apply를 실행했을 것입니다.

하지만 이제는 Helm이 있습니다. helm upgrade는 기존 릴리스를 새로운 설정이나 차트 버전으로 업데이트합니다.

김개발 씨가 helm upgrade my-app bitnami/nginx --set replicaCount=3을 실행하자 마법처럼 파드가 3개로 늘어났습니다. 기존 파드를 죽이지 않고 점진적으로 새 파드가 추가되었습니다.

이것이 바로 Kubernetes의 롤링 업데이트이고, Helm이 이를 자연스럽게 트리거한 것입니다. 그런데 문제가 생겼습니다.

새 버전의 이미지로 업그레이드했는데 애플리케이션이 제대로 동작하지 않았습니다. 에러 로그가 쏟아지기 시작했습니다.

김개발 씨의 얼굴이 하얗게 질렸습니다. 박시니어 씨가 침착하게 말했습니다.

"걱정 마세요. 롤백하면 됩니다." helm rollback은 릴리스를 이전 리비전으로 되돌립니다.

Helm은 모든 배포를 리비전이라는 단위로 저장합니다. helm history my-app 명령을 실행하면 지금까지의 모든 배포 이력이 나타납니다.

언제 배포했는지, 어떤 상태인지, 무슨 차트 버전이었는지 모두 기록되어 있습니다. helm rollback my-app 1을 실행하자 순식간에 이전 버전으로 돌아갔습니다.

에러 로그가 멈추고 정상적인 응답이 돌아왔습니다. 김개발 씨는 안도의 한숨을 내쉬었습니다.

"정말 다행이네요. 예전에는 롤백하려면 이전 YAML 파일을 찾아서 다시 적용해야 했는데..." 실무에서 이 명령어들은 어떻게 조합해서 쓸까요?

일반적인 배포 파이프라인에서는 CI/CD 도구가 helm upgrade --install 명령을 사용합니다. 이 명령은 릴리스가 없으면 설치하고, 있으면 업그레이드합니다.

덕분에 스크립트를 단순하게 유지할 수 있습니다. 또한 --atomic 옵션을 추가하면 배포 중 문제가 생길 경우 자동으로 롤백됩니다.

주의할 점도 있습니다. 롤백은 Helm이 관리하는 리소스만 되돌립니다.

만약 kubectl로 직접 수정한 부분이 있다면 그 변경사항은 추적되지 않습니다. 따라서 Helm으로 관리하는 리소스는 가능하면 Helm을 통해서만 수정해야 합니다.

그래야 이력이 정확하게 유지됩니다. 또한 helm uninstall을 실행하면 해당 릴리스의 모든 리소스와 히스토리가 삭제됩니다.

혹시라도 히스토리를 유지하고 싶다면 --keep-history 옵션을 사용할 수 있습니다. 김개발 씨가 정리하듯 말했습니다.

"install로 시작하고, upgrade로 변경하고, 문제가 생기면 rollback. 이 세 가지가 핵심이군요!" 박시니어 씨가 고개를 끄덕였습니다.

"맞아요. 그리고 항상 history로 현재 상태를 확인하는 습관을 들이세요."

실전 팁

💡 - helm upgrade --install을 사용하면 릴리스 존재 여부와 관계없이 한 명령으로 처리됩니다

• --atomic 옵션을 추가하면 배포 실패 시 자동 롤백됩니다
• --wait 옵션으로 모든 리소스가 Ready 상태가 될 때까지 기다릴 수 있습니다

---

4. Values 파일 활용

어느 날 김개발 씨에게 새로운 미션이 주어졌습니다. "같은 애플리케이션을 개발, 스테이징, 프로덕션 세 환경에 배포해주세요.

각 환경마다 리소스와 설정이 달라야 해요." 예전 같았으면 YAML 파일을 세 벌 만들었을 텐데, Helm에는 더 좋은 방법이 있습니다.

Values 파일은 차트의 동작을 제어하는 설정 파일입니다. 마치 게임의 난이도 설정처럼 같은 게임이라도 이지 모드와 하드 모드가 다르듯이, 같은 차트라도 Values 파일에 따라 전혀 다른 환경을 구성할 수 있습니다.

환경별로 다른 Values 파일을 준비해두면 코드 중복 없이 여러 환경을 관리할 수 있습니다.

다음 코드를 살펴봅시다.

# values-dev.yaml
replicaCount: 1
image:
  tag: "latest"
resources:
  limits:
    cpu: 100m
    memory: 128Mi

# values-prod.yaml
replicaCount: 3
image:
  tag: "v1.2.3"
resources:
  limits:
    cpu: 1000m
    memory: 1Gi

# 개발 환경 배포
helm install my-app ./mychart -f values-dev.yaml

# 프로덕션 환경 배포
helm install my-app ./mychart -f values-prod.yaml

# 여러 Values 파일 조합 (뒤의 파일이 앞의 값을 덮어씀)
helm install my-app ./mychart -f values.yaml -f values-prod.yaml

# 명령줄에서 직접 값 지정
helm install my-app ./mychart --set replicaCount=5

박시니어 씨가 김개발 씨에게 질문했습니다. "만약 개발 환경용 YAML, 스테이징용 YAML, 프로덕션용 YAML을 따로 만들면 어떤 문제가 생길까요?" 김개발 씨가 잠시 생각하다가 답했습니다.

"음... 하나를 수정하면 다른 것들도 다 수정해야 하니까 실수하기 쉬울 것 같아요." 정확합니다.

이런 문제를 해결하기 위해 Helm은 Values 파일 시스템을 제공합니다. Values 파일을 이해하려면 자동차 공장을 생각해보면 좋습니다.

같은 자동차 모델이라도 기본형, 고급형, 스포츠형이 있습니다. 차체와 엔진 같은 기본 설계는 동일하지만, 옵션에 따라 내장재나 편의 장치가 달라집니다.

Helm 차트도 마찬가지입니다. 템플릿은 동일하고 Values 파일만 바꿔서 다양한 구성을 만들어냅니다.

먼저 차트의 기본 values.yaml을 봅시다. 모든 차트에는 기본 values.yaml이 포함되어 있습니다.

이 파일에는 차트가 제공하는 모든 설정 옵션과 기본값이 정의되어 있습니다. 사용자가 아무 값도 지정하지 않으면 이 기본값이 사용됩니다.

환경별로 다른 설정이 필요할 때는 별도의 Values 파일을 만듭니다. 위 코드 예제처럼 values-dev.yaml과 values-prod.yaml을 각각 만들어둡니다.

개발 환경에서는 리소스를 적게 할당하고 latest 태그를 사용합니다. 반면 프로덕션 환경에서는 레플리카를 여러 개 띄우고, 검증된 특정 버전 태그를 사용하며, 더 많은 리소스를 할당합니다.

배포할 때는 -f 옵션으로 Values 파일을 지정합니다. helm install my-app ./mychart -f values-prod.yaml처럼 사용하면 기본 values.yaml 위에 values-prod.yaml의 값이 덮어씌워집니다.

마치 스티커를 붙이듯이 필요한 값만 변경할 수 있습니다. 여러 Values 파일을 조합할 수도 있습니다.

-f 옵션을 여러 번 사용하면 순서대로 값이 병합됩니다. 뒤에 오는 파일이 앞의 값을 덮어씁니다.

이를 활용하면 공통 설정 파일과 환경별 설정 파일을 분리해서 관리할 수 있습니다. 예를 들어 -f values-common.yaml -f values-prod.yaml처럼 조합하면 공통 설정 위에 프로덕션 설정이 추가됩니다.

급하게 테스트할 때는 --set 옵션이 유용합니다. 파일을 수정하지 않고 명령줄에서 직접 값을 지정할 수 있습니다.

--set replicaCount=5처럼 사용하면 해당 값만 즉시 변경됩니다. 디버깅이나 임시 테스트에 편리하지만, 프로덕션 배포에서는 가능하면 Values 파일로 관리하는 것이 좋습니다.

명령줄 옵션은 이력 추적이 어렵기 때문입니다. 실무에서는 이렇게 활용합니다.

대부분의 팀은 Git 저장소에 환경별 Values 파일을 보관합니다. values-dev.yaml, values-staging.yaml, values-prod.yaml을 각각 만들어두고, CI/CD 파이프라인에서 환경에 맞는 파일을 자동으로 선택해서 배포합니다.

이렇게 하면 배포 명령어는 동일하고 설정만 다르게 할 수 있습니다. 주의할 점이 있습니다.

Values 파일에 비밀번호나 API 키 같은 민감한 정보를 직접 넣으면 안 됩니다. 이런 값들은 Kubernetes Secret으로 별도 관리하거나, Helm Secrets 플러그인을 사용해서 암호화해야 합니다.

Git에 평문 비밀번호가 올라가면 보안 사고로 이어질 수 있습니다. 김개발 씨가 환하게 웃었습니다.

"이제 환경마다 YAML 파일을 따로 관리하지 않아도 되겠네요!" 박시니어 씨도 고개를 끄덕였습니다. "네, 차트는 하나고 Values 파일만 바꾸면 됩니다.

DRY 원칙을 지키는 거죠."

실전 팁

💡 - helm show values 차트명으로 차트의 모든 설정 옵션을 확인한 후 필요한 것만 오버라이드하세요

• 민감한 정보는 Values 파일에 직접 넣지 말고 Kubernetes Secret이나 Helm Secrets 플러그인을 사용하세요

---

5. 커스텀 차트 작성

김개발 씨의 팀에서 자체 개발한 마이크로서비스를 배포해야 할 일이 생겼습니다. 공개 차트 저장소를 뒤져봐도 우리 애플리케이션에 딱 맞는 차트는 없었습니다.

"직접 차트를 만들어야 할 것 같은데..." 박시니어 씨가 말했습니다. "걱정 마세요.

생각보다 어렵지 않아요."

커스텀 차트를 만들면 우리 팀만의 배포 표준을 정립할 수 있습니다. 마치 요리사가 자신만의 레시피북을 만드는 것처럼, 한 번 잘 만들어두면 팀원 누구나 일관된 방식으로 배포할 수 있게 됩니다.

Helm은 helm create 명령으로 기본 차트 뼈대를 자동 생성해주기 때문에 빈 파일부터 시작할 필요가 없습니다.

다음 코드를 살펴봅시다.

# 새 차트 생성
helm create myapp

# 생성된 templates/deployment.yaml 예시
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "myapp.selectorLabels" . | nindent 6 }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}

# 차트 문법 검증
helm lint ./myapp

# 렌더링 결과 미리보기
helm template my-release ./myapp

박시니어 씨가 터미널에서 helm create myapp을 실행했습니다. 순식간에 폴더와 파일들이 생성되었습니다.

"이게 차트의 기본 뼈대예요. 여기서 시작해서 우리 애플리케이션에 맞게 수정하면 됩니다." 김개발 씨가 생성된 파일들을 열어보았습니다.

뭔가 익숙하면서도 낯선 문법이 눈에 들어왔습니다. 중괄호 두 개로 감싸진 부분들이 여기저기 보였습니다.

Helm 템플릿은 Go 템플릿 문법을 사용합니다. {{ }}로 감싸진 부분은 동적으로 값이 치환되는 곳입니다.

예를 들어 {{ .Values.replicaCount }}는 values.yaml에 정의된 replicaCount 값으로 대체됩니다. 마치 편지의 [이름] 부분에 실제 이름이 들어가는 것처럼요.

몇 가지 핵심 템플릿 문법을 알아봅시다. .Values는 values.yaml의 값에 접근합니다.

.Values.image.repository처럼 점으로 깊이 들어갈 수 있습니다. .Chart는 Chart.yaml의 정보에 접근합니다.

차트 이름이나 버전을 가져올 때 사용합니다. .Release는 현재 릴리스의 정보를 담고 있습니다.

.Release.Name은 helm install 할 때 지정한 릴리스 이름입니다. include 함수는 재사용 가능한 템플릿을 호출합니다.

_helpers.tpl 파일을 보면 define으로 정의된 템플릿들이 있습니다. 예를 들어 "myapp.fullname"은 릴리스 이름과 차트 이름을 조합해서 고유한 리소스 이름을 만들어줍니다.

이렇게 공통 로직을 한 곳에 정의해두면 모든 템플릿에서 재사용할 수 있습니다. 조건문과 반복문도 사용할 수 있습니다.

{{- if .Values.ingress.enabled }}와 {{- end }} 사이에 있는 내용은 ingress.enabled가 true일 때만 렌더링됩니다. {{- range }}를 사용하면 리스트를 순회하면서 반복적인 내용을 생성할 수 있습니다.

이런 제어 구조 덕분에 하나의 템플릿으로 다양한 구성을 표현할 수 있습니다. 차트를 만들었으면 검증하는 습관이 중요합니다.

helm lint ./myapp 명령은 차트의 문법 오류나 잠재적인 문제를 검사합니다. 오류가 있으면 어느 파일의 몇 번째 줄이 문제인지 알려줍니다.

helm template my-release ./myapp 명령은 실제로 생성될 YAML을 미리 보여줍니다. 배포하기 전에 이 명령으로 의도한 대로 렌더링되는지 확인하세요.

실무에서 차트를 만들 때 주의할 점이 있습니다. 첫째, 모든 것을 설정 가능하게 만들려고 하지 마세요.

처음에는 꼭 필요한 것만 Values로 노출하고, 필요할 때 추가하는 것이 좋습니다. 둘째, 기본값은 "안전한" 값으로 설정하세요.

누군가 values 지정 없이 설치해도 문제없이 동작해야 합니다. 셋째, NOTES.txt에 유용한 정보를 꼭 넣으세요.

설치 후 어떻게 접속하는지, 초기 설정은 어떻게 하는지 안내하면 사용자 경험이 좋아집니다. 김개발 씨가 몇 시간 동안 씨름한 끝에 첫 커스텀 차트를 완성했습니다.

helm lint도 통과하고 helm template으로 결과도 확인했습니다. "이제 우리 팀만의 배포 표준이 생겼네요!" 박시니어 씨가 덧붙였습니다.

"잘했어요. 이 차트를 Git에 올려두면 다른 팀원들도 똑같이 배포할 수 있어요.

코드 리뷰도 받을 수 있고요."

실전 팁

💡 - helm create로 생성된 기본 차트를 먼저 분석하면서 템플릿 문법을 익히세요

• helm template 명령으로 배포 전 항상 렌더링 결과를 확인하는 습관을 들이세요
• _helpers.tpl의 헬퍼 함수를 적극 활용하면 템플릿이 깔끔해집니다

---

6. 차트 저장소 관리

김개발 씨가 만든 커스텀 차트가 팀 내에서 인기를 얻기 시작했습니다. 다른 팀에서도 "그 차트 어디서 받을 수 있어요?"라고 물어왔습니다.

매번 Git 저장소 주소를 알려주기도 번거롭고, 버전 관리도 체계적으로 하고 싶었습니다. "차트 저장소를 만들 때가 된 것 같군요."

**차트 저장소(Chart Repository)**는 Helm 차트를 호스팅하고 공유하는 곳입니다. 마치 npm의 npmjs.com이나 Python의 PyPI처럼, Helm에도 차트를 배포하고 검색할 수 있는 저장소 시스템이 있습니다.

공개 저장소를 사용할 수도 있고, 조직 내부용 프라이빗 저장소를 구축할 수도 있습니다.

다음 코드를 살펴봅시다.

# 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add stable https://charts.helm.sh/stable

# 저장소 목록 확인
helm repo list

# 저장소 업데이트 (최신 차트 정보 가져오기)
helm repo update

# 저장소에서 차트 검색
helm search repo nginx
helm search repo nginx --versions

# 차트 패키징 (배포용 .tgz 파일 생성)
helm package ./myapp

# index.yaml 생성 (저장소 메타데이터)
helm repo index ./charts-repo --url https://example.com/charts

# GitHub Pages를 차트 저장소로 사용할 때
# charts-repo/ 폴더에 .tgz 파일들과 index.yaml을 올리면 끝

박시니어 씨가 설명하기 시작했습니다. "차트 저장소는 생각보다 단순해요.

결국 HTTP 서버에 차트 파일과 인덱스 파일을 올려두는 것뿐이에요." 차트 저장소의 구조를 이해해봅시다. 저장소는 크게 두 가지로 구성됩니다.

하나는 .tgz 파일들입니다. helm package 명령으로 차트 폴더를 압축하면 myapp-0.1.0.tgz 같은 파일이 생성됩니다.

다른 하나는 index.yaml 파일입니다. 이 파일에는 저장소에 있는 모든 차트의 메타데이터가 들어있습니다.

이름, 버전, 다운로드 URL 등이 기록되어 있어서 Helm이 이 파일만 읽으면 어떤 차트가 있는지 알 수 있습니다. 가장 간단한 방법은 GitHub Pages를 활용하는 것입니다.

GitHub 저장소를 하나 만들고, gh-pages 브랜치에 차트 패키지(.tgz)와 index.yaml을 올립니다. GitHub Pages를 활성화하면 바로 차트 저장소가 됩니다.

무료이고 설정도 간단해서 개인 프로젝트나 소규모 팀에 적합합니다. 회사에서는 프라이빗 저장소가 필요할 수 있습니다.

Harbor, ChartMuseum, JFrog Artifactory 같은 솔루션들이 있습니다. 이런 도구들은 인증, 권한 관리, 차트 서명 등 엔터프라이즈 기능을 제공합니다.

특히 Harbor는 컨테이너 이미지 저장소와 Helm 차트 저장소를 함께 제공해서 많은 기업에서 사용합니다. 저장소를 사용하는 방법을 알아봅시다.

helm repo add 명령으로 저장소를 등록합니다. 한 번 등록하면 로컬에 저장되어 이후에도 계속 사용할 수 있습니다.

helm repo update는 등록된 모든 저장소에서 최신 index.yaml을 다운로드합니다. 새 차트가 올라왔는지 확인하려면 이 명령을 실행해야 합니다.

helm search로 차트를 검색할 수 있습니다. helm search repo nginx는 등록된 저장소에서 nginx라는 이름이 포함된 차트를 찾습니다.

--versions 옵션을 추가하면 모든 버전을 보여줍니다. 특정 버전을 설치하고 싶으면 helm install my-nginx bitnami/nginx --version 13.2.0처럼 지정합니다.

차트를 배포할 때는 helm package로 패키징합니다. helm package ./myapp을 실행하면 Chart.yaml에 정의된 버전으로 myapp-0.1.0.tgz 파일이 생성됩니다.

버전을 올릴 때마다 Chart.yaml의 version 필드를 수정하고 다시 패키징하면 됩니다. 패키징된 파일을 저장소에 올리고 helm repo index로 index.yaml을 업데이트하면 배포 완료입니다.

실무에서의 워크플로우는 이렇습니다. 대부분의 팀은 CI/CD 파이프라인에서 차트 패키징과 저장소 업데이트를 자동화합니다.

개발자가 차트 코드를 수정하고 버전을 올려서 PR을 만들면, 머지 후에 파이프라인이 자동으로 패키징하고 저장소에 올립니다. 사용자는 helm repo update만 실행하면 새 버전을 바로 사용할 수 있습니다.

주의할 점이 있습니다. 버전 관리를 철저히 해야 합니다.

한 번 배포한 버전의 내용을 수정하면 안 됩니다. 다른 사람이 같은 버전을 설치했을 때 다른 결과가 나오면 혼란이 생깁니다.

수정이 필요하면 반드시 새 버전으로 올려야 합니다. 시맨틱 버저닝(SemVer)을 따르는 것을 권장합니다.

김개발 씨가 GitHub Pages로 첫 차트 저장소를 만들었습니다. 다른 팀원들이 helm repo add myteam https://kimdev.github.io/charts로 등록하고 바로 차트를 사용하기 시작했습니다.

"이제 정말 제대로 된 배포 시스템이 갖춰진 것 같아요!" 박시니어 씨가 흐뭇하게 웃었습니다. "축하해요.

이제 Helm의 기본기는 다 익힌 거예요. 앞으로는 경험을 쌓으면서 더 복잡한 차트도 만들어보세요."

실전 팁

💡 - GitHub Pages나 GitLab Pages를 활용하면 무료로 차트 저장소를 운영할 수 있습니다

• Artifact Hub(artifacthub.io)에 차트를 등록하면 전 세계 개발자들이 검색하고 사용할 수 있습니다
• 프라이빗 저장소가 필요하다면 Harbor나 ChartMuseum을 검토해보세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!