Belajar Helm Chart - Dokumentasi Chart (README, NOTES.txt, helm-docs)

#Pendahuluan

Setelah di episode 14 sebelumnya kita membahas bagaimana menguji chart secara sistematis — mulai dari helm test, unit test dengan helm-unittest, validasi manifest dengan kubeconform, hingga linting dan integrasi testing ke CI dengan chart-testing — pada episode kali ini kita bergeser dari ranah yang "diperiksa mesin" ke ranah yang "dibaca manusia": dokumentasi chart.

Topik ini sering dianggap pelengkap, padahal ia justru penentu. Bayangkan kalian seorang engineer platform yang bertugas mengonsumsi chart dari tim lain. Tanpa dokumentasi, kalian harus membaca ratusan baris values.yaml, menebak-nebak arti setiap key, dan berharap helm install tidak meledak. Setiap chart yang dipublikasikan — ke Artifact Hub, ke repo internal, atau ke tim sendiri — adalah produk yang harus bisa dipakai orang lain tanpa bertanya ke pembuatnya. README.md adalah pintu depan produk itu, NOTES.txt adalah asisten yang berdiri di samping pengguna setelah instalasi selesai, dan CHANGELOG.md adalah catatan transparansi yang membuat pengguna berani melakukan upgrade.

Masalahnya, dokumentasi manual cepat basi. Setiap kali kalian menambah parameter di values.yaml, tabel konfigurasi di README langsung tidak sinkron. Di episode ini kita akan memecahkan masalah itu dari akarnya: membedah isi README.md yang lengkap, menulis NOTES.txt yang benar-benar membantu (bukan sekadar template), mendokumentasikan values dengan disiplin, lalu mengotomatiskan semuanya dengan helm-docs sehingga dokumentasi selalu sejalan dengan kode. Kita tutup dengan CHANGELOG.md sebagai alat komunikasi perubahan versi.

#Pembahasan Utama

#README.md — Wajah Pertama Chart Kalian

README.md adalah dokumen pertama yang dibaca siapa pun sebelum memutuskan memakai chart kalian. Ia adalah kontrak antara pembuat dan pengguna: pengguna berhak tahu apa yang mereka pasang, apa prasyaratnya, dan bagaimana cara menggunakannya. Sebuah README yang baik menjawab enam pertanyaan dengan urutan logis.

Pertama, deskripsi chart di bagian paling atas. Satu atau dua kalimat yang menjawab: aplikasi apa ini, dan untuk apa ia dipakai? Jangan menyalin description dari Chart.yaml mentah-mentah — di README kalian bisa menambahkan konteks, misalnya arsitektur singkat atau relasi antar komponen. Kedua, prerequisites. Ini daftar kejujuran: Kubernetes versi berapa, Helm versi berapa, apakah butuh storage class tertentu, apakah butuh Ingress Controller, apakah butuh cert-manager. Melewatkan bagian ini adalah sumber support ticket paling umum — pengguna memasang chart dengan versi yang tidak didukung, lalu melapor "chart-nya rusak".

Ketiga, instruksi instalasi. Mulai dari menambahkan repository sampai perintah helm install yang siap salin-tempel, lengkap dengan opsi --namespace dan --create-namespace. Keempat, tabel parameter konfigurasi. Ini bagian yang paling sering dicari orang: setiap key di values.yaml, artinya, tipe datanya, dan default-nya. Kelima, contoh penggunaan — misalnya cara mengaktifkan Ingress atau men-set resource limits. Keenam, upgrading notes dan uninstallation. Bagian upgrade menjelaskan apa yang berubah antar versi dan langkah migrasi; bagian uninstall cukup helm uninstall <release>, tapi sebaiknya disebutkan apakah data persisten ikut terhapus.

Ada satu aturan emas yang harus kalian pegang: README yang basi lebih buruk daripada tidak ada README. Dokumentasi yang ketinggalan zaman menyesatkan; ketiadaan dokumentasi setidaknya jujur. Karena itu kita tidak akan menulis tabel parameter secara manual — kita akan menggenerasinya otomatis, dan itu kita bahas di bagian helm-docs.

#NOTES.txt — Asisten Setelah Instalasi

Ketika helm install selesai, Helm menjalankan file templates/NOTES.txt dan mencetak hasilnya ke terminal. Ini bukan hiasan: ia adalah tahap pertama interaksi pengguna dengan release mereka. Coba ingat pengalaman memasang chart yang berakhir dengan teks membingungkan seperti "Your release has been deployed" tanpa apa pun sesudahnya. Pengguna langsung bertanya: "Lalu? Bagaimana saya mengaksesnya?"

NOTES.txt yang baik menjawab pertanyaan itu secara proaktif. Informasi yang wajib ada: cara mendapatkan URL akses aplikasi, credential yang perlu diambil (misalnya password admin yang digenerate), dan informasi penting lain seperti lokasi data atau catatan keamanan. Yang membuat NOTES.txt kuat adalah ia mendukung templating penuh — ia adalah template Go biasa, jadi ia bisa membaca .Values, .Release, bahkan hasil render resource lain.

Contoh nyata, catatan akses yang bergantung pada apakah Ingress diaktifkan atau tidak:

1. Dapatkan URL aplikasi dengan perintah berikut:
{{- if .Values.ingress.enabled }}
  echo "Akses aplikasi di: https://{{ .Values.ingress.host }}"
{{- else }}
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "myapp.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
  echo "Akses aplikasi di: http://127.0.0.1:8080"
  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:80
{{- end }}
 
2. Password default tersimpan di Secret "{{ include "myapp.fullname" . }}-admin":
   kubectl get secret --namespace {{ .Release.Namespace }} {{ include "myapp.fullname" . }}-admin \
     -o jsonpath="{.data.admin-password}" | base64 -d

Perhatikan bagaimana {{- if .Values.ingress.enabled }} dan {{- end }} membuat output berbeda tergantung konfigurasi. Jika Ingress aktif, pengguna diarahkan ke hostname yang sudah disetel; jika tidak, mereka diberi perintah port-forward yang siap salin-tempel. Ini pola yang sama dengan conditional rendering di template resource biasa (episode 10) — hanya saja outputnya untuk manusia, bukan untuk API server.

Satu hal lagi: NOTE.txt (tanpa S) — file templates/NOTES.txt dengan ekstensi .txt — di-render sebagai template. Tetapi templates/NOTES.txt memang memakai nama khusus; jangan menamainya notes.md atau notes.yaml, karena Helm mengenali pola ini secara spesifik.

#Mendokumentasikan Values dengan Disiplin

Di episode 7 kita belajar bahwa values.yaml adalah antarmuka utama chart. Di episode ini kita serius mengurus dokumentasinya, karena dokumentasi values adalah dokumentasi API — dan API tanpa dokumentasi adalah undangan untuk salah pakai.

Disiplin pertama: komentar inline di values.yaml. Setiap key yang non-trivial layak mendapat komentar yang menjelaskan apa fungsinya, bukan apa tipe datanya (itu sudah jelas dari nilainya). Bandingkan dua gaya berikut:

replicaCount: 3
image:
  repository: nginx
  tag: "1.27.3"
resources:
  requests:
    memory: 256Mi

# Jumlah replika yang dijalankan untuk service utama.
# Naikkan saat beban puncak; turunkan saat di luar jam sibuk.
replicaCount: 3
 
image:
  # Repositori image; gunakan tag immutable di produksi.
  repository: nginx
  # Jangan gunakan tag "latest" - sulit di-rollback.
  tag: "1.27.3"
 
resources:
  # Requests penting untuk penjadwalan pod dan HPA.
  requests:
    memory: 256Mi

Perbedaan di atas bukan kosmetik. Komentar pertama menjelaskan mengapa nilai default dipilih — itu mencegah orang lain mengubahnya tanpa konteks. Komentar tentang tag latest mencegah salah satu kesalahan produksi paling umum. Prinsipnya: komentar menjawab "kenapa", bukan "apa".

Disiplin kedua: jelaskan default values. Pengguna chart membaca tabel parameter untuk memutuskan apakah perlu mengubah sesuatu. Jika kalian hanya menulis replicaCount | int | 3, pengguna tidak tahu apakah 3 itu angka yang disarankan atau sekadar default serampangan. Tambahkan kalimat konteks: "3 replika cocok untuk HA dengan minimal 1; mulai dari 2 di environment kecil."

Disiplin ketiga: contoh penggunaan. Untuk parameter yang kompleks — misalnya ingress.annotations atau extraEnv — sertakan contoh snippet di README atau komentar. Contoh konkret jauh lebih mudah dipahami daripada deskripsi abstrak. Dan disiplin terakhir: konsistensi penamaan dan struktur, sehingga pengguna yang sudah akrab dengan chart lain bisa menebak lokasi key dengan akurat.

#helm-docs — Generasi Dokumentasi Otomatis

Di sinilah masalah "dokumentasi basi" diselesaikan. helm-docs (github.com/norwoodj/helm-docs) adalah tool yang membaca values.yaml kalian dan men-generate bagian tabel parameter di README secara otomatis. Ia bekerja lewat template bernama README.md.gotmpl — template Go tempat kalian menulis bagian README yang statis, lalu menyisipkan placeholder untuk bagian yang digenerate dari values.

Cara kerjanya sederhana: helm-docs mem-parsing values.yaml, mengekstrak setiap key beserta tipe dan default-nya, lalu merender placeholder seperti {{ template "chart.valuesTable" . }} menjadi tabel Markdown yang rapi. Karena tabelnya digenerate dari sumber yang sama dengan yang dipakai Helm saat runtime, tidak mungkin lagi ada key yang lupa didokumentasikan — selama values.yaml berubah, tabel ikut berubah.

Contoh README.md.gotmpl dan hasil render-nya:

::: code-group

# myapp
 
Deployment production-grade untuk aplikasi `myapp` di atas Kubernetes.
 
## Prasyarat
 
- Kubernetes >= 1.26
- Helm >= 3.12
- Ingress Controller (jika mengaktifkan `ingress.enabled`)
 
## Instalasi
 
```shell
helm repo add myorg https://charts.myorg.example.com
helm install myapp myorg/myapp --namespace myapp --create-namespace
```
 
## Parameter
 
| Parameter | Deskripsi | Default |
|-----------|-----------|---------|
{{ template "chart.valuesTable" . }}
 
## Uninstall
 
```shell
helm uninstall myapp --namespace myapp
```

## Parameter
 
| Parameter | Deskripsi | Default |
|-----------|-----------|---------|
| replicaCount | Jumlah replika service utama | 3 |
| image.repository | Repositori image aplikasi | nginx |
| image.tag | Tag image (hindari latest) | 1.27.3 |
| image.pullPolicy | Kebijakan pull image | IfNotPresent |
| service.type | Tipe Service Kubernetes | ClusterIP |
| service.port | Port yang diekspos Service | 80 |
| ingress.enabled | Aktifkan Ingress resource | false |
| ingress.host | Hostname untuk Ingress | myapp.example.com |
| autoscaling.enabled | Aktifkan HPA | false |
| autoscaling.minReplicas | Minimum replika HPA | 1 |
| autoscaling.maxReplicas | Maksimum replika HPA | 5 |
| resources.limits.memory | Batas maksimum memori pod | 512Mi |
| resources.requests.cpu | Request CPU per pod | 100m |
:::
 
Perhatikan bahwa kalian **tidak menulis tabelnya sendiri** — hanya menulis placeholder `{{ template "chart.valuesTable" . }}`. Untuk menghasilkan README final:
 
```bash icon="iHelm" title="Menjalankan helm-docs"
helm-docs --chart-search-root ./charts

Perintah di atas membaca README.md.gotmpl dan values.yaml di setiap chart di bawah ./charts, lalu menulis README.md final. Integrasi ke CI dilakukan dengan cara yang sama — cukup jalankan helm-docs, lalu jika ada perubahan (cek dengan git diff --exit-code), gagalkan pipeline karena artinya dokumentasi belum digenerate ulang. Dengan begitu, dokumentasi terpaksa sinkron sebelum kode bisa di-merge.

helm-docs juga mendukung konfigurasi via file helm-docs.yaml untuk mengatur opsi seperti sortValuesOrder, templatesLocation, atau file output kustom. Dan karena tabel dihasilkan dari values.yaml, disiplin menulis komentar inline yang kita bahas sebelumnya menjadi ganda penting: komentar di values.yaml kini ikut tampil sebagai kolom "Deskripsi" di tabel README. Dokumentasi values dan README menjadi satu alur, bukan dua hal terpisah.

#CHANGELOG.md — Riwayat yang Membangun Kepercayaan

Dokumentasi yang terakhir justru paling sering diabaikan: CHANGELOG.md. Ia adalah catatan perjalanan setiap versi chart — apa yang berubah, fitur apa yang baru, bug apa yang diperbaiki, dan yang terpenting: perubahan apa yang mematahkan (breaking changes). Mengapa ini krusial? Karena pengguna chart tidak pernah melakukan upgrade dengan ringan. Setiap kenaikan versi adalah risiko; CHANGELOG adalah cara kalian menurunkan risiko itu dengan transparansi.

Struktur CHANGELOG yang baik mengikuti pola "Keep a Changelog": versi terbaru di paling atas, setiap versi diberi tanggal, dan perubahan dikelompokkan per kategori — Added, Changed, Removed, Fixed. Yang membedakan CHANGELOG chart production-grade dari sekadar catatan adalah seksi migrasi untuk setiap versi yang mengandung breaking changes. Contoh nyata:

# Changelog
 
Semua perubahan penting pada chart ini akan dicatat di file ini.
Format mengikuti "Keep a Changelog", versi mengikuti Semantic Versioning.
 
## [2.0.0] - 2026-08-02
 
### Added
- Dukungan Horizontal Pod Autoscaler (`autoscaling.enabled`).
- Konfigurasi `securityContext` per-pod untuk podSecurityContext dan kontainer.
 
### Changed
- **Breaking**: struktur `service.annotations` dipindah menjadi `service.annotationsPod`.
  Migrasi: pindahkan anotasi pod dari `service.annotations` ke `service.annotationsPod`.
- Default `image.tag` berubah dari `1.25` menjadi `1.27.3`.
 
### Removed
- Parameter `replicas` (digantikan `replicaCount`, sudah deprecated sejak 1.4).
 
## [1.4.0] - 2026-05-10
 
### Added
- Parameter `nodeSelector` dan `tolerations`.
- Label tambahan `app.kubernetes.io/version` pada Deployment.
 
### Fixed
- Volume mount yang salah pada container init saat `extraVolumes` dipakai.

Perhatikan entri [2.0.0]: ini versi MAJOR (naik dari 1.x ke 2.0.0), dan setiap perubahan yang mematahkan diberi label **Breaking** dengan instruksi migrasi. Inilah yang membuat pengguna berani upgrade: mereka tahu persis apa yang harus disesuaikan, tanpa harus membaca diff seluruh template. Sebaliknya, CHANGELOG yang tidak pernah diupdate membuat pengguna menunda upgrade — dan menunda upgrade sama dengan menumpuk utang keamanan dan fitur.

Jika kalian sudah memakai semantic-release (seperti yang kita bahas di konteks CI), CHANGELOG bisa digenerate dari conventional commits dengan tool seperti standard-version atau plugin semantic-release/changelog. Tapi apapun toolnya, prinsipnya tetap: setiap rilis harus punya entri yang jujur, terutama tentang breaking changes.

#Penutup

Pada episode 15 ini kita telah membangun fondasi dokumentasi chart yang production-grade. Kita memulai dari README.md sebagai kontrak antar tim — deskripsi, prasyarat, instruksi instalasi, tabel parameter, contoh, upgrade notes, dan uninstallation — lalu NOTES.txt sebagai asisten pasca-instalasi yang mendukung templating dan conditional rendering sehingga instruksi akses selalu relevan. Kita mendisiplinkan dokumentasi values dengan komentar yang menjelaskan "kenapa", membebaskan diri dari dokumentasi basi dengan helm-docs yang men-generate tabel parameter langsung dari values.yaml, dan menutup dengan CHANGELOG.md yang menurunkan risiko upgrade lewat transparansi dan panduan migrasi.

Inti yang harus kalian bawa:

• README.md adalah kontrak pengguna; dokumentasi yang basi lebih berbahaya daripada tidak ada.
• NOTES.txt adalah template Go yang dieksekusi setelah install/upgrade — manfaatkan conditional rendering untuk instruksi yang kontekstual.
• Dokumentasi values = dokumentasi API: komentar menjawab kenapa, bukan apa.
• helm-docs membuat tabel parameter mustahil basi, selama dijalankan di CI dan digagalkan saat ada drift.
• CHANGELOG.md + semver yang disiplin = pengguna berani upgrade.

Sekarang chart kalian tidak hanya berfungsi, tapi juga bisa dipakai orang lain dengan percaya diri. Di episode 16 selanjutnya kita akan membedah chart packaging dan versioning: bagaimana Semantic Versioning yang benar, perbedaan version vs appVersion, helm package menjadi arsip .tgz, penandatanganan dan verifikasi provenance dengan GPG, hingga Chart.lock yang menjamin reproducibility. Pastikan tetap semangat!