Fredric News

쿠버네티스 Helm 3 실무 치트시트: 릴리즈 관리와 롤백

💡 핵심 요약 (Executive Summary)

본 가이드는 쿠버네티스 Helm 패키지 매니저 핵심 가이드 및 실전 아키텍처의 핵심 개념, 실전 구성 명령어 및 아키텍처 베스트 프랙티스를 다룹니다. 클라우드 네이티브 및 인프라 엔지니어링 실무에 즉시 활용 가능하도록 체계적으로 정리했습니다.

📑 Table of Contents

Installation

bash
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Exec

completion
html
echo "source <(helm completion bash)" >> ~/.bashrc
source ~/.bashrc
search
bash
# artifacthub.io에서 차트 검색
helm search hub {{ 검색어 }}

# repository명으로 차트 검색
helm search repo {{ 검색어 }}

repository: 차트 저장소 like Docker HUB
artifacthub.io:

  • helm search hub – 헬름 허브 또는 모노큘러 인스턴스에서 차트 검색
  • helm search repo – 차트에서 키워드에 대한 저장소 검색

bash
# 리포지토리 추가
helm repo add [NAME] [URL] [flags]
# helm repo add bitnami https://charts.bitnami.com/bitnami

# values show
helm show values $repo/$chart
helm show readme $repo/$chart
helm show chart $repo/$chart
helm show crds $repo/$chart
helm template .
helm show values kiali/kiali-server --version=v1.82.0 > values.origin

# 인스톨
helm install my-release bitnami/<chart>

# values.yaml 경로에서
helm install ${appname} . -n ${namespace}

# 업그레이드
# values.yaml 경로에서
helm upgrade ${appname} . -n ${namespace}

# 패키지 파일 생성
helm package .

# 패키지 파일 helm repository에 push
helm push $package.tgz oci://$myrepository/$project
repo
bash
#index.yaml 현재 경로 기준으로 생성 (helm repository index)
helm repo index .

#helm repository 등록
helm repo add $repository $repositoryURL
list


helm list attributes

sql
helm list --help


This command lists all of the releases for a specified namespace (uses current namespace context if namespace not specified).

By default, it lists only releases that are deployed or failed. Flags like
'--uninstalled' and '--all' will alter this behavior. Such flags can be combined:
'--uninstalled --failed'.

By default, items are sorted alphabetically. Use the '-d' flag to sort by
release date.

If the --filter flag is provided, it will be treated as a filter. Filters are
regular expressions (Perl compatible) that are applied to the list of releases.
Only items that match the filter will be returned.

    $ helm list --filter 'ara[a-z]+'
    NAME                UPDATED                                  CHART
    maudlin-arachnid    2020-06-18 14:17:46.125134977 +0000 UTC  alpine-0.1.0

If no results are found, 'helm list' will exit 0, but with no output (or in
the case of no '-q' flag, only headers).

By default, up to 256 items may be returned. To limit this, use the '--max' flag.
Setting '--max' to 0 will not return all results. Rather, it will return the
server's default, which may be much higher than 256. Pairing the '--max'
flag with the '--offset' flag allows you to page through results.

Usage:
  helm list [flags]

Aliases:
  list, ls

Flags:
  -a, --all                  show all releases without any filter applied
  -A, --all-namespaces       list releases across all namespaces
  -d, --date                 sort by release date
      --deployed             show deployed releases. If no other is specified, this will be automatically enabled
      --failed               show failed releases
  -f, --filter string        a regular expression (Perl compatible). Any releases that match the expression will be included in the results
  -h, --help                 help for list
  -m, --max int              maximum number of releases to fetch (default 256)
      --offset int           next release index in the list, used to offset from start value
  -o, --output format        prints the output in the specified format. Allowed values: table, json, yaml (default table)
      --pending              show pending releases
  -r, --reverse              reverse the sort order
  -l, --selector string      Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2). Works only for secret(default) and configmap storage backends.
  -q, --short                output short (quiet) listing format
      --superseded           show superseded releases
      --time-format string   format time using golang time formatter. Example: --time-format "2006-01-02 15:04:05Z0700"
      --uninstalled          show uninstalled releases (if 'helm uninstall --keep-history' was used)
      --uninstalling         show releases that are currently being uninstalled

Global Flags:
      --debug                       enable verbose output
      --kube-apiserver string       the address and the port for the Kubernetes API server
      --kube-as-group stringArray   group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --kube-as-user string         username to impersonate for the operation
      --kube-ca-file string         the certificate authority file for the Kubernetes API server connection
      --kube-context string         name of the kubeconfig context to use
      --kube-token string           bearer token used for authentication
      --kubeconfig string           path to the kubeconfig file
  -n, --namespace string            namespace scope for this request
      --registry-config string      path to the registry config file (default "/root/.config/helm/registry/config.json")
      --repository-cache string     path to the file containing cached repository indexes (default "/root/.cache/helm/repository")
      --repository-config string    path to the file containing repository names and URLs (default "/root/.config/helm/repositories.yaml")
pull
bash
# dir로 다운로드
helm pull ${repo}/${appname} --untar --version=${chart-version}
install
bash
# values.yaml 경로 내에서
helm install -n ${namespace} ${appname} .
helm install -n ${namespace} ${appname} . --create-namespace
# 리포에서 가져오기
helm install -n ${namespace} ${appname} ${repo}/${appname} --set ${flags_for_overwrite}

# map value set
#cat values.yaml | yq -o props
--set foo.bar={ foo: bar }
update
bash
# values.yaml 경로 내에서
helm update -n ${namespace} ${appname} .
uninstall
bash
helm uninstall -n ${namespace} ${appname}
status
bash
# helm release정보, 설치 Description 확인
helm status -n ${namespace} ${appname}
get
bash
# deploy된 모든 template metadata 확인 ( k8s-manifests )
helm get all -n ${namespace} ${appname}

OCI-based registry

사실 하버에서 제공해주는 helm registry는 OCI 기반 레지스트리이다. 이 레지스트리는 일반적인 helm chart 레지스트리와는 조금 다른 성격을 띤다. 일단 Helm 3.8 버전부터 OCI 기반 레지스트리 지원을 정식으로 하며, 3.8 이전 버전에서는 helm에서 OCI가 다르게 동작했다고 한다. 그래서 정상적으로 OCI 기반 레지스트리를 사용하려면 helm 버전이 3.8 이상인지 확인해야 한다.

bash
helm registry login $registry
helm registry logout $registry
helm push $package.tgz oci://$registry
helm pull oci://$registry
helm show $target oci://$registry
helm template $target oci://$registry
helm install $releasename -n $ns oci://$registry
helm upgrade $releasename -n $ns oci://$registry

Create Helm Chart

bash
helm create $chartname
Values 작성 요령
차트 구조 변경시에 필요한 값을 찾는 요령
bash
# 기존 values.yaml을 백업하고, 빈 values.yaml을 생성한다
mv values.yaml values-backup.yaml
> values.yaml

# 템플릿을 테스트해본다.
helm template mychart .
Error: template: cmp-common-si/templates/spring-cloud-vault.yaml:4:18: executing "cmp-common-si/templates/spring-cloud-vault.yaml" at <.Values.global.config.namePrefix>: nil pointer evaluating interface {}.config

Use --debug flag to render out invalid YAML

# yq를 이용하여 백업에서 가져옴
cat values-backup.yaml | yq -oprops | grep 'global.config.namePrefix' | yq -pprops >> values.yaml
bjw-s-labs Guideline
Reference & Guidelines (NOTE)

현재 쿠버네티스 커뮤니티(특히 GitOps 기반 인프라 구축 시)에서 코드 반복을 없애기 위해 가장 널리 쓰이는 리포지토리입니다.

  • 개요: 일반적인 웹앱, API 서버, 백엔드 등은 Deployment, Service, Ingress, PVC 구조가 90% 이상 동일합니다. 이 리포지토리는 “차트를 매번 새로 만들지 말고, 하나의 만능 차트에 values.yaml만 다르게 주입해서 쓰자”라는 철학으로 만들어졌습니다.
  • 작동 방식: 사용자는 Helm Chart 템플릿(YAML 파일들)을 전혀 작성하지 않습니다. 이 app-template 리포지토리를 가져온 뒤, values.yaml에 컨테이너 이미지, 포트, 인gress, 볼륨 구조만 선언하면 쿠버네티스 리소스가 자동으로 렌더링됩니다.
  • 리포지토리 주소: https://bjw-s-labs.github.io/helm-charts
1. 신규 차트 디렉터리 구조 생성

가장 먼저 신규 차트를 위한 폴더를 생성합니다. (예: my-custom-app)

bash
helm create my-custom-app
cd my-custom-app
rm -rf templates/*
Reference & Guidelines (NOTE)

주의: 일반적인 Helm 구조와 달리 templates 폴더를 만들거나 그 안에 Deployment, Service 등의 YAML을 직접 작성하지 않습니다.

2. Chart.yaml 작성 (의존성 정의)

Chart.yaml에서 가장 중요한 점은 bjw-s-labs 리포지토리를 dependencies로 등록하고, 해당 차트의 기능을 내 차트로 완전히 가져오는 것입니다.

yaml
apiVersion: v2
name: my-custom-app
description: # input this
type: application
version: 1.0.0
appVersion: "1.0.0"

dependencies:
  - name: common
    version: 5.0.1
    repository: https://bjw-s-labs.github.io/helm-charts/

or Local Repository

yaml
dependencies:
  - name: common
    version: 5.0.1
    repository: "file://./charts/common"
bash
helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts/
cd charts
helm pull bjw-s/common --untar
3. values.yaml 작성 (애플리케이션 명세)

App Template

yaml
controllers:
  main:
    strategy: Recreate

    containers:
      main:
        image:
          repository: vaultwarden/server
          tag: 1.25.2

        env:
          DATA_FOLDER: "config"

service:
  main:
    controller: main
    ports:
      http:
        port: 80
      websocket:
        enabled: true
        port: 3012

ingress:
  main:
    hosts:
      - host: vaultwarden.example.com
        paths:
          - path: /
            pathType: Prefix
            service:
              identifier: main
              port: http

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi
    globalMounts:
      - path: /config
4. 의존성 빌드 및 로컬 검증 (CLI 워크플로우)

차트 구조 작성이 완료되었다면, 아래 가이드라인 순서대로 터미널에서 검증을 진행합니다.

yaml
#Step 1: 의존성 차트 다운로드
helm dependency update ./my-custom-app

#Step 2: 템플릿 정적 분석 (Lint)
helm lint ./my-custom-app

#Step 3: 최종 쿠버네티스 YAML 렌더링 확인 (Dry-run / Template)
helm template my-release ./my-custom-app
💡 공식 가이드라인 핵심 요약
  1. 템플릿 작성 금지: templates/ 디렉터리는 비워둡니다. 모든 리소스 형태는 values.yaml의 구조적 선언만으로 결정됩니다.
  2. 컨트롤러 중심 구조: controllers.<이름>.containers.<이름> 구조를 기반으로 다중 컨테이너(Sidecar 등) 패턴도 values.yaml 내에서 쉽게 확장할 수 있습니다.
  3. 업데이트 주의: 메이저 버전 업데이트(예: v1 -> v2 -> v3) 시 values.yaml 스키마 구조가 크게 변경되는 경향이 있으므로, 의존성 선언 시 반드시 버전을 고정(v3.x.x)해서 관리해야 인프라가 안정적으로 유지됩니다.

features

Bitnami Chart Download / Control
bash
# repo 등록
helm repo add bitnami https://charts.bitnami.com/bitnami

# 차트 전체 리스트
helm search repo bitnami

# 차트 버전리스트
helm search repo bitnami/grafana -l

# 차트 다운로드
helm pull bitnami/grafana --untar --version=8.2.17 #Chart-version
chart push for my repository OCI
bash
docker login $myrepository
helm push $(helm package . | grep -o '/.*') oci://$myrepository/$project
Deploy to helm repository (1 depth)
bash
helm package */.
helm repo index .
Generate Default value
bash
helm show values ${repo}/${chart} > values.origin.yaml
Get Overwrited Values
bash
#helm repo list
#...
repo= #Set your repo `Name` -- 사용자가 등록한 repo Name은 일반화할 수 없음.
sdiff -s \
 <(helm show values ${repo}/$(cat Chart.yaml | yq '.name') \
   --version=$(cat Chart.yaml | yq '.version') | yq -oprops) \
 <(cat ./values.yaml | yq -oprops)

Posted:

/

Category:

Author:

fredric

Tags:

, , , , , , , , , , , , , ,

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *