Belajar Helm Chart - Membuat Chart Repository

#Pendahuluan

Setelah di episode 16 sebelumnya kita mengemas chart menjadi artefak .tgz yang ditandatangani dan versinya dibekukan lewat Chart.lock — pada episode kali ini kita membangun tempat penyimpanan artefak itu: chart repository. Ini titik di mana chart kalian berhenti menjadi file lokal dan mulai menjadi produk yang bisa dipakai siapa pun.

Mengapa topik ini penting? Sampai sekarang, rekan kerja kalian harus menyalin folder chart lewat git atau ZIP untuk bisa meng-install-nya — primitif, rawan versi basi, dan tidak bisa diotomasi. Repository mengubah semuanya: pengguna cukup helm repo add sekali, lalu helm search repo dan helm install kapan pun dengan constraint versi. Inilah yang membuat ekosistem Helm seperti Bitnami, ingress-nginx, dan prometheus-community bisa dikonsumsi oleh seluruh dunia dengan satu perintah. Tanpa repository, Helm hanyalah templating engine yang canggih; dengan repository, ia menjadi package manager sungguhan.

Di episode ini kita bedah anatomi repository — terutama index.yaml sebagai jantungnya — lalu menelusuri tipe-tipe repository yang umum dipakai, membangun repository HTTP sederhana, mengotomasi publikasi ke GitHub Pages dengan GitHub Actions, dan menutup dengan ChartMuseum untuk kebutuhan yang lebih enterprise.

#Pembahasan Utama

#Struktur Chart Repository — index.yaml sebagai Katalog

Secara teknis, chart repository hanyalah folder statis yang bisa diakses via HTTP(S), berisi dua hal: file chart .tgz dan sebuah index.yaml. Tidak ada server khusus, tidak ada database — hanya file. index.yaml adalah katalog yang memberitahu Helm: chart apa saja yang tersedia, versi apa saja, dan di URL mana setiap versi bisa diunduh.

Ketika kalian menjalankan helm search repo bitnami/nginx, Helm tidak menelusuri server — ia mengunduh index.yaml dari repository yang sudah ditambahkan, menyimpannya di cache lokal (~/.cache/helm/repository/), dan mencari dalam daftar itu. Begitu juga saat helm install dengan constraint versi: Helm memilih versi yang cocok langsung dari katalog, lalu mengunduh .tgz-nya. Artinya index.yaml harus selalu sinkron dengan file chart yang ada di folder — itulah yang dijaga oleh helm repo index.

Contoh isi index.yaml setelah di-generate:

apiVersion: v1
entries:
  myapp:
    - apiVersion: v2
      appVersion: "1.27.3"
      created: "2026-08-02T10:15:00Z"
      description: Chart aplikasi myapp
      digest: 1f7a4b3c9d2e0f1a8b6c4d2e0f1a8b6c
      name: myapp
      urls:
        - myapp-2.0.0.tgz
      version: 2.0.0
    - apiVersion: v2
      appVersion: "1.25.0"
      created: "2026-05-10T08:00:00Z"
      description: Chart aplikasi myapp
      digest: 9d2e0f1a8b6c4d2e0f1a8b6c1f7a4b3c
      name: myapp
      urls:
        - myapp-1.4.0.tgz
      version: 1.4.0
generated: "2026-08-02T10:16:00Z"

Perhatikan bagian urls — di sini URL-nya relatif (myapp-2.0.0.tgz), dan Helm akan menggabungkannya dengan base URL repository. Kalian bisa juga menulis URL absolut, misalnya saat chart disimpan di bucket terpisah. Bagian digest adalah SHA-256 dari arsip .tgz — ini yang membuat Helm bisa mendeteksi arsip korup atau tidak sesuai katalog.

#Tipe-Tipe Chart Repository

Karena repository hanyalah "folder + index.yaml yang bisa diakses HTTP", hampir semua tempat penyimpanan file bisa menjadi repository. Pilihan tipe adalah keputusan arsitektur yang memengaruhi cara kerja tim, jadi pahami trade-off masing-masing:

Pola yang penting diingat: semakin sederhana, semakin sedikit yang harus dioperasikan. Untuk chart publik, GitHub Pages yang statis sudah lebih dari cukup; untuk internal yang privat, bucket S3 dengan akses terbatas atau ChartMuseum lebih masuk akal. Jangan menambah kompleksitas server sebelum kebutuhan auth, multi-tenancy, atau API benar-benar ada.

#Membangun Repository HTTP Sederhana

Untuk memahami esensinya, mari bangun repository dari nol — hanya butuh tiga langkah: siapkan folder, taruh chart, lalu generate index.

# 1. Siapkan folder dan salin arsip chart ke dalamnya
mkdir -p ~/charts
cp myapp-2.0.0.tgz myapp-1.4.0.tgz ~/charts/
 
# 2. Generate index.yaml dari isi folder
cd ~/charts
helm repo index .
 
# 3. Serve folder sebagai situs statis
python3 -m http.server 8080

Sekarang di mesin lain (atau terminal lain), repository sudah bisa dipakai:

helm repo add myorg http://localhost:8080
helm search repo myorg
helm install myapp myorg/myapp --version 2.0.0

Ini menunjukkan sesuatu yang penting: repository Helm adalah konsep yang sangat tipis. Tidak ada logika di server — seluruh kecerdasan ada di client. Satu-satunya kewajiban server adalah menyajikan index.yaml dan file .tgz dengan benar.

Kapan kalian harus memperbarui index.yaml? Setiap kali ada chart baru masuk. Dua cara: regenerate seluruh folder (helm repo index .) yang aman dan idempoten, atau gunakan flag --merge untuk menggabungkan index lama dengan baru — berguna saat kalian hanya menambahkan satu versi chart baru tanpa memikirkan ulang entry lain. Aturan praktisnya: di tangan manusia, helm repo index . penuh lebih aman karena tidak ada risiko merge yang salah.

Sebelum melangkah lebih jauh, buka sebentar index.yaml yang baru digenerate — memahami isinya adalah kunci mendiagnosis masalah repository:

apiVersion: v1
entries:
  myapp:
    - apiVersion: v2
      description: Aplikasi demo untuk seri Helm
      name: myapp
      urls:
        - myapp-2.0.0.tgz
      version: 2.0.0
      digest: 8f9a3b...  # sha256 manifest, bukan chart

Tiga field yang paling sering menjadi sumber masalah: urls menentukan path relatif atau absolut menuju file .tgz — jika kalian memindahkan chart ke subfolder, perbarui field ini agar client bisa menemukan arsipnya; version adalah chart version yang di-pin pengguna (helm install ... --version 2.0.0); dan digest adalah sha256 dari manifest chart (bukan dari file .tgz mentah) — saat helm install menemukan digest yang tidak cocok dengan isi .tgz, ia menolak install dan menampilkan error "sha256 ... does not match". Inilah alasan mengapa index harus selalu di-generate ulang setelah file berubah: digest yang basi membuat chart tidak terinstall.

#GitHub Pages + GitHub Actions — Otomasi Publikasi

Repository HTTP di atas berfungsi, tapi ada masalah praktis: harus ada mesin yang menyala terus. Solusi gratis dan paling populer untuk chart publik adalah GitHub Pages — GitHub menyediakan hosting statis untuk setiap repository, dan karena chart repository adalah folder statis, ia cocok sempurna.

Strateginya: buat dua branch di satu repository. Branch main menyimpan source code chart (folder charts/ dan workflow). Branch gh-pages menyimpan hasil publikasi — folder berisi .tgz dan index.yaml yang siap di-serve oleh Pages. Setiap kali ada perubahan di main, GitHub Actions mengemas chart dan menulis hasilnya ke gh-pages.

Agar tidak menulis sendiri semua langkah ini (yang rawan salah), ekosistem Helm menyediakan chart-releaser-action (dari helm/chart-releaser). Action ini membaca semua chart di folder tertentu, membandingkan versi dengan yang sudah dipublikasikan, mengemas yang baru, dan men-generate ulang index.yaml secara otomatis. Workflow lengkapnya:

name: Release Charts
 
on:
  push:
    branches: [main]
 
jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Configure Git
        run: |
          git config user.name "chart-releaser"
          git config user.email "chart-releaser@users.noreply.github.com"
 
      - name: Run chart-releaser
        uses: helm/chart-releaser-action@v1.6.0
        with:
          charts_dir: charts
        env:
          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

Yang dilakukan workflow ini: setiap push ke main, chart-releaser-action memindai charts/, menemukan chart yang versinya belum pernah dirilis, mengemasnya, meng-commit hasilnya ke branch gh-pages, dan memperbarui index.yaml di sana. Publikasi chart jadi reproducible dan otomatis — tidak ada lagi langkah manual yang bisa terlupa.

Untuk memakai repository yang sudah diterbitkan:

helm repo add myorg https://<username>.github.io/<repo-name>
helm search repo myorg
helm repo update

URL Pages biasanya berbentuk https://<username>.github.io/<nama-repo>. Satu catatan: repo privat bisa memakai Pages hanya dengan langganan berbayar tertentu, jadi pola GitHub Pages secara alami cocok untuk chart yang memang publik — untuk chart internal, balik lagi ke bucket atau ChartMuseum.

#ChartMuseum — Repository dengan API

Jika kebutuhan kalian melampaui "folder statis" — misalnya butuh mengunggah chart via API dari CI, menghapus versi, autentikasi, atau multi-tenancy — saatnya mempertimbangkan ChartMuseum (github.com/helm/chartmuseum). Ia adalah server Go yang berperan sebagai repository dengan antarmuka HTTP API di atasnya.

Installasinya bisa lewat binary, container, atau langsung chart Helm-nya sendiri:

docker run --rm -d \
  --name chartmuseum \
  -p 8080:8080 \
  -e STORAGE=local \
  -e STORAGE_LOCAL_ROOTDIR=/charts \
  -v "$(pwd)/charts:/charts" \
  ghcr.io/helm/chartmuseum:latest

Dengan ChartMuseum, upload chart tidak lagi berarti "menaruh file di folder" — ia dilakukan lewat API:

# Upload chart
curl -L --data-binary "@myapp-2.0.0.tgz" \
  http://localhost:8080/api/charts
 
# Lihat daftar chart di repo
curl http://localhost:8080/api/charts/myapp
 
# Hapus satu versi
curl -X DELETE http://localhost:8080/api/charts/myapp/1.4.0

Poin pentingnya: ChartMuseum otomatis menjaga index.yaml tetap sinkron dengan setiap operasi API. Upload chart → index langsung berisi entry baru; delete versi → index ikut diupdate. Inilah yang membuatnya cocok untuk pipeline: CI bisa curl upload chart tanpa mengelola index secara manual.

Fitur yang membuatnya enterprise-ready:

• Autentikasi — proteksi dengan Basic Auth (AUTH_ANONYMOUS_GET untuk baca publik, lalu protect operasi tulis), atau integrasi dengan OpenID Connect/JWT untuk kontrol yang lebih granular.
• Multi-tenancy — ChartMuseum mendukung pemisahan tenant berbasis sub-path URL (/org-a/, /org-b/), sehingga satu instance bisa melayani beberapa tim dengan pemisahan chart.
• Storage backends — selain local, ia mendukung S3, GCS, Azure Blob, dan OSS. Ini membuat ChartMuseum bisa berjalan di server ephemeral sementara data chartnya hidup di object storage yang tahan lama.

Kapan kalian harus memilih ChartMuseum dibanding GitHub Pages? Jawabannya ketika kebutuhan non-fungsional muncul: perlu API untuk otomasi upload/delete, perlu auth, perlu multi-tenant, atau ingin data chart di storage yang terkelola. Untuk yang lain, struktur statis yang lebih sederhana justru lebih baik — satu hal yang lebih sedikit untuk dioperasikan dan diserang.

#Penutup

Pada episode 17 ini kita telah membangun rumah bagi chart kalian. Kita memahami bahwa chart repository secara teknis hanyalah folder statis berisi .tgz dan index.yaml — dan bahwa seluruh kecerdasan resolusi versi ada di client Helm, bukan di server. Kita membandingkan tipe-tipe repository dari HTTP statis, GitHub Pages, object storage cloud, OCI registry, hingga ChartMuseum, lengkap dengan trade-off masing-masing. Kita membangun repository HTTP dari nol dengan helm repo index, mengotomasi publikasi ke GitHub Pages menggunakan chart-releaser-action sehingga index.yaml selalu sinkron tanpa campur tangan manusia, dan menutup dengan ChartMuseum yang menambahkan API, autentikasi, multi-tenancy, dan storage backend terkelola di atas konsep yang sama.

Inti yang harus kalian bawa:

• Repository = folder statis + index.yaml; kecerdasan resolusi ada di client.
• helm repo index adalah penjaga sinkronisasi; jangan pernah lupa menjalankannya setelah menambah chart.
• GitHub Pages + chart-releaser-action memberi publikasi chart yang gratis dan otomatis untuk proyek publik.
• Pilih tipe repository berdasarkan kebutuhan nyata: statis untuk publik, bucket untuk internal, ChartMuseum saat butuh API/auth/multi-tenancy.
• helm repo update wajib dijalankan pengguna agar index.yaml terbaru sampai ke cache lokal.

Sekarang chart kalian punya rumah dan bisa dikonsumsi siapa pun. Tapi ada satu tipe repository yang kita sisakan di tabel tadi — OCI registry — yang mengubah cara Helm menyimpan dan memverifikasi chart secara fundamental. Di episode 18 selanjutnya kita akan membedah dukungan OCI: operasi helm push/helm pull, skema URL oci://, autentikasi registry, integrasi penandatanganan dengan Cosign, dan strategi migrasi dari repository HTTP. Pastikan tetap semangat!