Helm 사용하기

Helm으로 Kubernetes 클러스터에서 패키지를 관리하는 기본 방법을 설명하는 가이드입니다.

출처: 문서

본문

이 가이드는 Helm으로 Kubernetes 클러스터에서 패키지를 관리하는 기본 방법을 설명합니다. Helm 클라이언트를 이미 설치했다고 가정합니다.

몇몇 빠른 명령을 실행하는 데만 관심이 있다면 빠른 시작 가이드로 시작해도 좋습니다. 이 장은 Helm 명령의 세부 사항을 다루고 Helm을 사용하는 방법을 설명합니다.

이 가이드는 차트, 리포지토리, 릴리스에 익숙하다고 가정합니다. 이 구성 요소에 대한 소개는 Helm 소개를 참조하세요.

'helm search': 차트 찾기

Helm에는 강력한 검색 명령이 있습니다. 두 가지 다른 유형의 소스를 검색하는 데 사용할 수 있습니다.

helm search hub 는 수십 개의 서로 다른 리포지토리의 helm 차트를 나열하는 Artifact Hub를 검색합니다.
helm search repo 는 로컬 helm 클라이언트에 추가한 리포지토리(helm repo add 사용)를 검색합니다. 이 검색은 로컬 데이터를 대상으로 하므로 공개 네트워크 연결이 필요 없습니다.

helm search hub 를 실행하면 공개적으로 사용 가능한 차트를 찾을 수 있습니다.

$ helm search hub wordpress
URL                                                 CHART VERSION APP VERSION DESCRIPTION
https://hub.helm.sh/charts/bitnami/wordpress        7.6.7         5.2.4       Web publishing platform for building blogs and ...
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.6.3        v0.6.3      Presslabs WordPress Operator Helm Chart
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.7.1        v0.7.1      A Helm chart for deploying a WordPress site on ...

위 명령은 Artifact Hub에서 모든 wordpress 차트를 검색합니다.

필터가 없으면 helm search hub 는 사용 가능한 모든 차트를 보여줍니다.

helm search hub 는 artifacthub.io의 위치 URL을 노출하지만 실제 Helm 리포지토리는 노출하지 않습니다. helm search hub --list-repo-url 은 실제 Helm 리포지토리 URL을 노출하며, 새 리포지토리를 추가할 때(helm repo add [NAME] [URL]) 유용합니다.

helm search repo 로는 이미 추가한 리포지토리의 차트 이름을 찾을 수 있습니다.

$ helm repo add brigade https://brigadecore.github.io/charts
"brigade" has been added to your repositories
$ helm search repo brigade
NAME                          CHART VERSION APP VERSION DESCRIPTION
brigade/brigade               1.3.2         v1.2.1      Brigade provides event-driven scripting of Kube...
brigade/brigade-github-app    0.4.1         v0.2.1      The Brigade GitHub App, an advanced gateway for...
brigade/brigade-github-oauth  0.2.0         v0.20.0     The legacy OAuth GitHub Gateway for Brigade
brigade/brigade-k8s-gateway   0.1.0                     A Helm chart for Kubernetes
brigade/brigade-project       1.0.0         v1.0.0      Create a Brigade project
brigade/kashti                0.4.0         v0.4.0      A Helm chart for Kubernetes

Helm 검색은 퍼지 문자열 매칭 알고리즘을 사용하므로 단어나 구의 일부를 입력할 수 있습니다.

$ helm search repo kash
NAME            CHART VERSION APP VERSION DESCRIPTION
brigade/kashti  0.4.0         v0.4.0      A Helm chart for Kubernetes

검색은 사용 가능한 패키지를 찾는 좋은 방법입니다. 설치하고 싶은 패키지를 찾으면 helm install 로 설치할 수 있습니다.

'helm install': 패키지 설치

새 패키지를 설치하려면 helm install 명령을 사용합니다. 가장 간단한 형태로 두 인자를 받습니다: 사용자가 고른 릴리스 이름과 설치하려는 차트 이름입니다.

$ helm install happy-panda bitnami/wordpress
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

이제 wordpress 차트가 설치되었습니다. 차트를 설치하면 새 release 객체가 생성된다는 점에 유의하세요. 위 릴리스의 이름은 happy-panda 입니다. (Helm이 이름을 생성하도록 하려면 릴리스 이름을 생략하고 --generate-name 을 사용하세요.)

설치하는 동안 helm 클라이언트는 생성된 리소스, 릴리스 상태, 그리고 수행할 수 있거나 수행해야 하는 추가 구성 단계에 대한 유용한 정보를 출력합니다.

Helm은 다음 순서로 리소스를 설치합니다.

Namespace
NetworkPolicy
ResourceQuota
LimitRange
PodSecurityPolicy
PodDisruptionBudget
ServiceAccount
Secret
SecretList
ConfigMap
StorageClass
PersistentVolume
PersistentVolumeClaim
CustomResourceDefinition
ClusterRole
ClusterRoleList
ClusterRoleBinding
ClusterRoleBindingList
Role
RoleList
RoleBinding
RoleBindingList
Service
DaemonSet
Pod
ReplicationController
ReplicaSet
Deployment
HorizontalPodAutoscaler
StatefulSet
Job
CronJob
Ingress
APIService
MutatingWebhookConfiguration
ValidatingWebhookConfiguration

Helm은 모든 리소스가 실행될 때까지 기다리지 않고 종료됩니다. 많은 차트가 600MB가 넘는 Docker 이미지를 요구하며, 클러스터에 설치하는 데 오랜 시간이 걸릴 수 있습니다.

릴리스의 상태를 추적하거나 구성 정보를 다시 읽으려면 helm status 를 사용할 수 있습니다.

$ helm status happy-panda
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

위 출력은 릴리스의 현재 상태를 보여줍니다.

설치 전 차트 사용자 정의 (Customizing the Chart Before Installing)

여기에서처럼 설치하면 이 차트의 기본 구성 옵션만 사용합니다. 대부분 선호하는 구성을 사용하도록 차트를 사용자 정의하고 싶을 것입니다.

차트에서 구성 가능한 옵션을 보려면 helm show values 를 사용하세요.

$ helm show values bitnami/wordpress
## Global Docker image parameters
## Please, note that this will override the image parameters, including dependencies, configured to use the global value
## Current available global Docker image parameters: imageRegistry and imagePullSecrets
##
# global:
#   imageRegistry: myRegistryName
#   imagePullSecrets:
#     - myRegistryKeySecretName
#   storageClass: myStorageClass

## Bitnami WordPress image version
## ref: https://hub.docker.com/r/bitnami/wordpress/tags/
##
image:
  registry: docker.io
  repository: bitnami/wordpress
  tag: 5.6.0-debian-10-r35
  [..]

그런 다음 YAML 형식 파일에서 이 설정 중 하나라도 재정의하고, 설치 중에 그 파일을 전달할 수 있습니다.

$ echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml
$ helm install -f values.yaml bitnami/wordpress --generate-name

위 명령은 기본 MariaDB 사용자 user0 를 만들고 이 사용자에게 새로 생성된 user0db 데이터베이스에 대한 접근 권한을 부여하지만, 그 차트의 나머지 기본값은 모두 받아들입니다.

설치 중에 구성 데이터를 전달하는 방법은 두 가지입니다.

--values (또는 -f): 재정의가 포함된 YAML 파일을 지정합니다. 여러 번 지정할 수 있으며 가장 오른쪽 파일이 우선합니다.
--set: 명령줄에서 재정의를 지정합니다.

둘 다 사용하면 --set 값이 --values 에 병합되며 더 높은 우선순위를 갖습니다. --set 으로 지정한 재정의는 Secret에 저장됩니다. --set 된 값은 helm get values <release-name> 으로 특정 릴리스에 대해 볼 수 있습니다. --set 된 값은 helm upgrade 를 --reset-values 로 실행해 지울 수 있습니다.

`--set` 의 형식과 제한 사항 (The Format and Limitations of `--set`)

--set 옵션은 0개 이상의 이름/값 쌍을 받습니다. 가장 간단하게는 --set name=value 처럼 사용합니다. 그에 해당하는 YAML은 다음과 같습니다.

name: value

여러 값은 , 문자로 구분됩니다. 그래서 --set a=b,c=d 는 다음과 같습니다.

a: b
c: d

더 복잡한 표현도 지원됩니다. 예를 들어 --set outer.inner=value 는 다음과 같이 변환됩니다.

outer:
  inner: value

목록은 값을 { 와 } 로 감싸 표현할 수 있습니다. 예를 들어 --set name={a, b, c} 는 다음과 같이 변환됩니다.

name:
  - a
  - b
  - c

특정 이름/키를 null 이나 빈 배열 [] 로 설정할 수 있습니다. 예를 들어 --set name=[],a=null 은 다음과 같이 변환됩니다.

name: []
a: null

Helm 2.5.0부터 배열 인덱스 구문을 사용해 목록 항목에 접근할 수 있습니다. 예를 들어 --set servers[0].port=80 은 다음과 같습니다.

servers:
  - port: 80

이런 식으로 여러 값을 설정할 수 있습니다. --set servers[0].port=80,servers[0].host=example 은 다음과 같습니다.

servers:
  - port: 80
    host: example

때로는 --set 줄에 특수 문자를 사용해야 할 때가 있습니다. 백슬래시로 문자를 이스케이프할 수 있습니다. --set name=value1\,value2 는 다음과 같습니다.

name: "value1,value2"

마찬가지로 점 시퀀스도 이스케이프할 수 있으며, 차트가 toYaml 함수로 어노테이션, 레이블, 노드 셀렉터를 파싱할 때 유용합니다. --set nodeSelector."kubernetes\.io/role"=master 구문은 다음과 같습니다.

nodeSelector:
  kubernetes.io/role: master

깊게 중첩된 데이터 구조는 --set 으로 표현하기 어려울 수 있습니다. 차트 설계자는 values.yaml 파일 형식을 설계할 때 --set 사용을 고려해야 합니다(Values Files에서 더 읽어보세요).

더 많은 설치 방법 (More Installation Methods)

helm install 명령은 여러 소스에서 설치할 수 있습니다.

차트 리포지토리 (위에서 본 대로)
로컬 차트 아카이브 (helm install foo foo-0.1.1.tgz)
압축이 풀린 차트 디렉터리 (helm install foo path/to/foo)
전체 URL (helm install foo https://example.com/charts/foo-1.2.3.tgz)

'helm upgrade' 와 'helm rollback': 릴리스 업그레이드, 실패 시 복구

차트의 새 버전이 릴리스되거나 릴리스 구성을 변경하려면 helm upgrade 명령을 사용할 수 있습니다.

업그레이드는 기존 릴리스를 가져와 사용자가 제공한 정보에 따라 업그레이드합니다. Kubernetes 차트는 크고 복잡할 수 있으므로 Helm은 가장 덜 침습적인 업그레이드를 시도합니다. 마지막 릴리스 이후 변경된 것만 업데이트합니다.

$ helm upgrade -f panda.yaml happy-panda bitnami/wordpress

위 경우 happy-panda 릴리스가 같은 차트로 업그레이드되지만 새 YAML 파일이 사용됩니다.

mariadb.auth.username: user1

helm get values 로 새 설정이 적용되었는지 확인할 수 있습니다.

$ helm get values happy-panda
mariadb:
  auth:
    username: user1

helm get 명령은 클러스터의 릴리스를 살펴보는 데 유용한 도구입니다. 그리고 위에서 볼 수 있듯이 panda.yaml 의 새 값이 클러스터에 배포되었음을 보여줍니다.

이제 릴리스 중에 계획대로 되지 않는 일이 생기면 helm rollback [RELEASE] [REVISION] 으로 이전 릴리스로 쉽게 롤백할 수 있습니다.

$ helm rollback happy-panda 1

위 명령은 happy-panda 를 첫 번째 릴리스 버전으로 롤백합니다. 릴리스 버전은 증가하는 리비전입니다. 설치, 업그레이드, 롤백이 일어날 때마다 리비전 번호가 1씩 증가합니다. 첫 번째 리비전 번호는 항상 1입니다. 그리고 helm history [RELEASE] 로 특정 릴리스의 리비전 번호를 볼 수 있습니다.

릴리스가 롤백으로 생성된 경우 helm history 에 --show-rollback-revision 을 전달해 출력에 ROLLBACK 열을 추가할 수 있습니다. 이 열은 각 롤백이 대상으로 한 리비전을 보여줍니다.

설치/업그레이드/롤백에 유용한 옵션 (Helpful Options for Install/Upgrade/Rollback)

설치/업그레이드/롤백 중 Helm 동작을 사용자 정의하기 위해 지정할 수 있는 다른 유용한 옵션이 몇 가지 있습니다. 이 목록이 전체 CLI 플래그 목록은 아닙니다. 모든 플래그에 대한 설명을 보려면 helm <command> --help 를 실행하세요.

--timeout: Kubernetes 명령이 완료될 때까지 기다릴 Go duration 값입니다. 기본값은 5m0s 입니다.
--wait: 모든 Pod가 준비 상태가 되고, PVC가 바인딩되고, Deployment가 최소(Desired 빼기 maxUnavailable) Pod를 준비 상태로 가지며, Service가 IP 주소를 가질 때까지(LoadBalancer면 Ingress 포함) 기다린 후 릴리스를 성공으로 표시합니다. --timeout 값만큼 기다립니다. 타임아웃에 도달하면 릴리스는 FAILED 로 표시됩니다. 참고: Deployment가 replicas 를 1로 설정하고 롤링 업데이트 전략의 일부로 maxUnavailable 을 0으로 설정하지 않은 경우, 최소 Pod 준비 조건을 충족하면 --wait 가 준비 상태로 반환됩니다.
--no-hooks: 이 명령의 훅 실행을 건너뜁니다.
--recreate-pods (upgrade 와 rollback 에서만 사용 가능): 이 플래그는 (배포에 속한 Pod를 제외하고) 모든 Pod를 재생성하게 합니다. (Helm 3에서 DEPRECATED)

'helm uninstall': 릴리스 제거

클러스터에서 릴리스를 제거할 때는 helm uninstall 명령을 사용합니다.

$ helm uninstall happy-panda

이렇게 하면 클러스터에서 릴리스가 제거됩니다. 현재 배포된 모든 릴리스는 helm list 명령으로 볼 수 있습니다.

$ helm list
NAME            VERSION UPDATED                         STATUS          CHART
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0

위 출력에서 happy-panda 릴리스가 제거되었음을 알 수 있습니다.

Helm의 이전 버전에서는 릴리스가 삭제될 때 삭제 기록이 남았습니다. Helm 3에서는 삭제가 릴리스 기록도 제거합니다. 삭제된 릴리스 기록을 유지하려면 helm uninstall --keep-history 를 사용하세요. helm list --uninstalled 는 --keep-history 플래그로 제거된 릴리스만 보여줍니다.

helm list --all 플래그는 Helm이 보유한 모든 릴리스 기록을 보여줍니다. 여기에는 실패했거나 삭제된 항목(--keep-history 를 지정한 경우)의 기록도 포함됩니다.

$  helm list --all
NAME            VERSION UPDATED                         STATUS          CHART
happy-panda     2       Wed Sep 28 12:47:54 2016        UNINSTALLED     wordpress-10.4.5.6.0
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0
kindred-angelf  2       Tue Sep 27 16:16:10 2016        UNINSTALLED     alpine-0.1.0

이제 릴리스가 기본적으로 삭제되므로 제거된 리소스를 롤백하는 것은 더 이상 불가능합니다.

'helm repo': 리포지토리 작업

Helm 3는 더 이상 기본 차트 리포지토리를 제공하지 않습니다. helm repo 명령 그룹은 리포지토리를 추가, 나열, 제거하는 명령을 제공합니다.

helm repo list 로 구성된 리포지토리를 확인할 수 있습니다.

$ helm repo list
NAME            URL
stable          https://charts.helm.sh/stable
mumoshu         https://mumoshu.github.io/charts

helm repo add [NAME] [URL] 로 새 리포지토리를 추가할 수 있습니다.

$ helm repo add dev https://example.com/dev-charts

차트 리포지토리는 자주 변경되므로, 언제든지 helm repo update 를 실행해 Helm 클라이언트를 최신 상태로 유지할 수 있습니다.

리포지토리는 helm repo remove 로 제거할 수 있습니다.

자신만의 차트 만들기 (Creating Your Own Charts)

차트 개발 가이드는 자신만의 차트를 개발하는 방법을 설명합니다. 하지만 helm create 명령으로 빠르게 시작할 수 있습니다.

$ helm create deis-workflow
Creating deis-workflow

이제 ./deis-workflow 에 차트가 있습니다. 편집하고 자신만의 템플릿을 만들 수 있습니다.

차트를 편집하면서 helm lint 로 잘 구성되었는지 검증할 수 있습니다.

배포를 위해 차트를 패키징할 때는 helm package 명령을 실행할 수 있습니다.

$ helm package deis-workflow
deis-workflow-0.1.0.tgz

그 차트는 이제 helm install 로 쉽게 설치할 수 있습니다.

$ helm install deis-workflow ./deis-workflow-0.1.0.tgz
...

패키징된 차트는 차트 리포지토리에 로드될 수 있습니다. 자세한 내용은 Helm 차트 리포지토리 문서를 참조하세요.

결론

이 장은 검색, 설치, 업그레이드, 제거를 포함한 helm 클라이언트의 기본 사용 패턴을 다뤘습니다. 또한 helm status, helm get, helm repo 같은 유용한 유틸리티 명령도 다뤘습니다.

이 명령들에 대한 자세한 내용은 Helm의 내장 도움말(helm help)을 참조하세요.

다음 장에서는 차트를 개발하는 과정을 살펴봅니다.

더 알아보기 (Learn more)

차트 개발 팁과 요령 - 프로덕션 차트 개발 노하우
Helm 소개 - Helm 개념 개요

Helm 사용하기