KAL
Menu

Dasar Helm

Model pengemasan Helm: chart, values, template, dan konsep release di dalam kluster.

Daftar isi

Topik ini menjelaskan model pengemasan Helm dari sisi paling dasar, yaitu chart sebagai paket template, values sebagai nilai penyesuaian, dan release sebagai hasil instalasi yang dilacak di dalam kluster. Pembahasan dimulai dari struktur chart dan metadata Chart.yaml, dilanjutkan peran values.yaml serta cara template dirender, kemudian perintah instalasi dan pelacakan release, dan ditutup simulasi perenderan yang dapat dijalankan ulang. Contoh yang digunakan tetap pada aplikasi catatan dengan komponen API.

Chart sebagai paket template#

Chart adalah paket yang berisi template manifest beserta metadatanya, sehingga sekumpulan objek dapat didistribusikan dan diinstal sebagai satu kesatuan. Sebuah chart berbentuk folder dengan struktur yang diatur Helm, atau berkas arsip .tgz yang dihasilkan perintah helm package. Template di dalamnya ditulis dengan sintaks templating milik Go, yaitu teks manifest yang berisi placeholder yang digantikan nilainya saat perenderan berlangsung.

Struktur chart paling sederhana untuk aplikasi catatan terlihat seperti berikut.

text Struktur direktori 
catatan-api/
├── Chart.yaml
├── values.yaml
└── templates/
    └── deployment.yaml

Berkas Chart.yaml menyatakan identitas chart, sedangkan folder templates menyimpan template manifest yang dirender saat instalasi. Pada bundle topik ini, berkas-berkas chart ditampilkan datar di samping artikel, misalnya Chart.yaml yang dalam chart sesungguhnya berada di akar folder catatan-api.

yaml Chart.yaml 
apiVersion: v2
name: catatan-api
description: Chart awal untuk API aplikasi catatan
version: 0.1.0
appVersion: "1.2.0"

Dua bidang versi pada berkas ini sering tertukar. Bidang version adalah versi chart itu sendiri, sedangkan appVersion adalah versi aplikasi yang dibungkusnya. Chart versi 0.1.0 dapat membungkus aplikasi versi 1.2.0, sehingga keduanya naik dengan alasan yang berbeda.

values sebagai nilai penyesuaian#

values.yaml berisi nilai default yang menjadi acuan perenderan apabila tidak ada penyesuaian lain. Setiap kunci pada berkas ini dapat ditimpa saat instalasi melalui berkas values lain atau argumen –set, sehingga chart yang sama dapat dipasang di banyak lingkungan tanpa menyentuh template-nya.

yaml values.yaml 
replicaCount: 1
image:
  repository: registry.local/catatan-api
  tag: "1.2.0"
containerPort: 8000
service:
  type: ClusterIP
  port: 80

Kunci di atas menyediakan titik penyesuaian yang lazim. replicaCount mengatur jumlah replika Deployment, image menyatakan asal image beserta tag-nya, containerPort menyatakan port yang dibuka aplikasi, dan service menampung pengaturan Service yang template-nya tidak ditampilkan pada topik ini. Kunci yang bertingkat, misalnya image.tag, diakses pada template melalui jalur titik yang sama dengan strukturnya.

Template dan perenderan#

Template adalah berkas manifest yang sebagian teksnya digantikan saat perenderan. Placeholder ditulis dengan kurung kurawal ganda, misalnya {{ .Values.replicaCount }} yang mengambil nilai kunci replicaCount dari values. Helm merender seluruh template chart di sisi klien, kemudian mengirim hasilnya sebagai manifest biasa ke API server, sehingga kluster tidak pernah melihat sintaks template.

yaml template-deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: catatan-api
  labels:
    app: catatan-api
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: catatan-api
  template:
    metadata:
      labels:
        app: catatan-api
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.containerPort }}

Berkas berikut tersimpan sebagai templates/deployment.yaml dalam chart. Placeholder {{ .Values.image.repository }} dan {{ .Values.image.tag }} mengikuti kunci bertingkat pada values.yaml, sehingga nilai yang muncul selalu berasal dari satu sumber yang sama.

Perenderan berikut disimulasikan dengan Python agar dapat dijalankan ulang pada sandbox. Skrip membaca values.yaml dan template-deployment.yaml dari bundle, lalu mengganti setiap placeholder .Values dengan nilai yang dibaca PyYAML.

python simulasi-render.py 
# Simulasi perenderan Helm: placeholder .Values pada templat diganti dengan
# nilai yang dibaca dari values.yaml, sebagaimana helm install merender templat.
import re
import yaml

with open("values.yaml", encoding="utf-8") as berkas:
    values = yaml.safe_load(berkas)
with open("template-deployment.yaml", encoding="utf-8") as berkas:
    templat = berkas.read()

def ganti_placeholder(padanan):
    jalur = padanan.group(1).split(".")[1:]  # buang awalan .Values
    nilai = values
    for kunci in jalur:
        nilai = nilai[kunci]
    return str(nilai)

hasil = re.sub(r"{{\s*\.Values([A-Za-z0-9_.]+)\s*}}", ganti_placeholder, templat)
print(hasil)
text Keluaran 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: catatan-api
  labels:
    app: catatan-api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: catatan-api
  template:
    metadata:
      labels:
        app: catatan-api
    spec:
      containers:
        - name: api
          image: "registry.local/catatan-api:1.2.0"
          ports:
            - containerPort: 8000

Keluaran di atas adalah manifest yang akan dikirim Helm ke API server. Tidak ada lagi kurung kurawal yang tersisa, karena setiap placeholder telah digantikan nilai dari values.yaml. Proses yang sama dijalankan helm template untuk meninjau hasil perenderan tanpa instalasi.

Release sebagai instalasi bernama#

Release adalah satu instalasi chart yang diberi nama dan dilacak sampai dihapus. Satu chart dapat diinstal berkali-kali pada kluster yang sama dengan nama release yang berbeda, dan setiap instalasi berjalan sendiri-sendiri. Nama release diberikan pada saat instalasi, kemudian disebut kembali pada setiap perintah pengelolaan berikutnya.

bash 
# tidak-dijalankan
# menginstal chart dari folder catatan-api dengan nama release catatan
helm install catatan ./catatan-api
text Contoh keluaran 
NAME: catatan
LAST DEPLOYED: Tue May 12 09:14:03 2026
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Keluaran instalasi menyatakan status deployed dan nomor revisi pertama. Setelah terpasang, daftar release dapat dilihat dengan helm list, sedangkan isi values dan manifest yang tersimpan dapat diperiksa dengan helm get values dan helm get manifest. Penghapusan release dilakukan dengan helm uninstall, dan nama release yang sama dapat digunakan kembali setelahnya.

bash 
# tidak-dijalankan
# menampilkan daftar release pada namespace saat ini
helm list
text Contoh keluaran 
NAME     NAMESPACE REVISION UPDATED                             STATUS    CHART              APP VERSION
catatan  default   1        2026-05-12 09:14:03.81234 +0000 UTC deployed  catatan-api-0.1.0  1.2.0

Keadaan release yang tersimpan di kluster#

Setiap release menyimpan keadaannya di dalam kluster sebagai objek Secret bertipe helm.sh/release.v1 pada namespace tempat release berada. Secret tersebut memuat chart, values, dan manifest yang telah dirender, ditambah nomor revisi serta statusnya. Setiap perubahan pada release menambah satu revisi, sehingga riwayat keadaan tersusun berurutan di dalam kluster.

Pendekatan ini menjelaskan dua perilaku Helm yang sering ditanyakan pemula. Helm tidak membutuhkan komponen server di dalam kluster, karena seluruh perenderan dilakukan di sisi klien sebelum manifest dikirim. Selain itu, helm list pada namespace lain tidak menampilkan release yang ada, karena keadaan release tersimpan per namespace dan helm secara default melihat namespace yang sedang aktif saja.

Ringkasan#

  • Chart adalah paket template manifest beserta Chart.yaml dan values.yaml yang dapat didistribusikan sebagai folder atau arsip .tgz.
  • values.yaml berisi nilai default yang dapat ditimpa saat instalasi, dan seluruh template dirender di sisi klien sebelum dikirim ke API server.
  • Release adalah instalasi chart yang diberi nama dan dilacak beserta revisinya sebagai Secret bertipe helm.sh/release.v1.
  • Perintah helm install, helm list, dan helm get values membentuk siklus dasar pengelolaan release.

Referensi#