[k8s] Helm 4.2 차트 관리 완벽 가이드: OCI 배포, Helm 3 EOL, 실전 운영 체크포인트

목차

• Helm 4가 자리 잡은 지금, 무엇을 기준으로 봐야 할까요?
• Helm이 뭔지 다시 한번 짚고 가겠습니다
• Helm 3 vs Helm 4 주요 변경점 비교
• Helm 4.2.2 설치 및 초기 설정 가이드
• 1단계: Helm 4 설치
• 2단계: 자동완성(Autocomplete) 설정
• 3단계: 차트 소스와 OCI 레지스트리 준비
• 나만의 Helm 차트 만들기 — 실전 예제
• 차트 스캐폴딩 생성
• Chart.yaml 설정
• values.yaml 커스터마이징
• Deployment 템플릿 작성
• kubectl과 통합 배포 — 실무에서 이렇게 씁니다
• 환경별 values 파일 분리 전략
• 배포 명령어 실전 레시피
• 업그레이드와 롤백
• Helm 자동배포 — GitHub Actions 연동 예시
• ⚠️ 제가 삽질한 것들 — 트러블슈팅 모음
• 문제 1: 이름 재사용 에러
• 문제 2: values.yaml의 시크릿 관리
• 문제 3: 차트 의존성 업데이트 안 됨
• 문제 4: Helm 4에서 달라진 OCI 인증
• ✅ 배포 결과 검증 — 이렇게 확인하세요
• Helm 릴리즈 전체 관리 명령어 요약
• 자주 묻는 질문 (FAQ)
• Q. Helm 3에서 Helm 4로 올리면 기존 릴리즈가 날아가나요?
• Q. values.yaml에서 민감 정보는 어떻게 관리하나요?
• Q. Helm으로 배포한 리소스를 kubectl로 직접 수정해도 되나요?
• Q. Helm 말고 다른 선택지는?
• 2026년 기준 추가 체크포인트 — Helm 3 EOL과 운영 전략
• 마무리 — Helm 4, 이것만 기억하세요

Helm 4가 자리 잡은 지금, 무엇을 기준으로 봐야 할까요?

처음 이 글을 썼을 때는 Helm 4.0 자체가 화제의 중심이었습니다. 그런데 2026년 8월 2일 기준으로는 공식 문서 버전 표기가 이제 Helm 4.2.2까지 올라와 있어서, 단순히 "4.0이 나왔다" 수준으로 접근하면 놓치는 포인트가 꽤 많습니다.

특히 지금은 Helm 4.2.2, OCI 레지스트리, Server-Side Apply, Helm 3 EOL, GitOps 배포 자동화를 함께 봐야 합니다. Helm 4의 핵심은 OCI를 "새로 정식 지원"한다기보다, 이미 자리 잡은 OCI registry 기반 차트 배포와 supply chain security 흐름을 더 실무적으로 강화했다는 쪽에 가깝습니다.

그리고 더 중요한 변화도 생겼습니다. Helm 3는 2026년 9월 9일 마지막 기능 릴리즈가 예정되어 있고, 보안 패치는 2027년 2월 10일까지만 제공됩니다. 이제는 진짜 Helm 4 마이그레이션을 미루기 어려운 시점입니다.

Helm이 뭔지 다시 한번 짚고 가겠습니다

Helm은 쿠버네티스 애플리케이션을 차트(chart)라는 패키지 단위로 관리하는 쿠버네티스 패키지 매니저입니다. Deployment, Service, Ingress, Secret 같은 리소스를 한 번에 묶어서 설치하고, 버전 관리하고, 롤백할 수 있게 도와줍니다.

실무에서 Helm이 좋은 이유는 단순합니다. 반복 배포가 쉬워지고, 환경별 설정 분리가 편해지고, GitOps나 CI/CD 파이프라인에 붙이기 좋기 때문입니다. 지금은 여기에 OCI registry, digest pinning, Artifact Hub, 그리고 supply chain security까지 엮는 흐름이 사실상 표준이 됐습니다.

Helm 3 vs Helm 4 주요 변경점 비교

Helm 4에서 제가 가장 크게 느낀 변화는 "차트는 대부분 그대로인데, 운영 습관은 조금 바꿔야 한다"는 점이었습니다.

• 새 릴리즈 기본 적용 방식: Helm 4는 새 릴리즈 설치 시 server-side apply를 기본으로 사용합니다.
• 기존 Helm 3 릴리즈 연속성 유지: 업그레이드나 롤백 시에는 기존 릴리즈의 apply 방식에 맞춰 동작합니다.
• OCI 강화: 차트를 digest로 설치할 수 있어서 공급망 보안 측면이 좋아졌습니다.
• 플러그인 시스템 개편: WebAssembly 기반 플러그인 런타임이 추가됐고, post-renderer도 플러그인 방식으로 바뀌었습니다.
• CLI 플래그 변경: --atomic은 --rollback-on-failure, --force는 --force-replace로 이름이 바뀌었습니다. 예전 플래그는 아직 동작하지만 deprecated 경고가 뜹니다.
• 리소스 상태 추적 개선: kstatus 기반 감시가 들어가면서 배포 대기 상태를 더 자세히 볼 수 있습니다.
• 멀티 문서 values: 복잡한 values 구성을 더 유연하게 나눌 수 있습니다.
• Charts v3 실험 기능: 차트 포맷 차세대 버전이 실험 단계로 공개됐지만, 운영에서는 아직 v2를 기준으로 보는 게 안전합니다.

Helm 4.2.2 설치 및 초기 설정 가이드

2026년 8월 기준으로는 설치 예시도 조금 손봐야 합니다. 특히 리눅스에서 공식 스크립트를 쓸 때는 get-helm-4 스크립트를 사용하는 흐름이 문서에 반영되어 있고, Ubuntu/Debian 저장소는 예전 Balto 기준 문서를 그대로 따라가면 안 됩니다.

1단계: Helm 4 설치

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh
helm version

macOS라면 보통 아래 한 줄이면 됩니다.

brew install helm

Windows는 환경에 따라 다음 중 하나가 편합니다.

choco install kubernetes-helm
winget install Helm.Helm
scoop install helm

Ubuntu/Debian은 현재 공식 문서가 Buildkite APT 저장소 기준이고, GPG 키 지문 확인까지 같이 넣는 흐름이 더 안전합니다.

HELM_BUILDKITE_APT_KEY_ID="DDF78C3E6EBB2D2CC223C95C62BA89D07698DBC6"
sudo apt-get install curl gpg apt-transport-https --yes
curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey > "${TMPDIR:-/tmp}/helm.gpg"
if [ "$(gpg --show-keys --with-colons "${TMPDIR:-/tmp}/helm.gpg" | awk -F: '$1 == "fpr" {print $10}' | head -n 1)" != "${HELM_BUILDKITE_APT_KEY_ID}" ]; then echo "ERROR: Unexpected Helm APT key ID"; exit 1; fi
cat "${TMPDIR:-/tmp}/helm.gpg" | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

2단계: 자동완성(Autocomplete) 설정

source <(helm completion bash)

zsh를 쓰는 분은 아래처럼 설정하면 됩니다.

mkdir -p ~/.zfunc
helm completion zsh > ~/.zfunc/_helm

3단계: 차트 소스와 OCI 레지스트리 준비

예전에는 공식 레포지터리를 먼저 추가하는 흐름을 많이 썼는데, 지금은 상황이 조금 다릅니다. charts.helm.sh/stable는 사실상 아카이브 성격이고, 새 프로젝트를 찾을 때는 Artifact Hub나 각 벤더의 OCI registry를 먼저 보는 게 현실적입니다.

helm repo add stable https://charts.helm.sh/stable
helm repo update

다만 운영용 신규 배포라면 아래처럼 OCI 흐름을 익혀두는 쪽이 더 중요합니다.

helm registry login ghcr.io
helm pull oci://ghcr.io/example/charts/myapp --version 1.2.3
helm install myapp oci://ghcr.io/example/charts/myapp --version 1.2.3

주의: Helm 4에서는 helm registry login에 전체 URL이 아니라 도메인만 넣어야 합니다. 예를 들어 https://ghcr.io가 아니라 ghcr.io입니다.

나만의 Helm 차트 만들기 — 실전 예제

차트 스캐폴딩 생성

helm create myapp
cd myapp

처음 생성하면 템플릿이 꽤 많은데, 실무에서는 안 쓰는 리소스를 빨리 덜어내는 게 편합니다. ingress를 안 쓰면 관련 템플릿부터 정리해두세요.

Chart.yaml 설정

apiVersion: v2
name: myapp
description: A Helm chart for Kubernetes
type: application
version: 0.1.0
appVersion: "1.0.0"

Helm 4에서도 일반적인 애플리케이션 차트는 여전히 apiVersion: v2를 사용합니다. 다만 2026년 8월 기준으로는 Charts v3가 실험 단계로 공개돼 있어서, 테스트 환경에서는 한 번 검토해볼 만합니다. 운영 차트는 아직 v2 기준으로 두는 쪽이 안전합니다.

values.yaml 커스터마이징

replicaCount: 2
image:
  repository: nginx
  tag: "1.27.1"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

예시 이미지 태그도 너무 오래된 버전으로 굳혀두지 않는 게 좋습니다. 운영에서는 values를 한 파일에 몰아넣기보다 환경별로 나누는 게 낫습니다. Helm 4의 멀티 문서 values 기능도 생겼지만, 팀 단위에서는 여전히 파일 분리 전략이 제일 관리하기 쉽습니다.

Deployment 템플릿 작성

템플릿 작성 자체는 Helm 3와 크게 다르지 않습니다. 다만 Helm 4에서 새 릴리즈는 server-side apply가 기본이기 때문에, 다른 운영 툴이나 operator와 리소스 필드 충돌이 있던 환경에서는 오히려 더 안정적으로 느껴질 수 있습니다.

kubectl과 통합 배포 — 실무에서 이렇게 씁니다

환경별 values 파일 분리 전략

values.yaml
values-dev.yaml
values-staging.yaml
values-prod.yaml

이 패턴은 여전히 유효합니다. GitOps 환경에서도 리뷰가 쉬워서 저는 계속 이 방식을 선호합니다.

배포 명령어 실전 레시피

helm upgrade --install myapp ./myapp -n demo --create-namespace -f values-dev.yaml
helm upgrade --install myapp ./myapp -n prod -f values-prod.yaml --rollback-on-failure

예전 습관대로 --atomic을 써도 아직은 동작하지만, 자동화 스크립트는 이제 --rollback-on-failure로 바꿔두는 게 좋습니다.

OCI digest 기반 배포를 쓰면 더 재현성 있게 가져갈 수 있습니다.

helm install myapp oci://registry.example.com/charts/myapp@sha256:abcdef1234567890

업그레이드와 롤백

helm upgrade myapp ./myapp -n demo -f values-dev.yaml
helm rollback myapp 1 -n demo
helm history myapp -n demo

Helm 3에서 만들었던 릴리즈를 Helm 4로 업그레이드한다고 해서 갑자기 server-side apply로 강제 전환되지는 않습니다. 기존 릴리즈는 이전 apply 방식을 따라가므로 이 부분은 생각보다 안전합니다.

Helm 자동배포 — GitHub Actions 연동 예시

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/setup-helm@v4
      - run: helm version
      - run: helm upgrade --install myapp ./chart -n prod --create-namespace -f values-prod.yaml --rollback-on-failure

GitOps를 쓰지 않더라도 이 정도 구성만 해도 소규모 팀 배포 자동화에는 꽤 충분합니다. 다만 private OCI registry를 쓴다면 사전에 helm registry login 단계를 넣어두세요.

⚠️ 제가 삽질한 것들 — 트러블슈팅 모음

문제 1: 이름 재사용 에러

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

이건 여전히 자주 만납니다. 보통은 이미 같은 릴리즈 이름이 존재하는 상태라서 그렇습니다.

helm list -A | grep myapp
helm uninstall myapp -n demo

문제 2: values.yaml의 시크릿 관리

비밀번호, 토큰, 인증서는 values.yaml에 평문으로 넣지 않는 게 기본입니다. 실무에서는 External Secrets, Sealed Secrets, SOPS, 또는 클라우드 시크릿 매니저 연동을 씁니다. Helm은 시크릿 관리 도구가 아니라 배포 도구라는 점을 계속 기억하시면 덜 꼬입니다.

문제 3: 차트 의존성 업데이트 안 됨

helm dependency update
helm dependency build

의존성 버전 범위가 너무 빡빡하거나, 레포지터리 인증이 꼬여 있는 경우가 많습니다. OCI 기반 의존성을 쓰는 경우에는 로그인 상태도 같이 확인하세요.

문제 4: Helm 4에서 달라진 OCI 인증

제가 가장 헷갈렸던 부분입니다. Helm 4에서는 helm registry login https://registry.example.com처럼 URL 전체를 넣는 습관이 더 잘 깨집니다.

helm registry login registry.example.com

도메인만 넣는 것으로 바뀌었기 때문에, 오래된 사내 위키나 배포 스크립트가 있으면 여기서 한 번씩 걸립니다.

✅ 배포 결과 검증 — 이렇게 확인하세요

helm status myapp -n demo
helm get values myapp -n demo
helm get manifest myapp -n demo
kubectl get all -n demo
kubectl describe deploy myapp -n demo

Helm 4는 상태 추적이 더 좋아졌기 때문에, 배포가 오래 걸릴 때 이전보다 원인 파악이 조금 수월합니다. 그래도 최종 검증은 결국 kubectl로 리소스 상태를 함께 보는 게 제일 확실합니다.

Helm 릴리즈 전체 관리 명령어 요약

helm list -A
helm history myapp -n demo
helm upgrade --install myapp ./myapp -n demo -f values-dev.yaml
helm rollback myapp 1 -n demo
helm uninstall myapp -n demo
helm registry login ghcr.io
helm pull oci://ghcr.io/example/charts/myapp --version 1.2.3

자주 묻는 질문 (FAQ)

Q. Helm 3에서 Helm 4로 올리면 기존 릴리즈가 날아가나요?

아니요. 공식 문서 기준으로는 기존 Helm 3 차트와 릴리즈 대부분이 Helm 4와 호환되도록 설계됐습니다. 즉, 보통은 Helm 바이너리만 교체해도 기존 릴리즈를 계속 관리할 수 있습니다. 다만 운영 환경에서는 꼭 스테이징에서 먼저 검증하세요.

Q. values.yaml에서 민감 정보는 어떻게 관리하나요?

평문 저장은 피하세요. Kubernetes Secret 자체도 Base64 인코딩일 뿐이라 충분한 보안 대책이 아닙니다. External Secrets, Sealed Secrets, SOPS 같은 조합이 지금도 가장 많이 쓰입니다.

Q. Helm으로 배포한 리소스를 kubectl로 직접 수정해도 되나요?

가능은 하지만 추천하지 않습니다. 다음 Helm 업그레이드 때 덮어써질 수 있고, drift가 생기기 쉽습니다. 특히 GitOps 환경에서는 차트와 values를 수정하는 쪽이 훨씬 안전합니다.

Q. Helm 말고 다른 선택지는?

있습니다. 단순 템플릿 커스터마이징이면 Kustomize, GitOps 운영까지 같이 가져가려면 Argo CD나 Flux, 더 강한 패키징 규칙이 필요하면 Carvel 계열도 선택지입니다. 다만 범용성, 생태계, 차트 재사용성까지 같이 보면 2026년에도 Helm은 여전히 가장 현실적인 기본값입니다.

2026년 기준 추가 체크포인트 — Helm 3 EOL과 운영 전략

이건 이번 업데이트에서 꼭 추가해야 하는 부분입니다. 2026년 6월 Helm 프로젝트가 공식적으로 밝힌 일정에 따르면, Helm 3의 마지막 기능 릴리즈는 2026년 9월 9일이고 보안 패치 지원 종료일은 2027년 2월 10일입니다. 즉, 아직 당장 종료된 것은 아니지만 운영 로드맵에서는 이미 마이그레이션을 시작해야 하는 단계입니다.

또 하나는 저장소 보안입니다. Debian/Ubuntu 쪽은 과거 커뮤니티 APT 미러 도메인인 baltocdn.com 관련 보안 공지가 있었기 때문에, 오래된 설치 문서나 사내 위키를 그대로 복붙하면 위험할 수 있습니다. 지금은 공식 문서 기준으로 Buildkite APT 저장소를 사용하고, 가능하면 GPG 키 지문까지 검증하는 쪽이 안전합니다.

그리고 Helm 4에서는 Charts v3가 실험 기능으로 등장했습니다. 바로 운영에 넣을 단계는 아니지만, 내부 플랫폼 팀이나 차트 제작 팀이라면 테스트 환경에서 미리 감을 잡아두는 게 좋습니다. Helm 4의 안정화가 끝나면 차트 생태계도 이 방향으로 천천히 움직일 가능성이 큽니다.

• 운영팀: Helm 3 사용 중이면 2026년 하반기 안에 Helm 4 검증 시작
• CI/CD 담당자: --atomic, --force, --post-renderer 사용 스크립트 점검
• 플랫폼 엔지니어: OCI registry, digest 배포, registry auth 흐름 표준화
• 보안 담당자: 오래된 APT 저장소 문서와 서드파티 설치 경로 정리

마무리 — Helm 4, 이것만 기억하세요

지금 시점의 핵심은 세 가지입니다. 첫째, Helm 4.2.2 기준으로 운영 문서를 업데이트할 것. 둘째, OCI registry와 digest 배포를 기본값으로 익힐 것. 셋째, Helm 3 EOL 일정을 감안해서 2026년 안에 마이그레이션 검증을 끝내는 쪽으로 움직일 것.

차트 작성법 자체는 크게 바뀌지 않았습니다. 하지만 설치 경로, 인증 방식, 플러그인 구조, 배포 플래그, 운영 보안 포인트는 분명히 달라졌습니다. 그래서 지금 Helm 글을 다시 본다면, 단순 입문서보다 Helm 4 운영 가이드 관점으로 읽는 게 더 맞습니다.

Helm 4는 생각보다 낯설지 않습니다. 다만 예전 습관을 조금만 정리해두면, 앞으로의 쿠버네티스 배포 자동화와 GitOps 운영이 훨씬 편해집니다.

🔄 마지막 업데이트: 2026년 08월