HELM RELEASE LIFECYCLE

Helm 설치·업그레이드·롤백 운영 레시피

Helm v4 CLI를 검증해 설치하고 chart·values·권한을 렌더링과 server dry-run으로 점검한 뒤 install·upgrade·history·rollback을 Secret 노출과 데이터 마이그레이션 위험 없이 운영합니다.

Helm 4 설치helm upgrade installhelm rollback historyhelm dry-run hide-secretHelm values backuprollback-on-failure

지원 환경Helm v4.2.x CLI · Linux amd64/arm64

예상 시간약 45분

난이도중급

검토일2026-09-02

BEFORE YOU START

시작 전에 준비하세요

대상 kube-context·cluster·namespace와 release 이름, namespace 범위 배포 권한

고정 chart version·provenance 또는 digest와 코드 리뷰된 values 파일

현재 release revision·values·manifest를 보관할 권한 제한 백업 경로

hook Job·CRD·PVC·DB migration의 upgrade와 rollback 동작을 확인한 점검 계획

실패 시 이전 application image·schema와 호환되는 복구 revision

권장 대상 Helm release를 처음 설치하거나 운영 업그레이드·실패 rollback을 재현 가능한 절차로 관리하려는 개발자·플랫폼 운영자

FOLLOW THE RECIPE

8단계 구성·점검 레시피

확인시스템을 변경하지 않는 점검 단계

Helm·kubectl·context와 버전 확인

2026-09 현재 Helm v4가 stable이며 공식 명령 문서는 v4.2.x입니다. Helm v4.2.x는 Kubernetes v1.33~v1.36만 공식 지원하며 더 최신 Kubernetes에 대한 forward compatibility를 보장하지 않습니다. 기존 Helm, Kubernetes client/server와 현재 context를 확인해 다른 cluster 오조작을 막습니다.

기존 Helm

command -v helm
helm version

kubectl client·server

kubectl version

현재 context·cluster·namespace

kubectl config current-context
kubectl config view --minify -o jsonpath='{.clusters[0].name}{" namespace="}{..namespace}{"\n"}'

Helm 환경 경로

helm env

registry·repository 경로와 내부 주소가 포함될 수 있어 외부 공유 전 마스킹합니다.

대상 cluster·context·namespace를 작업 승인서와 대조했습니다.
Helm v4.2.x와 공식 호환되는 Kubernetes v1.33~v1.36 조합을 사용합니다.
기존 Helm major가 다르면 plugin·chart 호환성과 migration 문서를 확인했습니다.

결과 읽기

context나 namespace가 다르거나 Helm major 전환이 필요한 경우 같은 작업으로 묶지 않습니다. 먼저 설치 방식과 대상 cluster를 확정합니다.

다음 판단

namespace 상태와 최소 RBAC, release 충돌, cluster 이상 여부를 점검합니다.

확인시스템을 변경하지 않는 점검 단계

RBAC·release·cluster 상태 사전 점검

실제 배포 전에 namespace 접근권한과 기존 release, Pod·PVC·이벤트를 확인합니다. cluster-admin이 아니라 chart가 요구하는 최소 리소스 권한을 사용합니다.

namespace와 배포 권한

kubectl get namespace <NAMESPACE>
kubectl auth can-i create deployments -n <NAMESPACE>
kubectl auth can-i create secrets -n <NAMESPACE>

기존 release

helm list -n <NAMESPACE> --all
helm status <RELEASE> -n <NAMESPACE>

release가 아직 없으면 status의 not found는 신규 설치 분기를 뜻합니다.

현재 workload·PVC

kubectl get deploy,statefulset,daemonset,pod,pvc -n <NAMESPACE> -o wide

최근 Warning 이벤트

kubectl events -n <NAMESPACE> --types=Warning

release 이름과 namespace가 기존 다른 release와 충돌하지 않습니다.
chart의 cluster-scoped 리소스·CRD 생성 필요 여부와 별도 승인 주체를 확인했습니다.
기존 Pending·CrashLoop·PVC 장애를 이번 배포 전 상태로 기록했습니다.
배포 계정은 필요한 namespace와 resource verb에만 권한이 있습니다.

결과 읽기

기존 release가 pending-upgrade·pending-rollback 상태이거나 cluster 자체가 불안정하면 새 upgrade를 겹쳐 실행하지 않습니다.

다음 판단

공식 binary와 checksum·signature를 확인해 Helm CLI를 설치합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

Helm v4.2.x 공식 binary 검증·설치

공식 get.helm.sh binary를 파일로 내려받고 release 페이지의 SHA-256과 signature를 검증한 뒤 설치합니다. 원격 script를 shell로 바로 연결하지 않습니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

아키텍처 확인

uname -m

x86_64는 linux-amd64, aarch64는 linux-arm64 artifact를 선택합니다.

고정 버전 artifact·checksum·서명 다운로드

curl -fLO https://get.helm.sh/helm-v4.2.4-linux-<ARCH>.tar.gz
curl -fLO https://get.helm.sh/helm-v4.2.4-linux-<ARCH>.tar.gz.sha256sum
curl -fLO https://get.helm.sh/helm-v4.2.4-linux-<ARCH>.tar.gz.asc

공식 release checksum 대조

sha256sum --check helm-v4.2.4-linux-<ARCH>.tar.gz.sha256sum

checksum 파일명과 artifact가 같은 v4.2.4·아키텍처인지 확인합니다. 불일치하면 압축을 풀지 않습니다.

서명 검증

gpg --verify helm-v4.2.4-linux-<ARCH>.tar.gz.asc helm-v4.2.4-linux-<ARCH>.tar.gz

Helm 공식 KEYS에서 검증한 signer key를 별도 keyring에 준비한 뒤 실행합니다. unknown key나 BAD signature를 무시하지 않습니다.

압축 내용 확인·binary 설치

tar -tzf helm-v4.2.4-linux-<ARCH>.tar.gz
tar -xzf helm-v4.2.4-linux-<ARCH>.tar.gz
sudo install -o root -g root -m 0755 linux-<ARCH>/helm /usr/local/bin/helm
helm version

운영체제 아키텍처와 artifact 이름이 일치합니다.
SHA-256과 signer signature가 모두 성공했습니다.
helm version이 v4.2.4를 표시하고 기존 다른 binary가 PATH 앞에 있지 않습니다.
설치 파일·checksum·signer 정보를 변경 기록에 남겼습니다.

결과 읽기

checksum·signature가 하나라도 실패하거나 공식 release에 없는 버전이면 설치하지 않습니다. package manager를 쓸 경우 해당 공급자와 업데이트 정책도 별도 검토합니다.

다음 판단

현재 release와 values·manifest·history를 권한 제한 경로에 백업합니다.

주의권한·연결·중단 영향을 확인할 단계

release·values·manifest 백업과 변경 입력 고정

기존 release가 있다면 history, 실제 적용 values와 렌더링 manifest를 백업합니다. 출력에는 Secret이 포함될 수 있으므로 0700 디렉터리·0600 파일로 제한하고 외부 공유하지 않습니다.

권한 제한 백업 디렉터리

install -d -m 0700 "<APPROVED_BACKUP_DIR>"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>"

다른 사용자와 공유하지 않는 전용 디렉터리를 사용하고 mode가 700인지 확인합니다.

release history 백업

umask 077
helm history <RELEASE> -n <NAMESPACE> -o yaml > "<APPROVED_BACKUP_DIR>/history.before.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/history.before.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/history.before.yaml"

적용 values 백업

umask 077
helm get values <RELEASE> -n <NAMESPACE> --all -o yaml > "<APPROVED_BACKUP_DIR>/values.before.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/values.before.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/values.before.yaml"

values에 비밀번호·token이 포함될 수 있습니다. 암호화 저장소에 두고 외부 티켓·Git에 올리지 않습니다.

렌더링 manifest 백업

umask 077
helm get manifest <RELEASE> -n <NAMESPACE> > "<APPROVED_BACKUP_DIR>/manifest.before.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/manifest.before.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/manifest.before.yaml"

Secret 리소스의 base64 data도 비밀입니다. 접근을 제한하고 보존 기간 뒤 안전하게 폐기합니다.

chart·values checksum

sha256sum <PINNED_CHART_PACKAGE.tgz> <REVIEWED_VALUES.yaml>

현재 정상 revision과 chart version을 history에서 기록했습니다.
values·manifest 백업은 0600이며 암호화·접근 통제되는 경로에 있습니다.
고정 chart package와 리뷰된 values의 checksum을 기록했습니다.
CRD·hook·PVC·DB migration이 rollback 가능한지 담당자가 확인했습니다.

결과 읽기

release가 없는 신규 설치라면 get 명령의 not found는 정상이며, namespace 기준 자원 목록과 values checksum을 기준선으로 보관합니다.

다음 판단

lint·template·server dry-run에서 Secret을 숨기고 실제 변경을 검토합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

lint·dry-run 뒤 install 또는 upgrade 실행

렌더링 결과와 server dry-run을 검토한 뒤 신규 설치와 기존 업그레이드 중 하나만 실행합니다. chart version을 고정하고 wait·timeout·history 한도를 명시합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

chart lint·로컬 렌더링

helm lint <PINNED_CHART_PACKAGE.tgz> -f <REVIEWED_VALUES.yaml>
umask 077
helm template <RELEASE> <PINNED_CHART_PACKAGE.tgz> -n <NAMESPACE> -f <REVIEWED_VALUES.yaml> --include-crds > "<APPROVED_BACKUP_DIR>/rendered.proposed.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/rendered.proposed.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/rendered.proposed.yaml"

렌더링 파일에도 Secret이 포함될 수 있어 백업 디렉터리 권한을 유지합니다.

server dry-run

helm upgrade <RELEASE> <PINNED_CHART_PACKAGE.tgz> -n <NAMESPACE> -f <REVIEWED_VALUES.yaml> --install --dry-run=server --hide-secret --timeout 10m

--hide-secret이 있어도 hook 출력·NOTES·비 Secret 리소스의 민감값을 검토합니다. dry-run은 hook·외부 DB migration 전체를 보장하지 않습니다.

A. 신규 release 설치

helm install <RELEASE> <PINNED_CHART_PACKAGE.tgz> -n <NAMESPACE> -f <REVIEWED_VALUES.yaml> --wait=watcher --wait-for-jobs --timeout 10m

helm list에서 release가 없고 namespace·자원 충돌을 확인한 신규 설치에서만 실행합니다.

B. 기존 release 업그레이드

helm upgrade <RELEASE> <PINNED_CHART_PACKAGE.tgz> -n <NAMESPACE> -f <REVIEWED_VALUES.yaml> --rollback-on-failure --wait=watcher --wait-for-jobs --timeout 10m --history-max 10

기존 정상 revision이 있고 DB migration·hook의 rollback 호환성을 확인한 경우에만 실행합니다. --force-replace·--take-ownership은 사용하지 않습니다.

lint·template·server dry-run이 성공하고 예상 밖 cluster-scoped·RBAC·Secret 변경이 없습니다.
신규 install과 기존 upgrade 분기 중 하나만 실행했습니다.
chart와 values version·checksum, release·namespace·timeout을 기록했습니다.
hook Job과 DB migration의 중복 실행·rollback 영향을 확인했습니다.

결과 읽기

--rollback-on-failure는 Kubernetes release를 이전 성공 revision으로 되돌릴 수 있지만 외부 DB migration·PVC 데이터·hook 부작용을 자동으로 복구하지 않습니다.

다음 판단

release 상태, history, workload·hook·애플리케이션 동작을 함께 검증합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

release·workload·hook·서비스 검증

Helm status만 보지 않고 revision, 적용 values, Kubernetes 자원, Warning 이벤트와 애플리케이션 smoke test를 확인합니다. helm test는 hook 자원을 생성할 수 있어 chart 내용을 확인한 뒤 실행합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

release 상태·history

helm status <RELEASE> -n <NAMESPACE>
helm history <RELEASE> -n <NAMESPACE>

적용 values checksum 비교

umask 077
helm get values <RELEASE> -n <NAMESPACE> --all -o yaml > "<APPROVED_BACKUP_DIR>/values.after.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/values.after.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/values.after.yaml"
sha256sum "<APPROVED_BACKUP_DIR>/values.after.yaml"

workload·Pod·PVC 상태

kubectl get deploy,statefulset,daemonset,pod,pvc -n <NAMESPACE> -o wide
kubectl events -n <NAMESPACE> --types=Warning

chart test hook

helm test <RELEASE> -n <NAMESPACE> --logs --timeout 5m

chart의 tests/ hook manifest와 권한·외부 호출을 검토했고 테스트 데이터 생성·비용 영향을 승인한 경우에만 실행합니다. 로그는 공유 전 마스킹합니다.

release STATUS가 deployed이고 기대 revision·chart version입니다.
모든 필수 workload가 Ready이고 restart·Pending·PVC 오류가 없습니다.
hook Job과 smoke test가 성공하고 오류율·지연·핵심 업무가 기준 범위입니다.
values와 image digest가 승인한 입력과 일치합니다.

결과 읽기

deployed 상태라도 애플리케이션·migration·PVC가 비정상일 수 있습니다. 실패 원인이 chart 변경인지 기존 cluster 장애인지 배포 전 기준선과 비교합니다.

다음 판단

release Secret, RBAC, image, provenance와 history·백업 보존을 최종 점검합니다.

확인시스템을 변경하지 않는 점검 단계

chart provenance·RBAC·Secret·image 보안 점검

chart 공급망과 생성된 권한·Secret·image를 확인합니다. Secret data는 출력하지 않고 metadata와 key 이름만 확인합니다.

chart metadata·provenance 검증

helm show chart <PINNED_CHART_PACKAGE.tgz>
helm verify <PINNED_CHART_PACKAGE.tgz>

provenance를 제공하지 않는 chart라면 OCI digest·서명과 내부 mirror 승인 절차를 사용합니다.

release 소유 RBAC

kubectl get role,rolebinding,serviceaccount -n <NAMESPACE> -l app.kubernetes.io/instance=<RELEASE> -o wide

Secret type·key 이름만 확인

kubectl get secret -n <NAMESPACE> -l app.kubernetes.io/instance=<RELEASE> -o jsonpath='{range .items[*]}{.metadata.name}{" type="}{.type}{" keys="}{range $k,$v := .data}{$k}{" "}{end}{"\n"}{end}'

실제 imageID

kubectl get pods -n <NAMESPACE> -l app.kubernetes.io/instance=<RELEASE> -o jsonpath='{range .items[*].status.containerStatuses[*]}{.name}{" "}{.image}{" imageID="}{.imageID}{"\n"}{end}'

chart package의 provenance 또는 OCI digest·서명을 검증했습니다.
chart version과 container image digest가 고정돼 있습니다.
ServiceAccount·Role·ClusterRole은 필요한 verb·resource·namespace로 최소화했습니다.
Secret 원문은 values·Git·shell history·일반 로그와 백업에 평문으로 남기지 않습니다.
post-renderer·plugin·hook은 신뢰한 고정 버전만 사용하고 실행 코드를 리뷰했습니다.
history와 backup의 접근권한·암호화·보존 기간을 정했습니다.

결과 읽기

검증되지 않은 chart, wildcard cluster-admin, mutable image tag, 평문 Secret이 있으면 운영 승인을 중단하고 공급망·권한을 먼저 수정합니다.

다음 판단

문제가 있을 때 복구할 revision과 rollback hook·migration 영향을 다시 확인합니다.

변경패키지·설정·서비스 상태가 달라지는 단계

revision dry-run·승인·rollback과 재검증

rollback도 새 revision을 만들고 hook을 실행할 수 있는 변경입니다. 되돌릴 revision의 chart·values와 DB schema·PVC 호환성을 확인하고 server dry-run 뒤 승인된 번호만 적용합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.

복구 후보 history·values 확인

helm history <RELEASE> -n <NAMESPACE>
umask 077
helm get values <RELEASE> -n <NAMESPACE> --revision <ROLLBACK_REVISION> --all -o yaml > "<APPROVED_BACKUP_DIR>/values.rollback-candidate.yaml"
chmod 0600 "<APPROVED_BACKUP_DIR>/values.rollback-candidate.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_DIR>/values.rollback-candidate.yaml"

후보 values에도 Secret이 있을 수 있어 0600 경로에서만 확인합니다.

rollback server dry-run

helm rollback <RELEASE> <ROLLBACK_REVISION> -n <NAMESPACE> --dry-run=server --wait=watcher --timeout 10m

dry-run 출력에도 민감정보가 있을 수 있고 외부 DB migration·hook 부작용을 완전히 검증하지 못합니다.

승인된 revision으로 rollback

helm rollback <RELEASE> <ROLLBACK_REVISION> -n <NAMESPACE> --wait=watcher --wait-for-jobs --timeout 10m

revision 번호, 현재·복구 chart, schema·PVC 호환성, hook 재실행을 승인받은 뒤 실행합니다. --force-replace를 추가하지 않습니다.

rollback 결과 검증

helm status <RELEASE> -n <NAMESPACE>
helm history <RELEASE> -n <NAMESPACE>
kubectl get deploy,statefulset,pod,pvc -n <NAMESPACE> -o wide
kubectl events -n <NAMESPACE> --types=Warning

정확한 rollback revision과 chart·values·image를 확인했습니다.
DB migration·CRD·PVC·hook을 별도 복구해야 하는지 담당자가 승인했습니다.
rollback 뒤 release가 deployed이고 workload·서비스 지표·핵심 업무가 회복됐습니다.
실패 revision과 rollback revision, 원인·시간·명령·후속 수정 계획을 기록했습니다.

결과 읽기

rollback 성공은 Kubernetes manifest revision 복구를 뜻할 뿐 DB·외부 시스템·PV 데이터를 자동 복원하지 않습니다. 복구 뒤에도 오류가 남으면 추가 revision 왕복을 멈춥니다.

다음 판단

원인을 chart·values·hook·cluster 상태로 분류하고 CI에 lint·schema·render·policy·staging rollback 검사를 추가해 재발을 막습니다.

SECURITY CHECK

운영 전 마지막 보안 점검

Helm binary와 chart의 checksum·signature·provenance 또는 OCI digest를 검증합니다.
kube-context·namespace·release를 명령마다 명시하고 cluster-admin kubeconfig를 CI에 넣지 않습니다.
dry-run·values·manifest·hook 로그도 Secret을 포함할 수 있어 출력·백업 접근을 제한합니다.
민감 파일을 만드는 각 명령 블록에서 umask 077·chmod 0600·stat 검증을 자체 수행하며 앞서 실행한 shell 상태에 의존하지 않습니다.
<...> 자리표시자는 승인된 리터럴 값으로 직접 치환하고 외부 입력으로 shell 명령을 조립하거나 eval하지 않습니다.
chart·image·dependency를 고정 버전으로 사용하고 post-renderer·plugin·hook 코드를 리뷰합니다.
CRD·PVC·DB migration은 Helm rollback 밖의 복구 계획과 검증된 백업을 둡니다.
--insecure-skip-tls-verify, --plain-http, --pass-credentials, --force-replace를 편의상 추가하지 않습니다.

COMMON ERRORS

자주 막히는 지점

another operation is in progress 또는 pending-upgrade

증상: upgrade가 다른 작업 진행 중 오류로 실패하거나 release가 pending-upgrade·pending-rollback에 머뭅니다.
가능한 원인: 이전 Helm 작업이 아직 실행 중이거나 hook·클라이언트 중단으로 revision 상태가 완료되지 않았을 수 있습니다.
확인 순서: 동시 배포를 중단하고 helm history·status, hook Job·이벤트를 확인한 뒤 검증된 revision rollback 여부를 판단합니다.

트러블슈팅으로 이어보기

ImagePullBackOff로 rollout timeout

증상: Helm은 wait 중 timeout되고 새 Pod 이벤트에 unauthorized·manifest unknown·x509가 표시됩니다.
가능한 원인: chart values의 image tag·digest, imagePullSecret 또는 Node registry 연결 문제일 수 있습니다.
확인 순서: Secret 값을 출력하지 말고 Pod 이벤트와 imageID를 ImagePullBackOff 가이드에서 분리합니다.

트러블슈팅으로 이어보기

Pod가 CrashLoopBackOff·probe 실패로 Ready가 안 됨

증상: 배포 자원은 만들어졌지만 restart가 증가하고 --wait가 성공하지 않습니다.
가능한 원인: 애플리케이션 설정·migration·resource limit·startup/liveness probe가 새 release와 맞지 않을 수 있습니다.
확인 순서: previous 로그, 종료 reason, resource와 probe를 확인하고 정상 revision과 비교합니다.

트러블슈팅으로 이어보기

Pending Pod·PVC 때문에 release가 준비되지 않음

증상: Pod가 Pending이고 FailedScheduling 또는 unbound PVC 이벤트가 지속됩니다.
가능한 원인: request·taint·affinity·StorageClass·PVC binding 또는 Node NotReady 문제일 수 있습니다.
확인 순서: workload values만 반복 수정하지 말고 scheduler·PVC·Node 상태 가이드로 분기합니다.

트러블슈팅으로 이어보기

PRIMARY REFERENCES

공식 문서

설치 저장소와 지원 버전은 바뀔 수 있습니다. 검토일 이후에는 링크된 공식 문서와 현재 서버의 패키지 후보 버전을 함께 확인하세요.

시작 전에 준비하세요

8단계 구성·점검 레시피

운영 전 마지막 보안 점검

자주 막히는 지점

another operation is in progress 또는 pending-upgrade

ImagePullBackOff로 rollout timeout

Pod가 CrashLoopBackOff·probe 실패로 Ready가 안 됨

Pending Pod·PVC 때문에 release가 준비되지 않음

공식 문서

설치 후 문제라면 여기서 이어가세요

함께 볼 구성 레시피