Helm 차트 기초 완벽 가이드

쿠버네티스 패키지 매니저 Helm의 기본 개념부터 차트 구조까지 실무에서 바로 활용할 수 있도록 친절하게 설명합니다. 초급 개발자도 쉽게 따라할 수 있는 실전 예제와 함께 Helm 차트의 핵심을 마스터해보세요.

1. Helm이란?

어느 날 김개발 씨는 쿠버네티스 클러스터에 애플리케이션을 배포하려고 했습니다. 그런데 Deployment, Service, ConfigMap, Ingress 등 수십 개의 YAML 파일을 일일이 관리해야 했습니다.

"이걸 하나하나 다 만들어야 하나요?" 선배 박시니어 씨가 웃으며 대답했습니다. "Helm을 쓰면 훨씬 쉬워질 거예요."

Helm은 쿠버네티스를 위한 패키지 매니저입니다. 마치 npm이 Node.js의 패키지를 관리하듯이, Helm은 쿠버네티스 리소스를 패키지로 묶어서 관리합니다.

복잡한 애플리케이션도 한 번의 명령으로 설치하고, 업그레이드하고, 롤백할 수 있습니다.

다음 코드를 살펴봅시다.

# Helm으로 애플리케이션 설치하기
# 차트 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami

# 저장소 업데이트
helm repo update

# WordPress 설치 - 단 한 줄로!
helm install my-wordpress bitnami/wordpress

# 설치된 릴리스 확인
helm list

# 업그레이드도 간단하게
helm upgrade my-wordpress bitnami/wordpress --set wordpressPassword=newpassword

김개발 씨는 입사 2개월 차 백엔드 개발자입니다. 처음으로 쿠버네티스에 애플리케이션을 배포하는 임무를 맡았습니다.

회사 위키를 찾아보니 Deployment, Service, ConfigMap, Secret, Ingress 등 무려 15개의 YAML 파일을 작성해야 했습니다. 한 파일 한 파일 작성하다 보니 오타도 나고, 설정값도 헷갈렸습니다.

"분명히 포트 번호를 8080으로 맞췄는데 왜 연결이 안 되지?" 디버깅만 2시간이 걸렸습니다. 더 큰 문제는 개발, 스테이징, 프로덕션 환경마다 설정값이 달라서 파일을 일일이 수정해야 한다는 점이었습니다.

바로 그때 선배 박시니어 씨가 지나가다 화면을 보고 말했습니다. "아직도 수작업으로 하고 있어요?

Helm 쓰면 10분이면 끝나는데." 그렇다면 Helm은 정확히 무엇일까요? 쉽게 비유하자면, Helm은 마치 스마트폰의 앱스토어와 같습니다.

앱스토어에서 앱을 검색하고 설치 버튼만 누르면 복잡한 설치 과정이 자동으로 진행되는 것처럼, Helm도 애플리케이션을 검색하고 한 번의 명령으로 설치할 수 있습니다. 앱을 업데이트하거나 삭제하는 것도 버튼 하나로 가능하듯이, Helm도 동일한 방식으로 작동합니다.

Helm이 없던 시절에는 어땠을까요? 개발자들은 수십 개의 YAML 파일을 직접 작성하고 관리해야 했습니다.

환경이 바뀔 때마다 파일을 복사해서 값을 수정하고, 버전 관리도 직접 해야 했습니다. 더 큰 문제는 롤백이었습니다.

배포 후 문제가 생기면 이전 버전의 모든 YAML 파일을 다시 찾아서 적용해야 했습니다. 프로젝트가 커질수록 이런 작업은 악몽이 되었습니다.

바로 이런 문제를 해결하기 위해 Helm이 등장했습니다. Helm을 사용하면 패키징이 가능해집니다.

관련된 모든 쿠버네티스 리소스를 하나의 차트로 묶을 수 있습니다. 또한 템플릿화도 얻을 수 있습니다.

변수를 사용해서 환경별로 다른 값을 주입할 수 있습니다. 무엇보다 버전 관리와 롤백이라는 큰 이점이 있습니다.

배포 이력을 자동으로 관리하고, 문제가 생기면 이전 버전으로 즉시 돌아갈 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 helm repo add 명령으로 차트 저장소를 추가합니다. 이것은 마치 npm에서 레지스트리를 추가하는 것과 같습니다.

다음으로 helm install 명령 하나로 WordPress와 필요한 모든 리소스가 설치됩니다. Deployment, Service, PersistentVolumeClaim 등이 자동으로 생성됩니다.

마지막으로 helm upgrade로 설정을 변경하면서 업그레이드할 수 있습니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 마이크로서비스 아키텍처를 운영하는 회사를 생각해봅시다. 사용자 서비스, 주문 서비스, 결제 서비스 등 10개의 서비스가 있고, 각 서비스마다 데이터베이스, 캐시, 메시지 큐가 필요합니다.

Helm을 활용하면 각 서비스를 차트로 만들어두고, helm install 명령 하나로 전체 스택을 배포할 수 있습니다. Netflix, Spotify 같은 많은 기업에서 이런 패턴을 적극적으로 사용하고 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 Helm을 만능 도구로 생각하는 것입니다.

간단한 애플리케이션까지 무조건 Helm으로 관리하려다 오히려 복잡도가 높아질 수 있습니다. 따라서 리소스가 5개 이상이거나, 여러 환경에 배포해야 하는 경우에 Helm을 사용하는 것이 좋습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 눈이 반짝였습니다.

"이렇게 편한 도구가 있었다니!" Helm을 제대로 이해하면 쿠버네티스 배포가 훨씬 쉬워지고, 실수도 줄어듭니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - helm repo list 명령으로 등록된 저장소를 확인할 수 있습니다

helm search repo [키워드] 명령으로 필요한 차트를 검색할 수 있습니다
helm history [릴리스명] 명령으로 배포 이력을 확인하고 원하는 버전으로 롤백할 수 있습니다

2. Helm 설치

김개발 씨는 Helm이 무엇인지 알게 되었습니다. 이제 직접 사용해보고 싶었습니다.

"어떻게 설치하죠?" 박시니어 씨가 터미널을 열며 말했습니다. "생각보다 간단해요.

3분이면 끝나요."

Helm 설치는 매우 간단합니다. 리눅스, macOS, Windows 모두 지원하며, 패키지 매니저를 통해 쉽게 설치할 수 있습니다.

설치 후에는 kubectl처럼 helm 명령을 사용할 수 있습니다.

다음 코드를 살펴봅시다.

# macOS에서 Homebrew로 설치
brew install helm

# Linux에서 스크립트로 설치
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows에서 Chocolatey로 설치
choco install kubernetes-helm

# 설치 확인
helm version

# Kubernetes 클러스터 연결 확인
helm list

김개발 씨는 맥북을 사용하고 있었습니다. "설치가 어렵지 않을까?" 걱정했지만, 박시니어 씨가 보여준 방법은 놀라울 정도로 간단했습니다.

터미널을 열고 단 한 줄의 명령어를 입력했습니다. brew install helm.

커피 한 모금 마시는 사이에 설치가 완료되었습니다. "이게 끝이에요?" 김개발 씨가 놀라서 물었습니다.

Helm 설치는 정말 간단합니다. 왜 이렇게 쉬울까요?

Helm은 단일 바이너리 파일로 배포됩니다. 마치 kubectl처럼 하나의 실행 파일만 있으면 모든 기능을 사용할 수 있습니다.

복잡한 의존성도 없고, 별도의 데이터베이스나 서버도 필요 없습니다. 그저 실행 파일 하나를 PATH에 추가하면 끝입니다.

운영체제별로 설치 방법이 조금씩 다릅니다만, 모두 쉽습니다. macOS 사용자라면 Homebrew를 사용하는 것이 가장 편합니다.

Homebrew는 macOS에서 가장 인기 있는 패키지 매니저입니다. brew install helm 한 줄이면 최신 버전의 Helm이 설치되고, 업데이트도 brew upgrade helm으로 간단히 할 수 있습니다.

Linux 사용자는 공식 설치 스크립트를 사용할 수 있습니다. curl 명령으로 스크립트를 다운로드하고 bash로 실행하면, 자동으로 시스템에 맞는 바이너리를 다운로드하고 설치합니다.

Ubuntu, CentOS, Fedora 등 대부분의 배포판에서 동일하게 작동합니다. Windows 사용자는 Chocolatey나 Scoop 같은 패키지 매니저를 사용할 수 있습니다.

PowerShell을 관리자 권한으로 실행하고 choco install kubernetes-helm 명령을 입력하면 됩니다. 또는 GitHub 릴리스 페이지에서 zip 파일을 직접 다운로드할 수도 있습니다.

설치가 완료되었다면 반드시 확인해야 합니다. helm version 명령을 실행해보세요.

버전 정보가 출력되면 설치가 성공한 것입니다. 현재 최신 버전은 Helm 3입니다.

Helm 2와는 많은 부분이 달라졌는데, 가장 큰 차이는 Tiller가 제거되었다는 점입니다. Helm 2에서는 클러스터 안에 Tiller라는 서버 컴포넌트가 필요했지만, Helm 3는 클라이언트만으로 모든 작업이 가능합니다.

다음으로 Kubernetes 클러스터와의 연결을 확인해야 합니다. helm list 명령을 실행해보세요.

에러가 나지 않고 빈 목록이나 기존 릴리스 목록이 출력되면 정상입니다. Helm은 kubectl과 동일한 kubeconfig 파일을 사용합니다.

즉, kubectl이 정상적으로 작동한다면 Helm도 자동으로 동일한 클러스터에 연결됩니다. 실무에서 자주 겪는 문제가 하나 있습니다.

회사에서 여러 개의 Kubernetes 클러스터를 사용하는 경우, 어떤 클러스터에 연결되어 있는지 헷갈릴 수 있습니다. kubectl config current-context 명령으로 현재 컨텍스트를 확인하고, kubectl config use-context [컨텍스트명] 명령으로 전환할 수 있습니다.

Helm은 자동으로 kubectl의 현재 컨텍스트를 따라갑니다. 김개발 씨는 helm version을 실행해보았습니다.

"version.BuildInfo{Version:"v3.14.0"...}" 버전 정보가 화면에 출력되었습니다. "성공했어요!" 이제 본격적으로 Helm을 사용할 준비가 완료되었습니다.

Helm 설치는 첫 번째 단계일 뿐입니다. 하지만 이 간단한 설치 과정 덕분에 누구나 쉽게 Helm을 시작할 수 있습니다.

여러분도 지금 바로 터미널을 열고 설치해보세요.

실전 팁

💡 - Helm 3를 사용하세요. Helm 2는 2020년에 지원이 종료되었습니다

helm completion bash 명령으로 자동완성을 활성화하면 더욱 편리합니다
helm plugin list 명령으로 유용한 플러그인을 추가할 수 있습니다

3. Chart 구조

Helm을 설치한 김개발 씨는 이제 차트를 만들어보고 싶었습니다. "차트는 어떻게 생겼나요?" 박시니어 씨가 helm create 명령으로 샘플 차트를 만들어 보여주었습니다.

폴더를 열어보니 여러 파일과 디렉토리가 보였습니다.

Helm 차트는 특정한 디렉토리 구조를 가진 파일들의 모음입니다. Chart.yaml, values.yaml, templates 디렉토리가 핵심이며, 각각 메타데이터, 설정값, 쿠버네티스 리소스 템플릿을 담당합니다.

이 구조를 이해하면 차트를 자유롭게 만들고 수정할 수 있습니다.

다음 코드를 살펴봅시다.

# 새로운 차트 생성
helm create myapp

# 생성된 차트 구조 확인
tree myapp/

# 출력 결과:
# myapp/
# ├── Chart.yaml          # 차트 메타데이터
# ├── values.yaml         # 기본 설정값
# ├── charts/             # 의존성 차트
# ├── templates/          # 쿠버네티스 리소스 템플릿
# │   ├── deployment.yaml
# │   ├── service.yaml
# │   ├── ingress.yaml
# │   └── _helpers.tpl    # 템플릿 헬퍼 함수
# └── .helmignore         # 패키징 시 제외할 파일

김개발 씨는 helm create myapp 명령을 입력했습니다. 순식간에 myapp이라는 디렉토리가 생성되고, 그 안에 여러 파일이 만들어졌습니다.

VS Code로 폴더를 열어보니 낯선 파일 이름들이 보였습니다. "이게 다 뭐예요?" 김개발 씨가 물었습니다.

박시니어 씨가 하나씩 설명해주었습니다. "각 파일이 다 역할이 있어요.

마치 집을 짓는 것처럼 설계도, 자재 목록, 시공 지침이 따로 있는 거죠." Helm 차트의 구조는 매우 체계적입니다. 가장 먼저 눈에 띄는 것은 Chart.yaml 파일입니다.

이 파일은 마치 책의 표지와 같습니다. 차트의 이름, 버전, 설명, 작성자 정보가 들어있습니다.

누군가 이 차트를 검색하거나 설치하려 할 때 가장 먼저 보는 정보입니다. 두 번째로 중요한 것은 values.yaml 파일입니다.

이 파일은 마치 설정 파일과 같습니다. 컨테이너 이미지 이름, 포트 번호, 리소스 제한, 환경변수 등 모든 설정값이 여기에 모여있습니다.

사용자가 차트를 설치할 때 이 값들을 원하는 대로 변경할 수 있습니다. 예를 들어 개발 환경에서는 레플리카를 1개로, 프로덕션에서는 3개로 설정하는 식입니다.

세 번째 핵심은 templates 디렉토리입니다. 이 디렉토리가 차트의 심장부입니다.

실제 쿠버네티스 리소스 파일들이 템플릿 형태로 들어있습니다. deployment.yaml은 Deployment를 만들고, service.yaml은 Service를 만들고, ingress.yaml은 Ingress를 만듭니다.

하지만 일반 YAML 파일과 다른 점이 있습니다. 바로 변수를 사용한다는 것입니다.

템플릿 파일을 열어보면 이상한 문법이 보입니다. 중괄호 두 개로 감싸진 표현식들입니다.

예를 들어 {{ .Values.image.repository }}처럼 생긴 것들이 있습니다. 이것이 바로 Go 템플릿 문법입니다.

Helm이 차트를 설치할 때 이런 표현식을 values.yaml의 실제 값으로 치환합니다. 마치 Word의 메일 머지 기능처럼 말입니다.

charts 디렉토리는 의존성을 관리합니다. 만약 여러분의 애플리케이션이 PostgreSQL 데이터베이스가 필요하다면 어떻게 할까요?

PostgreSQL 차트를 의존성으로 추가하면 됩니다. Chart.yaml에 의존성을 선언하고, helm dependency update 명령을 실행하면 필요한 차트가 charts 디렉토리에 다운로드됩니다.

그러면 helm install 한 번으로 애플리케이션과 데이터베이스가 함께 설치됩니다. _helpers.tpl 파일은 특별합니다.

이 파일은 템플릿에서 반복적으로 사용되는 코드를 함수처럼 정의해두는 곳입니다. 예를 들어 레이블을 만드는 로직이 여러 리소스에서 반복된다면, _helpers.tpl에 정의해두고 재사용할 수 있습니다.

코드 중복을 줄이고 유지보수를 쉽게 만듭니다. .helmignore 파일도 유용합니다.

이것은 .gitignore와 비슷합니다. 차트를 패키징할 때 포함하지 않을 파일이나 디렉토리를 지정합니다.

개발 중에 만든 테스트 파일이나 임시 파일을 제외하고 싶을 때 사용합니다. 실무에서는 이 구조를 어떻게 활용할까요?

예를 들어 마이크로서비스를 배포한다고 해봅시다. 먼저 helm create로 기본 구조를 만듭니다.

그다음 templates 디렉토리에 필요한 리소스를 추가합니다. Deployment만 있다면 Service를 추가하고, 외부 접근이 필요하면 Ingress를 추가합니다.

values.yaml에는 환경별로 다를 수 있는 모든 설정을 빼냅니다. 이렇게 만든 차트 하나로 개발, 스테이징, 프로덕션 모든 환경에 배포할 수 있습니다.

주의할 점이 있습니다. 초보자들은 templates 디렉토리에 너무 많은 파일을 만들려 합니다.

처음에는 꼭 필요한 리소스만 만드세요. Deployment와 Service만 있어도 충분히 작동합니다.

Ingress, ConfigMap, Secret 등은 실제로 필요할 때 추가하면 됩니다. 김개발 씨는 각 파일을 하나씩 열어보며 구조를 이해했습니다.

"아, 이렇게 체계적으로 되어있구나!" 처음에는 복잡해 보였지만, 각 파일의 역할을 알고 나니 오히려 명확하고 깔끔하다는 생각이 들었습니다. 차트 구조를 이해하는 것은 Helm 마스터로 가는 필수 과정입니다.

이 구조만 알면 어떤 차트든 읽고 수정할 수 있습니다. 여러분도 helm create로 직접 차트를 만들어보며 구조를 익혀보세요.

실전 팁

💡 - helm create로 생성된 기본 차트를 템플릿으로 활용하세요

필요 없는 파일은 과감히 삭제해도 됩니다 (예: ingress.yaml이 필요 없다면 삭제)
helm lint 명령으로 차트 구조가 올바른지 검증할 수 있습니다

4. templates 디렉토리

김개발 씨는 templates 디렉토리를 열어보았습니다. deployment.yaml 파일에는 일반 YAML과 다른 이상한 문법이 가득했습니다.

"이 중괄호들은 뭔가요?" 박시니어 씨가 미소를 지으며 대답했습니다. "바로 Helm의 핵심이에요.

템플릿 엔진이죠."

templates 디렉토리는 쿠버네티스 리소스 파일들을 템플릿 형태로 저장하는 곳입니다. Go 템플릿 문법을 사용해서 변수, 조건문, 반복문을 활용할 수 있습니다.

이를 통해 하나의 템플릿으로 다양한 환경에 맞는 리소스를 생성할 수 있습니다.

다음 코드를 살펴봅시다.

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
  labels:
    app: {{ .Chart.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        app: {{ .Chart.Name }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: {{ .Values.service.port }}

김개발 씨가 처음 본 템플릿 파일은 충격적이었습니다. 평소에 작성하던 깔끔한 YAML 파일과 달리 {{ }}로 감싸진 표현식들이 곳곳에 박혀있었습니다.

"이게 정말 작동하는 건가요?" 박시니어 씨가 설명해주었습니다. "Helm이 설치할 때 이 템플릿을 읽고, 중괄호 안의 표현식을 실제 값으로 바꿔줍니다.

그러면 일반 YAML이 되는 거죠." templates 디렉토리의 핵심은 동적 생성입니다. 마치 프린터가 문서를 찍어내듯이, Helm은 템플릿을 읽고 실제 쿠버네티스 리소스를 생성합니다.

이 과정에서 변수를 주입하고, 조건에 따라 다른 내용을 만들고, 반복문으로 여러 개를 생성할 수도 있습니다. 이 모든 것이 templates 디렉토리에서 일어납니다.

가장 기본적인 것은 변수 치환입니다. {{ .Values.replicaCount }}라는 표현식을 봅시다.

이것은 values.yaml 파일의 replicaCount 값을 가져옵니다. 만약 values.yaml에 replicaCount: 3이라고 되어있다면, 이 표현식은 3으로 치환됩니다.

이렇게 하면 환경마다 다른 값을 쉽게 적용할 수 있습니다. 변수는 세 가지 주요 객체에서 가져올 수 있습니다.

첫째는 .Values입니다. values.yaml 파일의 모든 값에 접근할 수 있습니다.

.Values.image.repository처럼 점으로 연결해서 중첩된 값도 가져올 수 있습니다. 둘째는 .Chart입니다.

Chart.yaml에 정의된 메타데이터에 접근합니다. .Chart.Name이나 .Chart.Version 같은 값을 사용할 수 있습니다.

셋째는 .Release입니다. 현재 릴리스에 대한 정보를 담고 있습니다.

.Release.Name은 helm install 할 때 지정한 릴리스 이름이고, .Release.Namespace는 설치될 네임스페이스입니다. 조건문도 사용할 수 있습니다.

예를 들어 Ingress를 선택적으로 만들고 싶다면 이렇게 작성합니다. {{ if .Values.ingress.enabled }} 블록을 만들고, values.yaml의 ingress.enabled 값이 true일 때만 Ingress 리소스를 생성하도록 할 수 있습니다.

이렇게 하면 개발 환경에서는 Ingress를 끄고, 프로덕션에서만 켤 수 있습니다. 반복문은 더 강력합니다.

ConfigMap에 여러 개의 환경변수를 넣고 싶다면 어떻게 할까요? values.yaml에 env라는 배열을 만들고, 템플릿에서 {{ range .Values.env }} 반복문을 사용하면 됩니다.

배열의 각 항목이 자동으로 환경변수로 변환됩니다. 파이프라인 기능도 유용합니다.

{{ .Values.name | upper }}처럼 파이프 기호를 사용하면 값을 함수에 전달할 수 있습니다. upper는 문자열을 대문자로 바꾸는 함수입니다.

quote 함수는 따옴표로 감싸주고, default 함수는 기본값을 설정합니다. 여러 함수를 체인처럼 연결할 수도 있습니다.

실제 업무에서는 이런 기능을 어떻게 활용할까요? 예를 들어 회사에서 개발, 스테이징, 프로덕션 환경을 운영한다고 합시다.

개발에서는 레플리카 1개, CPU 제한 없음으로 실행하고, 프로덕션에서는 레플리카 3개, CPU 제한 1000m로 실행하고 싶습니다. 템플릿은 하나만 만들고, values.yaml 파일만 환경별로 다르게 준비하면 됩니다.

helm install -f values-dev.yaml 또는 helm install -f values-prod.yaml처럼 사용합니다. 주의해야 할 점이 있습니다.

템플릿에 너무 복잡한 로직을 넣지 마세요. 조건문이 3단계 이상 중첩되거나, 반복문 안에 또 조건문이 들어가면 읽기 어려워집니다.

복잡한 로직은 _helpers.tpl에 함수로 분리하는 것이 좋습니다. 또 하나 중요한 것은 들여쓰기입니다.

YAML은 들여쓰기에 민감합니다. 템플릿에서 값을 주입할 때 들여쓰기가 맞지 않으면 에러가 발생합니다.

indent 함수를 사용해서 올바른 위치에 들여쓰기를 추가하세요. 예를 들어 {{ .Values.config | indent 4 }}처럼 사용합니다.

김개발 씨는 직접 템플릿을 수정해보았습니다. replicaCount를 2로 바꾸고, helm install --dry-run --debug 명령으로 결과를 확인했습니다.

화면에 실제 생성될 YAML이 출력되었습니다. "와, 정말 바뀌네요!" templates 디렉토리를 마스터하면 Helm의 진정한 힘을 느낄 수 있습니다.

하나의 템플릿으로 무한한 변형을 만들어낼 수 있습니다. 여러분도 직접 템플릿을 작성하고 실험해보세요.

실전 팁

💡 - helm template 명령으로 렌더링된 결과를 미리 확인할 수 있습니다

helm install --dry-run --debug 명령으로 실제 설치 없이 테스트할 수 있습니다
toYaml 함수를 사용하면 values.yaml의 객체를 그대로 YAML로 변환할 수 있습니다

5. values.yaml 역할

김개발 씨는 템플릿을 이해했지만, 궁금한 점이 생겼습니다. "템플릿에서 사용하는 값들은 다 어디서 오는 거죠?" 박시니어 씨가 values.yaml 파일을 열어 보여주었습니다.

"바로 여기요. Helm 차트의 설정 파일이에요."

values.yaml은 차트의 모든 설정값을 중앙에서 관리하는 파일입니다. 템플릿에서 사용할 변수의 기본값을 정의하며, 사용자는 설치 시 이 값들을 원하는 대로 변경할 수 있습니다.

이를 통해 동일한 차트로 다양한 환경을 구성할 수 있습니다.

다음 코드를 살펴봅시다.

# values.yaml
replicaCount: 2

image:
  repository: nginx
  tag: "1.21.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

ingress:
  enabled: false
  className: "nginx"
  hosts:
    - host: myapp.example.com
      paths:
        - path: /
          pathType: Prefix

김개발 씨가 values.yaml 파일을 열어보니 깔끔하게 정리된 YAML 파일이었습니다. 이번에는 중괄호 같은 이상한 문법이 없었습니다.

그냥 일반적인 설정 파일처럼 보였습니다. "이건 이해하기 쉬운데요?" 박시니어 씨가 고개를 끄덕였습니다.

"맞아요. values.yaml은 개발자가 가장 자주 수정하는 파일이에요.

그래서 최대한 간단하고 명확하게 만들어야 해요." values.yaml의 핵심 역할은 설정의 중앙화입니다. 쿠버네티스에 애플리케이션을 배포할 때 설정해야 할 것들이 많습니다.

이미지 이름, 태그, 포트 번호, 리소스 제한, 환경변수, 볼륨 설정 등등. 이런 값들이 deployment.yaml, service.yaml, configmap.yaml 여기저기 흩어져 있으면 관리하기 어렵습니다.

values.yaml은 이 모든 설정을 한곳에 모아둡니다. 구조는 매우 직관적입니다.

계층적으로 구성되어 있습니다. image라는 키 아래에 repository, tag, pullPolicy가 있습니다.

service 아래에는 type과 port가 있습니다. 이렇게 관련된 설정을 그룹으로 묶으면 읽기 쉽고, 찾기도 쉽습니다.

실제로 어떻게 사용될까요? 템플릿에서 {{ .Values.image.repository }}라고 작성하면, values.yaml의 image.repository 값인 nginx가 주입됩니다.

{{ .Values.service.port }}는 80이 됩니다. 이런 식으로 템플릿과 values.yaml이 유기적으로 연결됩니다.

가장 큰 장점은 오버라이드입니다. values.yaml은 기본값만 정의합니다.

사용자는 설치할 때 이 값들을 자유롭게 변경할 수 있습니다. helm install myapp ./myapp --set replicaCount=5 명령을 실행하면, 기본값 2 대신 5가 사용됩니다.

여러 값을 바꾸려면 --set을 여러 번 사용하거나, 별도의 values 파일을 만들어서 -f 옵션으로 전달할 수 있습니다. 환경별 values 파일을 만드는 것이 일반적입니다.

기본 values.yaml은 개발 환경용으로 두고, values-prod.yaml 파일을 별도로 만듭니다. 프로덕션용 파일에는 레플리카를 5로, 리소스 제한을 더 높게 설정합니다.

배포할 때 helm install myapp ./myapp -f values-prod.yaml처럼 사용하면 됩니다. 필수 값과 선택 값을 구분하는 것도 중요합니다.

ingress.enabled: false처럼 기본값을 false로 두면, 사용자가 명시적으로 true로 바꾸지 않는 한 Ingress가 생성되지 않습니다. 이렇게 선택적인 기능은 기본적으로 비활성화해두는 것이 좋습니다.

반면 image.repository처럼 반드시 필요한 값은 합리적인 기본값을 제공해야 합니다. 주석도 적극 활용하세요.

values.yaml에 주석을 달아서 각 설정이 무엇을 의미하는지 설명하세요. 특히 값의 범위나 형식을 명시하면 좋습니다.

예를 들어 "service.type: ClusterIP, NodePort, LoadBalancer 중 하나"라고 주석을 달아두면 사용자가 실수하지 않습니다. 실무에서 자주 사용하는 패턴이 있습니다.

secrets 같은 민감한 정보는 values.yaml에 직접 넣지 않습니다. 대신 existingSecret 같은 키를 만들어서 기존에 생성된 Secret의 이름을 참조하도록 합니다.

또는 Helm Secrets 플러그인을 사용해서 암호화된 values 파일을 관리하기도 합니다. 값의 검증도 고려해야 합니다.

Helm 3부터는 values.schema.json 파일을 만들어서 values.yaml의 형식을 검증할 수 있습니다. JSON Schema 형식으로 "replicaCount는 1 이상의 정수여야 함" 같은 규칙을 정의하면, helm install 할 때 자동으로 검증됩니다.

김개발 씨는 자신의 애플리케이션에 맞게 values.yaml을 수정해보았습니다. 이미지를 회사 레지스트리로 바꾸고, 포트를 8080으로 변경했습니다.

그리고 helm install --dry-run으로 확인했습니다. "제 설정이 정확히 반영되네요!" values.yaml을 잘 설계하면 차트의 재사용성이 크게 높아집니다.

한 번 만든 차트를 모든 환경에서 사용할 수 있습니다. 여러분도 명확하고 유연한 values.yaml을 만들어보세요.

실전 팁

💡 - values.yaml은 알파벳 순서로 정렬하면 찾기 쉽습니다

중첩은 3단계를 넘지 않도록 하세요 (너무 깊으면 복잡해집니다)
helm get values [릴리스명] 명령으로 현재 사용 중인 값을 확인할 수 있습니다

6. Chart.yaml 메타데이터

김개발 씨는 차트의 핵심 구조를 모두 이해했습니다. 마지막으로 궁금한 것이 하나 남았습니다.

"Chart.yaml은 뭐하는 파일인가요?" 박시니어 씨가 파일을 열어 보여주었습니다. "차트의 신분증이에요.

이름, 버전, 작성자 정보가 들어있죠."

Chart.yaml은 차트의 메타데이터를 정의하는 필수 파일입니다. 차트의 이름, 버전, 설명, 작성자, 의존성 등을 명시합니다.

이 정보는 차트 검색, 버전 관리, 의존성 해결에 사용됩니다.

다음 코드를 살펴봅시다.

# Chart.yaml
apiVersion: v2
name: myapp
description: A Helm chart for my awesome application
type: application
version: 1.0.0
appVersion: "2.1.0"

keywords:
  - web
  - backend
  - api

maintainers:
  - name: Kim Developer
    email: kim@example.com

dependencies:
  - name: postgresql
    version: "12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

김개발 씨가 Chart.yaml을 열어보니 생각보다 간단했습니다. 몇 개의 필드만 있었습니다.

"이게 전부예요?" 박시니어 씨가 웃으며 답했습니다. "간단해 보이지만, 아주 중요한 정보들이에요." Chart.yaml의 첫 번째 역할은 차트 식별입니다.

name 필드는 차트의 고유한 이름입니다. 소문자와 하이픈만 사용할 수 있습니다.

이 이름으로 차트를 검색하고 설치합니다. 마치 npm 패키지 이름처럼 전 세계에서 유일해야 하는 것은 아니지만, 조직 내에서는 중복되지 않아야 합니다.

version 필드는 차트의 버전입니다. 시맨틱 버저닝을 따릅니다.

1.0.0 형식으로 작성하며, MAJOR.MINOR.PATCH 규칙을 사용합니다. 차트 내용이 바뀔 때마다 버전을 올려야 합니다.

템플릿이 바뀌거나, values.yaml에 새 설정이 추가되면 버전을 업데이트합니다. Helm 저장소에 차트를 게시할 때 이 버전으로 구분됩니다.

appVersion은 조금 다릅니다. 이것은 차트가 배포하는 애플리케이션의 버전입니다.

예를 들어 nginx 차트의 version이 2.0.0이고 appVersion이 1.21.0이라면, 차트 자체는 2.0.0 버전이지만 실제 배포되는 nginx는 1.21.0 버전이라는 의미입니다. 사용자가 "어떤 버전의 애플리케이션이 설치되나요?"라고 물을 때 참고하는 정보입니다.

apiVersion은 Helm 버전을 나타냅니다. Helm 3를 사용한다면 v2라고 적습니다.

Helm 2에서는 v1이었습니다. 이 필드를 보고 Helm이 차트 형식을 올바르게 해석합니다.

type 필드는 차트의 종류를 구분합니다. application은 일반적인 애플리케이션 차트입니다.

library는 다른 차트에서 재사용할 수 있는 헬퍼 함수나 템플릿을 제공하는 차트입니다. 대부분의 경우 application을 사용합니다.

description은 차트에 대한 간단한 설명입니다. 한두 문장으로 이 차트가 무엇을 배포하는지 설명합니다.

사용자가 helm search로 차트를 찾을 때 이 설명을 보고 원하는 차트인지 판단합니다. keywords는 검색을 돕습니다.

차트와 관련된 키워드를 배열로 나열합니다. 예를 들어 웹 서버 차트라면 web, http, server 같은 키워드를 추가합니다.

Helm 저장소에서 검색할 때 이 키워드가 사용됩니다. maintainers는 관리자 정보입니다.

차트를 유지보수하는 사람의 이름과 이메일을 적습니다. 문제가 생겼을 때 누구에게 문의해야 하는지 알 수 있습니다.

가장 강력한 기능은 dependencies입니다. 차트가 다른 차트에 의존할 수 있습니다.

예를 들어 웹 애플리케이션 차트가 PostgreSQL 데이터베이스를 필요로 한다면, dependencies에 postgresql 차트를 명시합니다. helm dependency update 명령을 실행하면 필요한 차트가 자동으로 다운로드됩니다.

그리고 helm install 한 번으로 애플리케이션과 데이터베이스가 함께 설치됩니다. condition 필드를 사용하면 의존성을 선택적으로 만들 수 있습니다.

condition: postgresql.enabled라고 설정하면, values.yaml의 postgresql.enabled 값이 true일 때만 PostgreSQL이 설치됩니다. 개발 환경에서는 외부 데이터베이스를 사용하고, 프로덕션에서만 차트로 설치하고 싶을 때 유용합니다.

실무에서는 Chart.yaml을 어떻게 관리할까요? CI/CD 파이프라인에서 자동으로 버전을 올리는 경우가 많습니다.

코드가 main 브랜치에 머지되면, 스크립트가 Chart.yaml의 version을 자동으로 증가시키고, 차트를 패키징해서 저장소에 업로드합니다. 이렇게 하면 수작업 실수를 방지할 수 있습니다.

주의할 점이 있습니다. version을 올리지 않고 차트를 수정하면 안 됩니다.

Helm 저장소는 같은 버전을 덮어쓸 수 없습니다. 작은 수정이라도 반드시 PATCH 버전을 올려야 합니다.

이것이 버전 관리의 기본 원칙입니다. 김개발 씨는 자신의 차트에 맞게 Chart.yaml을 수정했습니다.

이름을 myapp에서 user-service로 바꾸고, 설명을 추가하고, 자신을 maintainer로 등록했습니다. "이제 제대로 된 차트가 된 것 같아요!" 박시니어 씨가 고개를 끄덕였습니다.

"Chart.yaml은 작지만 중요해요. 이 파일 하나로 차트의 정체성이 결정되니까요." Chart.yaml을 정확하게 작성하면 차트의 신뢰성이 높아집니다.

버전 관리가 명확해지고, 의존성도 자동으로 해결됩니다. 여러분도 차트를 만들 때 Chart.yaml부터 꼼꼼히 작성해보세요.

실전 팁

💡 - 차트 내용이 바뀔 때마다 반드시 version을 올리세요

appVersion은 실제 배포되는 애플리케이션 버전과 일치시키세요
helm show chart [차트명] 명령으로 Chart.yaml 정보를 빠르게 확인할 수 있습니다

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

#Helm#Chart#Kubernetes#Templates#Values

Helm 차트 기초 완벽 가이드

# Helm 차트 기초 완벽 가이드 쿠버네티스 패키지 매니저 Helm의 기본 개념부터 차트 구조까지 실무에서 바로 활용할 수 있도록 친절하게 설명합니다. 초급 개발자도 쉽게 따라할 수 있는 실전 예제와 함께 Helm 차트의 핵심을 마스터해보세요. --- ## 목차 1. [Helm이란?](#helm이란?) 2. [Helm_설치](#helm-설치) 3. [Chart_구조](#chart-구조) 4. [templates_디렉토리](#templates-디렉토리) 5. [values.yaml_역할](#values.yaml-역할) 6. [Chart.yaml_메타데이터](#chart.yaml-메타데이터) --- ## 1. Helm이란? 어느 날 김개발 씨는 쿠버네티스 클러스터에 애플리케이션을 배포하려고 했습니다. 그런데 Deployment, Service, ConfigMap, Ingress 등 수십 개의 YAML 파일을 일일이 관리해야 했습니다. "이걸 하나하나 다 만들어야 하나요?" 선배 박시니어 씨가 웃으며 대답했습니다. "Helm을 쓰면 훨씬 쉬워질 거예요." **Helm**은 쿠버네티스를 위한 패키지 매니저입니다. 마치 npm이 Node.js의 패키지를 관리하듯이, Helm은 쿠버네티스 리소스를 패키지로 묶어서 관리합니다. 복잡한 애플리케이션도 한 번의 명령으로 설치하고, 업그레이드하고, 롤백할 수 있습니다. 다음 코드를 살펴봅시다. ```yaml # Helm으로 애플리케이션 설치하기 # 차트 저장소 추가 helm repo add bitnami https://charts.bitnami.com/bitnami # 저장소 업데이트 helm repo update # WordPress 설치 - 단 한 줄로! helm install my-wordpress bitnami/wordpress # 설치된 릴리스 확인 helm list # 업그레이드도 간단하게 helm upgrade my-wordpress bitnami/wordpress --set wordpressPassword=newpassword ``` 김개발 씨는 입사 2개월 차 백엔드 개발자입니다. 처음으로 쿠버네티스에 애플리케이션을 배포하는 임무를 맡았습니다. 회사 위키를 찾아보니 Deployment, Service, ConfigMap, Secret, Ingress 등 무려 15개의 YAML 파일을 작성해야 했습니다. 한 파일 한 파일 작성하다 보니 오타도 나고, 설정값도 헷갈렸습니다. "분명히 포트 번호를 8080으로 맞췄는데 왜 연결이 안 되지?" 디버깅만 2시간이 걸렸습니다. 더 큰 문제는 개발, 스테이징, 프로덕션 환경마다 설정값이 달라서 파일을 일일이 수정해야 한다는 점이었습니다. 바로 그때 선배 박시니어 씨가 지나가다 화면을 보고 말했습니다. "아직도 수작업으로 하고 있어요? Helm 쓰면 10분이면 끝나는데." 그렇다면 Helm은 정확히 무엇일까요? 쉽게 비유하자면, Helm은 마치 스마트폰의 앱스토어와 같습니다. 앱스토어에서 앱을 검색하고 설치 버튼만 누르면 복잡한 설치 과정이 자동으로 진행되는 것처럼, Helm도 애플리케이션을 검색하고 한 번의 명령으로 설치할 수 있습니다. 앱을 업데이트하거나 삭제하는 것도 버튼 하나로 가능하듯이, Helm도 동일한 방식으로 작동합니다. Helm이 없던 시절에는 어땠을까요? 개발자들은 수십 개의 YAML 파일을 직접 작성하고 관리해야 했습니다. 환경이 바뀔 때마다 파일을 복사해서 값을 수정하고, 버전 관리도 직접 해야 했습니다. 더 큰 문제는 롤백이었습니다. 배포 후 문제가 생기면 이전 버전의 모든 YAML 파일을 다시 찾아서 적용해야 했습니다. 프로젝트가 커질수록 이런 작업은 악몽이 되었습니다. 바로 이런 문제를 해결하기 위해 Helm이 등장했습니다. Helm을 사용하면 **패키징**이 가능해집니다. 관련된 모든 쿠버네티스 리소스를 하나의 차트로 묶을 수 있습니다. 또한 **템플릿화**도 얻을 수 있습니다. 변수를 사용해서 환경별로 다른 값을 주입할 수 있습니다. 무엇보다 **버전 관리와 롤백**이라는 큰 이점이 있습니다. 배포 이력을 자동으로 관리하고, 문제가 생기면 이전 버전으로 즉시 돌아갈 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 helm repo add 명령으로 차트 저장소를 추가합니다. 이것은 마치 npm에서 레지스트리를 추가하는 것과 같습니다. 다음으로 helm install 명령 하나로 WordPress와 필요한 모든 리소스가 설치됩니다. Deployment, Service, PersistentVolumeClaim 등이 자동으로 생성됩니다. 마지막으로 helm upgrade로 설정을 변경하면서 업그레이드할 수 있습니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 마이크로서비스 아키텍처를 운영하는 회사를 생각해봅시다. 사용자 서비스, 주문 서비스, 결제 서비스 등 10개의 서비스가 있고, 각 서비스마다 데이터베이스, 캐시, 메시지 큐가 필요합니다. Helm을 활용하면 각 서비스를 차트로 만들어두고, helm install 명령 하나로 전체 스택을 배포할 수 있습니다. Netflix, Spotify 같은 많은 기업에서 이런 패턴을 적극적으로 사용하고 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 Helm을 만능 도구로 생각하는 것입니다. 간단한 애플리케이션까지 무조건 Helm으로 관리하려다 오히려 복잡도가 높아질 수 있습니다. 따라서 **리소스가 5개 이상이거나, 여러 환경에 배포해야 하는 경우**에 Helm을 사용하는 것이 좋습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 눈이 반짝였습니다. "이렇게 편한 도구가 있었다니!" Helm을 제대로 이해하면 쿠버네티스 배포가 훨씬 쉬워지고, 실수도 줄어듭니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - helm repo list 명령으로 등록된 저장소를 확인할 수 있습니다 - helm search repo [키워드] 명령으로 필요한 차트를 검색할 수 있습니다 - helm history [릴리스명] 명령으로 배포 이력을 확인하고 원하는 버전으로 롤백할 수 있습니다 --- ## 2. Helm_설치 김개발 씨는 Helm이 무엇인지 알게 되었습니다. 이제 직접 사용해보고 싶었습니다. "어떻게 설치하죠?" 박시니어 씨가 터미널을 열며 말했습니다. "생각보다 간단해요. 3분이면 끝나요." **Helm 설치**는 매우 간단합니다. 리눅스, macOS, Windows 모두 지원하며, 패키지 매니저를 통해 쉽게 설치할 수 있습니다. 설치 후에는 kubectl처럼 helm 명령을 사용할 수 있습니다. 다음 코드를 살펴봅시다. ```yaml # macOS에서 Homebrew로 설치 brew install helm # Linux에서 스크립트로 설치 curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash # Windows에서 Chocolatey로 설치 choco install kubernetes-helm # 설치 확인 helm version # Kubernetes 클러스터 연결 확인 helm list ``` 김개발 씨는 맥북을 사용하고 있었습니다. "설치가 어렵지 않을까?" 걱정했지만, 박시니어 씨가 보여준 방법은 놀라울 정도로 간단했습니다. 터미널을 열고 단 한 줄의 명령어를 입력했습니다. brew install helm. 커피 한 모금 마시는 사이에 설치가 완료되었습니다. "이게 끝이에요?" 김개발 씨가 놀라서 물었습니다. Helm 설치는 정말 간단합니다. 왜 이렇게 쉬울까요? Helm은 **단일 바이너리 파일**로 배포됩니다. 마치 kubectl처럼 하나의 실행 파일만 있으면 모든 기능을 사용할 수 있습니다. 복잡한 의존성도 없고, 별도의 데이터베이스나 서버도 필요 없습니다. 그저 실행 파일 하나를 PATH에 추가하면 끝입니다. 운영체제별로 설치 방법이 조금씩 다릅니다만, 모두 쉽습니다. macOS 사용자라면 Homebrew를 사용하는 것이 가장 편합니다. Homebrew는 macOS에서 가장 인기 있는 패키지 매니저입니다. brew install helm 한 줄이면 최신 버전의 Helm이 설치되고, 업데이트도 brew upgrade helm으로 간단히 할 수 있습니다. Linux 사용자는 공식 설치 스크립트를 사용할 수 있습니다. curl 명령으로 스크립트를 다운로드하고 bash로 실행하면, 자동으로 시스템에 맞는 바이너리를 다운로드하고 설치합니다. Ubuntu, CentOS, Fedora 등 대부분의 배포판에서 동일하게 작동합니다. Windows 사용자는 Chocolatey나 Scoop 같은 패키지 매니저를 사용할 수 있습니다. PowerShell을 관리자 권한으로 실행하고 choco install kubernetes-helm 명령을 입력하면 됩니다. 또는 GitHub 릴리스 페이지에서 zip 파일을 직접 다운로드할 수도 있습니다. 설치가 완료되었다면 반드시 확인해야 합니다. helm version 명령을 실행해보세요. 버전 정보가 출력되면 설치가 성공한 것입니다. 현재 최신 버전은 Helm 3입니다. Helm 2와는 많은 부분이 달라졌는데, 가장 큰 차이는 **Tiller가 제거되었다**는 점입니다. Helm 2에서는 클러스터 안에 Tiller라는 서버 컴포넌트가 필요했지만, Helm 3는 클라이언트만으로 모든 작업이 가능합니다. 다음으로 Kubernetes 클러스터와의 연결을 확인해야 합니다. helm list 명령을 실행해보세요. 에러가 나지 않고 빈 목록이나 기존 릴리스 목록이 출력되면 정상입니다. Helm은 kubectl과 동일한 kubeconfig 파일을 사용합니다. 즉, kubectl이 정상적으로 작동한다면 Helm도 자동으로 동일한 클러스터에 연결됩니다. 실무에서 자주 겪는 문제가 하나 있습니다. 회사에서 여러 개의 Kubernetes 클러스터를 사용하는 경우, 어떤 클러스터에 연결되어 있는지 헷갈릴 수 있습니다. kubectl config current-context 명령으로 현재 컨텍스트를 확인하고, kubectl config use-context [컨텍스트명] 명령으로 전환할 수 있습니다. Helm은 자동으로 kubectl의 현재 컨텍스트를 따라갑니다. 김개발 씨는 helm version을 실행해보았습니다. "version.BuildInfo{Version:"v3.14.0"...}" 버전 정보가 화면에 출력되었습니다. "성공했어요!" 이제 본격적으로 Helm을 사용할 준비가 완료되었습니다. Helm 설치는 첫 번째 단계일 뿐입니다. 하지만 이 간단한 설치 과정 덕분에 누구나 쉽게 Helm을 시작할 수 있습니다. 여러분도 지금 바로 터미널을 열고 설치해보세요. **실전 팁** 💡 - Helm 3를 사용하세요. Helm 2는 2020년에 지원이 종료되었습니다 - helm completion bash 명령으로 자동완성을 활성화하면 더욱 편리합니다 - helm plugin list 명령으로 유용한 플러그인을 추가할 수 있습니다 --- ## 3. Chart_구조 Helm을 설치한 김개발 씨는 이제 차트를 만들어보고 싶었습니다. "차트는 어떻게 생겼나요?" 박시니어 씨가 helm create 명령으로 샘플 차트를 만들어 보여주었습니다. 폴더를 열어보니 여러 파일과 디렉토리가 보였습니다. **Helm 차트**는 특정한 디렉토리 구조를 가진 파일들의 모음입니다. Chart.yaml, values.yaml, templates 디렉토리가 핵심이며, 각각 메타데이터, 설정값, 쿠버네티스 리소스 템플릿을 담당합니다. 이 구조를 이해하면 차트를 자유롭게 만들고 수정할 수 있습니다. 다음 코드를 살펴봅시다. ```yaml # 새로운 차트 생성 helm create myapp # 생성된 차트 구조 확인 tree myapp/ # 출력 결과: # myapp/ # ├── Chart.yaml # 차트 메타데이터 # ├── values.yaml # 기본 설정값 # ├── charts/ # 의존성 차트 # ├── templates/ # 쿠버네티스 리소스 템플릿 # │ ├── deployment.yaml # │ ├── service.yaml # │ ├── ingress.yaml # │ └── _helpers.tpl # 템플릿 헬퍼 함수 # └── .helmignore # 패키징 시 제외할 파일 ``` 김개발 씨는 helm create myapp 명령을 입력했습니다. 순식간에 myapp이라는 디렉토리가 생성되고, 그 안에 여러 파일이 만들어졌습니다. VS Code로 폴더를 열어보니 낯선 파일 이름들이 보였습니다. "이게 다 뭐예요?" 김개발 씨가 물었습니다. 박시니어 씨가 하나씩 설명해주었습니다. "각 파일이 다 역할이 있어요. 마치 집을 짓는 것처럼 설계도, 자재 목록, 시공 지침이 따로 있는 거죠." Helm 차트의 구조는 매우 체계적입니다. 가장 먼저 눈에 띄는 것은 **Chart.yaml** 파일입니다. 이 파일은 마치 책의 표지와 같습니다. 차트의 이름, 버전, 설명, 작성자 정보가 들어있습니다. 누군가 이 차트를 검색하거나 설치하려 할 때 가장 먼저 보는 정보입니다. 두 번째로 중요한 것은 **values.yaml** 파일입니다. 이 파일은 마치 설정 파일과 같습니다. 컨테이너 이미지 이름, 포트 번호, 리소스 제한, 환경변수 등 모든 설정값이 여기에 모여있습니다. 사용자가 차트를 설치할 때 이 값들을 원하는 대로 변경할 수 있습니다. 예를 들어 개발 환경에서는 레플리카를 1개로, 프로덕션에서는 3개로 설정하는 식입니다. 세 번째 핵심은 **templates 디렉토리**입니다. 이 디렉토리가 차트의 심장부입니다. 실제 쿠버네티스 리소스 파일들이 템플릿 형태로 들어있습니다. deployment.yaml은 Deployment를 만들고, service.yaml은 Service를 만들고, ingress.yaml은 Ingress를 만듭니다. 하지만 일반 YAML 파일과 다른 점이 있습니다. 바로 **변수**를 사용한다는 것입니다. 템플릿 파일을 열어보면 이상한 문법이 보입니다. 중괄호 두 개로 감싸진 표현식들입니다. 예를 들어 {{ .Values.image.repository }}처럼 생긴 것들이 있습니다. 이것이 바로 **Go 템플릿 문법**입니다. Helm이 차트를 설치할 때 이런 표현식을 values.yaml의 실제 값으로 치환합니다. 마치 Word의 메일 머지 기능처럼 말입니다. charts 디렉토리는 의존성을 관리합니다. 만약 여러분의 애플리케이션이 PostgreSQL 데이터베이스가 필요하다면 어떻게 할까요? PostgreSQL 차트를 의존성으로 추가하면 됩니다. Chart.yaml에 의존성을 선언하고, helm dependency update 명령을 실행하면 필요한 차트가 charts 디렉토리에 다운로드됩니다. 그러면 helm install 한 번으로 애플리케이션과 데이터베이스가 함께 설치됩니다. _helpers.tpl 파일은 특별합니다. 이 파일은 템플릿에서 반복적으로 사용되는 코드를 함수처럼 정의해두는 곳입니다. 예를 들어 레이블을 만드는 로직이 여러 리소스에서 반복된다면, _helpers.tpl에 정의해두고 재사용할 수 있습니다. 코드 중복을 줄이고 유지보수를 쉽게 만듭니다. .helmignore 파일도 유용합니다. 이것은 .gitignore와 비슷합니다. 차트를 패키징할 때 포함하지 않을 파일이나 디렉토리를 지정합니다. 개발 중에 만든 테스트 파일이나 임시 파일을 제외하고 싶을 때 사용합니다. 실무에서는 이 구조를 어떻게 활용할까요? 예를 들어 마이크로서비스를 배포한다고 해봅시다. 먼저 helm create로 기본 구조를 만듭니다. 그다음 templates 디렉토리에 필요한 리소스를 추가합니다. Deployment만 있다면 Service를 추가하고, 외부 접근이 필요하면 Ingress를 추가합니다. values.yaml에는 환경별로 다를 수 있는 모든 설정을 빼냅니다. 이렇게 만든 차트 하나로 개발, 스테이징, 프로덕션 모든 환경에 배포할 수 있습니다. 주의할 점이 있습니다. 초보자들은 templates 디렉토리에 너무 많은 파일을 만들려 합니다. 처음에는 꼭 필요한 리소스만 만드세요. Deployment와 Service만 있어도 충분히 작동합니다. Ingress, ConfigMap, Secret 등은 실제로 필요할 때 추가하면 됩니다. 김개발 씨는 각 파일을 하나씩 열어보며 구조를 이해했습니다. "아, 이렇게 체계적으로 되어있구나!" 처음에는 복잡해 보였지만, 각 파일의 역할을 알고 나니 오히려 명확하고 깔끔하다는 생각이 들었습니다. 차트 구조를 이해하는 것은 Helm 마스터로 가는 필수 과정입니다. 이 구조만 알면 어떤 차트든 읽고 수정할 수 있습니다. 여러분도 helm create로 직접 차트를 만들어보며 구조를 익혀보세요. **실전 팁** 💡 - helm create로 생성된 기본 차트를 템플릿으로 활용하세요 - 필요 없는 파일은 과감히 삭제해도 됩니다 (예: ingress.yaml이 필요 없다면 삭제) - helm lint 명령으로 차트 구조가 올바른지 검증할 수 있습니다 --- ## 4. templates_디렉토리 김개발 씨는 templates 디렉토리를 열어보았습니다. deployment.yaml 파일에는 일반 YAML과 다른 이상한 문법이 가득했습니다. "이 중괄호들은 뭔가요?" 박시니어 씨가 미소를 지으며 대답했습니다. "바로 Helm의 핵심이에요. 템플릿 엔진이죠." **templates 디렉토리**는 쿠버네티스 리소스 파일들을 템플릿 형태로 저장하는 곳입니다. Go 템플릿 문법을 사용해서 변수, 조건문, 반복문을 활용할 수 있습니다. 이를 통해 하나의 템플릿으로 다양한 환경에 맞는 리소스를 생성할 수 있습니다. 다음 코드를 살펴봅시다. ```yaml # templates/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: {{ .Release.Name }}-deployment labels: app: {{ .Chart.Name }} spec: replicas: {{ .Values.replicaCount }} selector: matchLabels: app: {{ .Chart.Name }} template: metadata: labels: app: {{ .Chart.Name }} spec: containers: - name: {{ .Chart.Name }} image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" ports: - containerPort: {{ .Values.service.port }} ``` 김개발 씨가 처음 본 템플릿 파일은 충격적이었습니다. 평소에 작성하던 깔끔한 YAML 파일과 달리 {{ }}로 감싸진 표현식들이 곳곳에 박혀있었습니다. "이게 정말 작동하는 건가요?" 박시니어 씨가 설명해주었습니다. "Helm이 설치할 때 이 템플릿을 읽고, 중괄호 안의 표현식을 실제 값으로 바꿔줍니다. 그러면 일반 YAML이 되는 거죠." templates 디렉토리의 핵심은 **동적 생성**입니다. 마치 프린터가 문서를 찍어내듯이, Helm은 템플릿을 읽고 실제 쿠버네티스 리소스를 생성합니다. 이 과정에서 변수를 주입하고, 조건에 따라 다른 내용을 만들고, 반복문으로 여러 개를 생성할 수도 있습니다. 이 모든 것이 templates 디렉토리에서 일어납니다. 가장 기본적인 것은 **변수 치환**입니다. {{ .Values.replicaCount }}라는 표현식을 봅시다. 이것은 values.yaml 파일의 replicaCount 값을 가져옵니다. 만약 values.yaml에 replicaCount: 3이라고 되어있다면, 이 표현식은 3으로 치환됩니다. 이렇게 하면 환경마다 다른 값을 쉽게 적용할 수 있습니다. 변수는 세 가지 주요 객체에서 가져올 수 있습니다. 첫째는 **.Values**입니다. values.yaml 파일의 모든 값에 접근할 수 있습니다. .Values.image.repository처럼 점으로 연결해서 중첩된 값도 가져올 수 있습니다. 둘째는 **.Chart**입니다. Chart.yaml에 정의된 메타데이터에 접근합니다. .Chart.Name이나 .Chart.Version 같은 값을 사용할 수 있습니다. 셋째는 **.Release**입니다. 현재 릴리스에 대한 정보를 담고 있습니다. .Release.Name은 helm install 할 때 지정한 릴리스 이름이고, .Release.Namespace는 설치될 네임스페이스입니다. 조건문도 사용할 수 있습니다. 예를 들어 Ingress를 선택적으로 만들고 싶다면 이렇게 작성합니다. {{ if .Values.ingress.enabled }} 블록을 만들고, values.yaml의 ingress.enabled 값이 true일 때만 Ingress 리소스를 생성하도록 할 수 있습니다. 이렇게 하면 개발 환경에서는 Ingress를 끄고, 프로덕션에서만 켤 수 있습니다. 반복문은 더 강력합니다. ConfigMap에 여러 개의 환경변수를 넣고 싶다면 어떻게 할까요? values.yaml에 env라는 배열을 만들고, 템플릿에서 {{ range .Values.env }} 반복문을 사용하면 됩니다. 배열의 각 항목이 자동으로 환경변수로 변환됩니다. 파이프라인 기능도 유용합니다. {{ .Values.name | upper }}처럼 파이프 기호를 사용하면 값을 함수에 전달할 수 있습니다. upper는 문자열을 대문자로 바꾸는 함수입니다. quote 함수는 따옴표로 감싸주고, default 함수는 기본값을 설정합니다. 여러 함수를 체인처럼 연결할 수도 있습니다. 실제 업무에서는 이런 기능을 어떻게 활용할까요? 예를 들어 회사에서 개발, 스테이징, 프로덕션 환경을 운영한다고 합시다. 개발에서는 레플리카 1개, CPU 제한 없음으로 실행하고, 프로덕션에서는 레플리카 3개, CPU 제한 1000m로 실행하고 싶습니다. 템플릿은 하나만 만들고, values.yaml 파일만 환경별로 다르게 준비하면 됩니다. helm install -f values-dev.yaml 또는 helm install -f values-prod.yaml처럼 사용합니다. 주의해야 할 점이 있습니다. 템플릿에 너무 복잡한 로직을 넣지 마세요. 조건문이 3단계 이상 중첩되거나, 반복문 안에 또 조건문이 들어가면 읽기 어려워집니다. 복잡한 로직은 _helpers.tpl에 함수로 분리하는 것이 좋습니다. 또 하나 중요한 것은 **들여쓰기**입니다. YAML은 들여쓰기에 민감합니다. 템플릿에서 값을 주입할 때 들여쓰기가 맞지 않으면 에러가 발생합니다. indent 함수를 사용해서 올바른 위치에 들여쓰기를 추가하세요. 예를 들어 {{ .Values.config | indent 4 }}처럼 사용합니다. 김개발 씨는 직접 템플릿을 수정해보았습니다. replicaCount를 2로 바꾸고, helm install --dry-run --debug 명령으로 결과를 확인했습니다. 화면에 실제 생성될 YAML이 출력되었습니다. "와, 정말 바뀌네요!" templates 디렉토리를 마스터하면 Helm의 진정한 힘을 느낄 수 있습니다. 하나의 템플릿으로 무한한 변형을 만들어낼 수 있습니다. 여러분도 직접 템플릿을 작성하고 실험해보세요. **실전 팁** 💡 - helm template 명령으로 렌더링된 결과를 미리 확인할 수 있습니다 - helm install --dry-run --debug 명령으로 실제 설치 없이 테스트할 수 있습니다 - toYaml 함수를 사용하면 values.yaml의 객체를 그대로 YAML로 변환할 수 있습니다 --- ## 5. values.yaml_역할 김개발 씨는 템플릿을 이해했지만, 궁금한 점이 생겼습니다. "템플릿에서 사용하는 값들은 다 어디서 오는 거죠?" 박시니어 씨가 values.yaml 파일을 열어 보여주었습니다. "바로 여기요. Helm 차트의 설정 파일이에요." **values.yaml**은 차트의 모든 설정값을 중앙에서 관리하는 파일입니다. 템플릿에서 사용할 변수의 기본값을 정의하며, 사용자는 설치 시 이 값들을 원하는 대로 변경할 수 있습니다. 이를 통해 동일한 차트로 다양한 환경을 구성할 수 있습니다. 다음 코드를 살펴봅시다. ```yaml # values.yaml replicaCount: 2 image: repository: nginx tag: "1.21.0" pullPolicy: IfNotPresent service: type: ClusterIP port: 80 resources: limits: cpu: 500m memory: 512Mi requests: cpu: 250m memory: 256Mi ingress: enabled: false className: "nginx" hosts: - host: myapp.example.com paths: - path: / pathType: Prefix ``` 김개발 씨가 values.yaml 파일을 열어보니 깔끔하게 정리된 YAML 파일이었습니다. 이번에는 중괄호 같은 이상한 문법이 없었습니다. 그냥 일반적인 설정 파일처럼 보였습니다. "이건 이해하기 쉬운데요?" 박시니어 씨가 고개를 끄덕였습니다. "맞아요. values.yaml은 개발자가 가장 자주 수정하는 파일이에요. 그래서 최대한 간단하고 명확하게 만들어야 해요." values.yaml의 핵심 역할은 **설정의 중앙화**입니다. 쿠버네티스에 애플리케이션을 배포할 때 설정해야 할 것들이 많습니다. 이미지 이름, 태그, 포트 번호, 리소스 제한, 환경변수, 볼륨 설정 등등. 이런 값들이 deployment.yaml, service.yaml, configmap.yaml 여기저기 흩어져 있으면 관리하기 어렵습니다. values.yaml은 이 모든 설정을 한곳에 모아둡니다. 구조는 매우 직관적입니다. 계층적으로 구성되어 있습니다. image라는 키 아래에 repository, tag, pullPolicy가 있습니다. service 아래에는 type과 port가 있습니다. 이렇게 관련된 설정을 그룹으로 묶으면 읽기 쉽고, 찾기도 쉽습니다. 실제로 어떻게 사용될까요? 템플릿에서 {{ .Values.image.repository }}라고 작성하면, values.yaml의 image.repository 값인 nginx가 주입됩니다. {{ .Values.service.port }}는 80이 됩니다. 이런 식으로 템플릿과 values.yaml이 유기적으로 연결됩니다. 가장 큰 장점은 **오버라이드**입니다. values.yaml은 기본값만 정의합니다. 사용자는 설치할 때 이 값들을 자유롭게 변경할 수 있습니다. helm install myapp ./myapp --set replicaCount=5 명령을 실행하면, 기본값 2 대신 5가 사용됩니다. 여러 값을 바꾸려면 --set을 여러 번 사용하거나, 별도의 values 파일을 만들어서 -f 옵션으로 전달할 수 있습니다. 환경별 values 파일을 만드는 것이 일반적입니다. 기본 values.yaml은 개발 환경용으로 두고, values-prod.yaml 파일을 별도로 만듭니다. 프로덕션용 파일에는 레플리카를 5로, 리소스 제한을 더 높게 설정합니다. 배포할 때 helm install myapp ./myapp -f values-prod.yaml처럼 사용하면 됩니다. 필수 값과 선택 값을 구분하는 것도 중요합니다. ingress.enabled: false처럼 기본값을 false로 두면, 사용자가 명시적으로 true로 바꾸지 않는 한 Ingress가 생성되지 않습니다. 이렇게 선택적인 기능은 기본적으로 비활성화해두는 것이 좋습니다. 반면 image.repository처럼 반드시 필요한 값은 합리적인 기본값을 제공해야 합니다. 주석도 적극 활용하세요. values.yaml에 주석을 달아서 각 설정이 무엇을 의미하는지 설명하세요. 특히 값의 범위나 형식을 명시하면 좋습니다. 예를 들어 "service.type: ClusterIP, NodePort, LoadBalancer 중 하나"라고 주석을 달아두면 사용자가 실수하지 않습니다. 실무에서 자주 사용하는 패턴이 있습니다. secrets 같은 민감한 정보는 values.yaml에 직접 넣지 않습니다. 대신 existingSecret 같은 키를 만들어서 기존에 생성된 Secret의 이름을 참조하도록 합니다. 또는 Helm Secrets 플러그인을 사용해서 암호화된 values 파일을 관리하기도 합니다. 값의 검증도 고려해야 합니다. Helm 3부터는 values.schema.json 파일을 만들어서 values.yaml의 형식을 검증할 수 있습니다. JSON Schema 형식으로 "replicaCount는 1 이상의 정수여야 함" 같은 규칙을 정의하면, helm install 할 때 자동으로 검증됩니다. 김개발 씨는 자신의 애플리케이션에 맞게 values.yaml을 수정해보았습니다. 이미지를 회사 레지스트리로 바꾸고, 포트를 8080으로 변경했습니다. 그리고 helm install --dry-run으로 확인했습니다. "제 설정이 정확히 반영되네요!" values.yaml을 잘 설계하면 차트의 재사용성이 크게 높아집니다. 한 번 만든 차트를 모든 환경에서 사용할 수 있습니다. 여러분도 명확하고 유연한 values.yaml을 만들어보세요. **실전 팁** 💡 - values.yaml은 알파벳 순서로 정렬하면 찾기 쉽습니다 - 중첩은 3단계를 넘지 않도록 하세요 (너무 깊으면 복잡해집니다) - helm get values [릴리스명] 명령으로 현재 사용 중인 값을 확인할 수 있습니다 --- ## 6. Chart.yaml_메타데이터 김개발 씨는 차트의 핵심 구조를 모두 이해했습니다. 마지막으로 궁금한 것이 하나 남았습니다. "Chart.yaml은 뭐하는 파일인가요?" 박시니어 씨가 파일을 열어 보여주었습니다. "차트의 신분증이에요. 이름, 버전, 작성자 정보가 들어있죠." **Chart.yaml**은 차트의 메타데이터를 정의하는 필수 파일입니다. 차트의 이름, 버전, 설명, 작성자, 의존성 등을 명시합니다. 이 정보는 차트 검색, 버전 관리, 의존성 해결에 사용됩니다. 다음 코드를 살펴봅시다. ```yaml # Chart.yaml apiVersion: v2 name: myapp description: A Helm chart for my awesome application type: application version: 1.0.0 appVersion: "2.1.0" keywords: - web - backend - api maintainers: - name: Kim Developer email: kim@example.com dependencies: - name: postgresql version: "12.1.0" repository: "https://charts.bitnami.com/bitnami" condition: postgresql.enabled ``` 김개발 씨가 Chart.yaml을 열어보니 생각보다 간단했습니다. 몇 개의 필드만 있었습니다. "이게 전부예요?" 박시니어 씨가 웃으며 답했습니다. "간단해 보이지만, 아주 중요한 정보들이에요." Chart.yaml의 첫 번째 역할은 **차트 식별**입니다. name 필드는 차트의 고유한 이름입니다. 소문자와 하이픈만 사용할 수 있습니다. 이 이름으로 차트를 검색하고 설치합니다. 마치 npm 패키지 이름처럼 전 세계에서 유일해야 하는 것은 아니지만, 조직 내에서는 중복되지 않아야 합니다. version 필드는 차트의 버전입니다. 시맨틱 버저닝을 따릅니다. 1.0.0 형식으로 작성하며, MAJOR.MINOR.PATCH 규칙을 사용합니다. 차트 내용이 바뀔 때마다 버전을 올려야 합니다. 템플릿이 바뀌거나, values.yaml에 새 설정이 추가되면 버전을 업데이트합니다. Helm 저장소에 차트를 게시할 때 이 버전으로 구분됩니다. appVersion은 조금 다릅니다. 이것은 차트가 배포하는 애플리케이션의 버전입니다. 예를 들어 nginx 차트의 version이 2.0.0이고 appVersion이 1.21.0이라면, 차트 자체는 2.0.0 버전이지만 실제 배포되는 nginx는 1.21.0 버전이라는 의미입니다. 사용자가 "어떤 버전의 애플리케이션이 설치되나요?"라고 물을 때 참고하는 정보입니다. apiVersion은 Helm 버전을 나타냅니다. Helm 3를 사용한다면 v2라고 적습니다. Helm 2에서는 v1이었습니다. 이 필드를 보고 Helm이 차트 형식을 올바르게 해석합니다. type 필드는 차트의 종류를 구분합니다. application은 일반적인 애플리케이션 차트입니다. library는 다른 차트에서 재사용할 수 있는 헬퍼 함수나 템플릿을 제공하는 차트입니다. 대부분의 경우 application을 사용합니다. description은 차트에 대한 간단한 설명입니다. 한두 문장으로 이 차트가 무엇을 배포하는지 설명합니다. 사용자가 helm search로 차트를 찾을 때 이 설명을 보고 원하는 차트인지 판단합니다. keywords는 검색을 돕습니다. 차트와 관련된 키워드를 배열로 나열합니다. 예를 들어 웹 서버 차트라면 web, http, server 같은 키워드를 추가합니다. Helm 저장소에서 검색할 때 이 키워드가 사용됩니다. maintainers는 관리자 정보입니다. 차트를 유지보수하는 사람의 이름과 이메일을 적습니다. 문제가 생겼을 때 누구에게 문의해야 하는지 알 수 있습니다. 가장 강력한 기능은 **dependencies**입니다. 차트가 다른 차트에 의존할 수 있습니다. 예를 들어 웹 애플리케이션 차트가 PostgreSQL 데이터베이스를 필요로 한다면, dependencies에 postgresql 차트를 명시합니다. helm dependency update 명령을 실행하면 필요한 차트가 자동으로 다운로드됩니다. 그리고 helm install 한 번으로 애플리케이션과 데이터베이스가 함께 설치됩니다. condition 필드를 사용하면 의존성을 선택적으로 만들 수 있습니다. condition: postgresql.enabled라고 설정하면, values.yaml의 postgresql.enabled 값이 true일 때만 PostgreSQL이 설치됩니다. 개발 환경에서는 외부 데이터베이스를 사용하고, 프로덕션에서만 차트로 설치하고 싶을 때 유용합니다. 실무에서는 Chart.yaml을 어떻게 관리할까요? CI/CD 파이프라인에서 자동으로 버전을 올리는 경우가 많습니다. 코드가 main 브랜치에 머지되면, 스크립트가 Chart.yaml의 version을 자동으로 증가시키고, 차트를 패키징해서 저장소에 업로드합니다. 이렇게 하면 수작업 실수를 방지할 수 있습니다. 주의할 점이 있습니다. version을 올리지 않고 차트를 수정하면 안 됩니다. Helm 저장소는 같은 버전을 덮어쓸 수 없습니다. 작은 수정이라도 반드시 PATCH 버전을 올려야 합니다. 이것이 버전 관리의 기본 원칙입니다. 김개발 씨는 자신의 차트에 맞게 Chart.yaml을 수정했습니다. 이름을 myapp에서 user-service로 바꾸고, 설명을 추가하고, 자신을 maintainer로 등록했습니다. "이제 제대로 된 차트가 된 것 같아요!" 박시니어 씨가 고개를 끄덕였습니다. "Chart.yaml은 작지만 중요해요. 이 파일 하나로 차트의 정체성이 결정되니까요." Chart.yaml을 정확하게 작성하면 차트의 신뢰성이 높아집니다. 버전 관리가 명확해지고, 의존성도 자동으로 해결됩니다. 여러분도 차트를 만들 때 Chart.yaml부터 꼼꼼히 작성해보세요. **실전 팁** 💡 - 차트 내용이 바뀔 때마다 반드시 version을 올리세요 - appVersion은 실제 배포되는 애플리케이션 버전과 일치시키세요 - helm show chart [차트명] 명령으로 Chart.yaml 정보를 빠르게 확인할 수 있습니다 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: Kubernetes

언어: YAML

태그: Helm, Chart, Kubernetes, Templates, Values

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

Helm 차트 기초 완벽 가이드

목차

1. Helm이란?

2. Helm 설치

3. Chart 구조

4. templates 디렉토리

5. values.yaml 역할

6. Chart.yaml 메타데이터

댓글 (0)

함께 보면 좋은 카드 뉴스

Istio 보안 완벽 가이드

Istio 트래픽 관리 완벽 가이드

Istio 설치와 구성 완벽 가이드

서비스 메시 완벽 가이드

Helm 마이크로서비스 패키징 완벽 가이드