2026년 9월 기준 Chartmuseum 최신 버전은 v0.16.6 이고, Helm 3 부터는 Tiller 없이 helm 바이너리만으로 저장소를 붙입니다. 이 글의 S3 다운로드 주소와 옛 helm 명령은 지금 그대로 쓰면 안 되니 4절 표를 먼저 보시길 권합니다.
Helm 차트를 패키징해 저장소로 관리하게 된 배경
안녕하세요? 정리하는 개발자 워니즈입니다. 이번시간에는 Helm 챠트를 어떤식으로 패키징하고 repo를 지정하여 배포를 하는지 정리해보도록 하겠습니다.
지난 글들은 아래를 참고 해주시면 됩니다.
- 쿠버네티스 1편 : 설치 가이드
- 쿠버네티스 2편 : pod
- 쿠버네티스 3편 : service
- 쿠버네티스 4편 : deployment
- 쿠버네티스 5편 : pod 설정
- 쿠버네티스 6편 : 배포 전략
- 쿠버네티스 7편 : volume
- 쿠버네티스 8편 : daemonset
- 쿠버네티스 9편 : 테라폼을 통한 클러스터 구성
- 쿠버네티스 10편 : eks에서 volume 사용하기
- 쿠버네티스 11편 : helm
- 쿠버네티스 12편 : helm chart template
- 쿠버네티스 13편 : helm deploy
- 쿠버네티스 14편 : fluentd를 통한 log수집
- 쿠버네티스 15편 : chartmuseum
- 쿠버네티스 16편 : 배포툴(ArgoCD 설치방법/사용법)
- 쿠버네티스 17편 : 배포툴(ArgoCD 구성/알람)
- 쿠버네티스 18편 : 쿠버네티스 Autoscailing
- 쿠버네티스 19편 : 쿠버네티스 로깅 아키텍처
챠트까지는 생성을 하고 작성하는데 큰 무리가 없었는데, 이것을 패키징해서 어떻게 관리를 할 수 있을까 생각해보았습니다.
챠트뮤지엄은 Go언어로 작성된 오픈소스 Helm Chart Repository 서버입니다. 클라우드 스토리지를 Backend로 지원을 합니다. (Google Cloud Storate, Amazon S3, Microsoft Azure Blob Storage 등등)
1. 설치 방법
Chartmuseum은 다양한 플랫폼에서 제공되는 Helm Chart Repository로 쉽게 설치 및 조작이 가능합니다. 필자 같은 경우는 EKS를 구성해두고, CLI서버(kubectl command 호출 서버)에서 직접 Helm과 Tiller를 설치한 뒤, 이어서 Chartmuseum을 설치했습니다.
2026년 9월 기준으로 덧붙이면, Tiller 는 Helm 2 에만 있던 클러스터 쪽 구성요소이고 Helm 3 에서 제거되었습니다. 지금은 helm 바이너리 하나만 설치하면 되고, Helm 2 시절 구조는 예전에 정리한 Helm 기본 개념 정리에 남아 있습니다.
여기서 2가지 방식이 존재하는데
- 직접 설치를 하는 경우,
$ curl -LO https://s3.amazonaws.com/chartmuseum/release/latest/bin/linux/amd64/chartmuseum
$ chmod +x chartmuseum
$ ./chartmuseum --version
2026년 9월 28일에 다시 받아 보니 위 S3 주소는 403 을 돌려줘 더 이상 내려받을 수 없습니다. 지금은 공식 README 의 설치 스크립트나 GitHub 릴리스에 걸린 get.helm.sh 바이너리를 씁니다.
# 공식 설치 스크립트
$ curl https://raw.githubusercontent.com/helm/chartmuseum/main/scripts/get-chartmuseum | bash
# 또는 릴리스 바이너리 직접 받기 (v0.16.6, 2026-08-14)
$ curl -LO https://get.helm.sh/chartmuseum-v0.16.6-linux-amd64.tar.gz
$ tar -zxvf chartmuseum-v0.16.6-linux-amd64.tar.gz
$ ./linux-amd64/chartmuseum --version
설치가 완료되면, Chartmuseum을 기동해야합니다 .
./chartmuseum --debug --port=8080 \
--storage=amazon \
--storage-amazon-bucket=my-chart-bucket \
--storage-amazon-prefix= \
--storage-amazon-region=ap-northeast-2
- port
- aws bucket
- region
위의 내용을 셋팅해줍니다.
- Docker를 활용하여 설치를 하는 경우,
docker run -d -it \
-p 8080:8080 \
-e DEBUG=1 \
-e STORAGE="amazon" \
-e STORAGE_AMAZON_BUCKET="my-chart-bucket" \
-e STORAGE_AMAZON_PREFIX="" \
-e STORAGE_AMAZON_REGION="ap-northeast-2" \
-v ~/.aws:/home/chartmuseum/.aws:ro \
chartmuseum/chartmuseum:latest
공식 README 는 이제 GitHub Container Registry 이미지 ghcr.io/helm/chartmuseum:v0.16.6 을 예시로 씁니다. STORAGE, STORAGE_AMAZON_BUCKET 같은 환경변수 이름은 이 글과 같습니다.
Docker는 훨씬 간편하게 설치 및 기동이 가능합니다. 필자는 Docker를 활용해서 설치를 진행했습니다.
- 접속 테스트
설치가 완료된 후, http://{HOST}:8080 로 접속을 하게 되면 아래와 같은 화면이 노출됩니다
2. Chartmuseum 사용법
이제 Chart에 대한 repository를 직접 만들었습니다. 이제 준비되어있는 Chart를 패키징하고 뮤지엄으로 add를 하면 됩니다.
- Helm 클라이언트에 저장소 추가하기
$ helm repo add chartmuseum http://localhost:8080
해당 host에 8080으로 기동했기 때문에 localhost로 등록을 해주고, chartmuseum이라는 이름을 명시하여 등록을 완료했습니다.
- Chart 패키징
//helmchart가 작성되어있는 폴더 안으로 들어옵니다.
├── Chart.yaml
├── templates
│ ├── deployment_helm.yml
│ └── service_helm.yml
└── values.yaml
//chart를 패키징하는 명령어를 수행합니다.
$ helm package ./
Successfully packaged chart and saved it to: /root/helm/chart/my-app/my-app-0.1.1.tgz
//tgz 파일이 생성된 것이 보입니다.
├── Chart.yaml
├── my-app-0.1.1.tgz
├── templates
│ ├── deployment_helm.yml
│ └── service_helm.yml
└── values.yaml
위와 같은 순서로 패키징이 진행이 됩니다.
- Chartmuseum에 업로드
// 이제, curl 명령어를 통해서 Package되어있는 내용을 Chartmuseum에 등록하여 봅니다.
$ curl --data-binary "@my-app-0.1.1.tgz" http://localhost:8080/api/charts
// helm repo에 대한 변경사항을 update해줍니다.
$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Skip local chart repository
...Successfully got an update from the "chartmuseum" chart repository
...Successfully got an update from the "stable" chart repository
Update Complete. ⎈ Happy Helming!⎈
//이후에 검색을 해보면, chartmuseum repo에 정상적으로 등록이 된것을 확인할 수 있습니다.
$ helm search chartmuseum
NAME CHART VERSION APP VERSION DESCRIPTION chartmuseum/my-app 0.1.1 1.0 A Helm chart for my-app
Helm 3 이후로는 helm search chartmuseum 대신 helm search repo chartmuseum/ 처럼 repo 하위 명령으로 찾습니다.
- Backend Storage
S3 에도 정상적으로 tgz 파일이 업로드 되어있는 것을 볼 수 있습니다.
S3에서 index-cache.yaml 이라는 파일이 있습니다. 이 파일은 저장소에 보관되어 있는 Helm 챠트의 메타데이터를 보관하고 있습니다. 저장되어 있는 챠트의 목록, 이름, 다이제스트 등이 출력됩니다.
3. Chartmuseum으로부터 Helm Deploy
이제 Helm repo에 패키지를 정상적으로 등록하였습니다. 이제 repo로부터 패키징된 chart를 fetch받고, install하는 과정이 남아있습니다.
//chartmuseum repo에 my-app라는 이름의 Chart를 설치하라는 명령입니다.
$ helm install chartmuseum/my-app
$ helm list
dev-author-web 11 Mon May 25 19:21:56 2020 DEPLOYED dev-author-web-0.1.0 1.0 dev-web
Helm 3 부터는 릴리스 이름이 필수라서 helm install 릴리스이름 chartmuseum/차트이름 처럼 이름을 앞에 주거나 --generate-name 을 붙여야 합니다. 설치 이후 values 로 이미지 버전만 바꿔 배포하는 흐름은 Helm 차트 배포 정리에서 이어집니다.
정상적으로 Deploy까지 완료 되었습니다.
4. 2026년에 Chartmuseum 을 새로 쓴다면 무엇이 달라졌나요?
저장소 서버 역할과 업로드 API(POST /api/charts)는 그대로이고, 바뀐 것은 Helm 쪽 명령과 설치 경로입니다. 2026년 9월 28일에 GitHub 릴리스와 Helm 공식 문서를 다시 확인한 값입니다.
| 항목 | 이 글(2020년) | 2026년 9월 기준 |
|---|---|---|
| Chartmuseum | latest 바이너리 (S3 주소) | v0.16.6 (2026-08-14), 설치 스크립트 또는 get.helm.sh |
| 컨테이너 이미지 | chartmuseum/chartmuseum:latest | 공식 README 예시는 ghcr.io/helm/chartmuseum:v0.16.6 |
| Helm | Helm 2 와 Tiller | Helm v4.3.0 (2026-09-09), v3 계열 최신 v3.22.0 (2026-09-10), Tiller 없음 |
| 차트 검색 | helm search chartmuseum |
helm search repo chartmuseum/ |
| 차트 설치 | helm install chartmuseum/차트 |
helm install 이름 chartmuseum/차트 또는 --generate-name |
| 업로드 | curl --data-binary 로 /api/charts |
같은 API 그대로, helm-push 플러그인 v0.11.1 의 helm cm-push 도 가능 |
Helm v3 는 언제까지 지원되나요?
Helm v3 의 버그 수정은 2026년 7월 8일로 끝났고, 보안 수정은 2026년 11월 11일까지입니다. Helm v4.0.0 이 2025년 11월 12일에 나왔으니, 지금 새로 구성한다면 Helm 4 기준으로 맞추는 편이 좋을 것 같습니다.
Helm 4 에서도 helm cm-push 플러그인을 쓸 수 있나요?
쓸 수 있도록 고쳐졌습니다. helm-push 플러그인은 2026년 2월 9일 v0.11.1 에서 플러그인 정의를 Helm 3 과 Helm 4 양쪽에서 읽히는 형식으로 바꿨습니다. Helm 4 는 플러그인 구조를 새로 설계했기 때문에, 예전에 깔아 둔 플러그인이 있다면 최신 버전으로 다시 설치하는 편이 안전합니다.
$ helm plugin install https://github.com/chartmuseum/helm-push
$ helm cm-push ./ chartmuseum
Chartmuseum 대신 OCI 레지스트리를 써도 되나요?
됩니다. Helm 공식 차트 저장소 가이드도 저장소를 새로 만든다면 OCI 레지스트리를 먼저 검토해 보라고 적고 있습니다. OCI 방식은 helm push 차트.tgz oci://레지스트리/경로 로 올리고 helm install 이름 oci://레지스트리/경로/차트 --version 0.1.0 으로 설치합니다.
반대로 S3 같은 오브젝트 스토리지를 그대로 저장소로 쓰고 싶거나, 이미 helm repo add 방식에 맞춰 둔 배포 파이프라인이 있다면 Chartmuseum 이 여전히 간단합니다. 2026년 기준으로 헬름 차트 설치 값을 다시 정리한 예는 KeyCloak 헬름차트 설치 글에서 보실 수 있습니다.
5. 마치며…
챠트뮤지엄은 쉽게 이야기하면 Helm Chart에 대한 Repository입니다. 여기서 궁금한것이 매번 패키징을 진행하느냐가 가장 궁금했었습니다.
k8s로 굉장히 유명하신 분의 블로그에 문의글을 남겼고, 친절하게도 답변을 해주셨습니다. Chart에 대한 Meta정보가 변경되지 않는한, 패키징을 매번 할 필요는 없어보입니다.
필자의 프로젝트에서는 사실 이미지 버전만 신규로 구워지고 해당 이미지를 배포하는 내용이라 values.yaml파일에서 충분히 커버가 가능합니다. 따라서 repo를 구성해뒀지만, 패키징파일이 크게 변경될일은 없을 것 같습니다.
끝.
새 글이 올라오면 Threads @wonizz.ai 에도 올립니다. 팔로우해 두면 피드에서 바로 볼 수 있습니다.