YAML di Kubernetes: 12 Kesalahan Konfigurasi yang Meruntuhkan Deploy Jam 2 Pagi

YAML terasa ramah sampai kesalahan indent dua spasi meruntuhkan produksi. Kubernetes menjadikan YAML wajah default infrastruktur—artinya setiap insinyur menyunting format sensitif whitespace di bawah tekanan, sering menempel dari Stack Overflow, ChatGPT, atau template Helm dengan karakter tak terlihat.

Artikel ini mengatalog dua belas kesalahan yang lolos review kode, menjelaskan bagaimana API Kubernetes sesungguhnya mem-parse manifest, serta cara mengonversi dan memeriksa YAML secara lokal di Safe Local Tools sebelum kubectl apply mengirimnya ke klaster.

Manifest adalah kode eksekusi yang akan dijalankan otomatis—perlakukan whitespace dan tipe sama seriusnya dengan bug logika aplikasi.

YAML adalah antarmuka manusia bukan bahasa yang memaafkan

YAML 1.2 mengizinkan banyak bentuk skalar—quoted, unquoted, literal blok—yang JSON tidak punya.

Fleksibilitas itu membantu prosa tetapi menyakiti mesin: yes/no bisa menjadi boolean pada beberapa parser; 0123 pernah ditafsirkan oktal pada mesin lama; tab dalam indent struktural melanggar aturan.

Kubernetes mengonversi YAML ke JSON di server—YAML valid tetapi pemetaan tipe JSON tak terduga menghasilkan perilaku runtime halus, bukan error sintaks langsung.

Kesalahan 1 — Tab menggantikan spasi

YAML melarang tab untuk indent struktural.

Gejala: karakter tidak bisa memulai token pada baris yang tampak benar.

Perbaikan: editor "indent using spaces", .editorconfig, hook pra‑komit yang menolak \t dalam *.yaml.

Kesalahan 2 — Kedalaman indent tidak konsisten

Daftar Kubernetes memakai -; saudara kunci harus sejajar.

Spasi ekstra di bawah containers: bisa menyarangkan bidang di bawah orang tua salah.

Gejala: env hilang atau probe menempel pada objek lain.

Kesalahan 3 — String tak kutip menjadi boolean atau null

value: off bisa menjadi false pada beberapa jalur parsing.

Perbaikan: kutip skalar ambigu seperti "off".

env:
  - name: DEBUG
    value: off   # bisa menjadi false

Kesalahan 4 — Skrip multi‑baris tanpa block scalar

Menempel skrip dengan banyak : pada args: bisa membingungkan parser.

Gunakan | atau > dengan kutipan tambahan di mana diperlukan.

Kesalahan 5 — Kunci duplikat (pemenang terakhir tanpa peringatan)

Beberapa loader YAML mengizinkan duplikasi; yang terakhir menang tanpa alarm.

Konversi ketat JSON membantu menyoroti struktur yang tidak Anda maksud.

Kesalahan 6 — Salin Helm tanpa render

Placeholder {{ .Values.foo }} bukan objek Kubernetes sampai templating di-render.

Gunakan helm template atau kubectl apply --dry-run=server di CI.

Kesalahan 7 — Pasangan apiVersion/kind salah

YAML valid bisa mendeskripsikan sumber daya yang tidak dikenali klaster Anda.

Pelihara matriks versi per klaster.

Kesalahan 8 — Mega‑manifest tanpa pemisahan

Satu berkas ribuan baris mengundang drift indent tidak sengaja.

Gunakan overlay Kustomize atau pisahkan Deployment, Service, Ingress.

Kesalahan 9 — Secret YAML polos di git

Meskipun "berhasil", itu tiket ke insiden ketika pemindai menemukan token.

Gunakan Sealed Secrets, SOPS, atau operator rahasia eksternal.

Kesalahan 10 — Kesalahpahaman pemisah dokumen ---

Beberapa dokumen dalam satu berkas kuat tetapi pemisah hilang bisa menggabungkan objek tidak terkait.

Gunakan --- eksplisit dengan disiplin.

Kesalahan 11 — Quantity sumber daya sebagai float

Kubernetes mengharapkan string seperti 500m CPU dan 512Mi memori.

Float bisa menyebabkan penjadwal mengabaikan limit atau menerapkan default tak terduga.

Kesalahan 12 — Mengira JSON mengerti anchor YAML

Anchor (&id) dan alias (*id) tidak ada di JSON.

Prefer duplikasi eksplisit pada manifest yang dikomit kecuali templating lokal Anda yang mengexpand anchor.

Mengapa YAML → JSON membantu debugging

JSON lebih ketat: tanpa komentar (murni), lebih sedikit koersi skalar ambigu, kesalahan duplikasi lebih terlihat pada banyak toolchain.

Safe Local Tools mengonversi YAML dan JSON di browser ketika Anda tidak bisa menempel manifest internal ke formatter cloud.

Alur kerja lokal sebelum apply

Format dan lint YAML di CI.

Konversi ke JSON untuk verifikasi struktur mental atau otomatis.

kubectl apply --dry-run=server -f manifest.yaml

Canary rollout; awasi event untuk penolakan field.

Helm, Kustomize, dan CRD operator

Custom Resource punya OpenAPI schema sendiri—bidang valid pada Deployment bisa tidak valid pada CRD Anda.

Gunakan validasi klien ketika tersedia; jika tidak, dry‑run server tetap penting.

Kebiasaan tinjauan keamanan

Perlakukan manifest seperti kode: komit bertanda tangan, review wajib.

Pindai hostPath, privileged: true, wildcard RBAC berlebihan.

Sematkan image dengan digest di produksi, bukan hanya tag yang bisa bergerak.

Ketika LLM menulis YAML Anda

Model bahasa mengindent secara tidak konsisten dan kadang menghalusinasikan apiVersion.

Jalankan pemeriksaan mekanis yang sama seperti untuk kontributor manusia.

Contoh tugas CI minimal

Lint YAML dan validasi terhadap schema Kubernetes untuk versi klaster target sebagai pintu gesek untuk PR.

yamllint -c .yamllint manifest/
kubeconform -kubernetes-version 1.29.0 -summary manifest/

Patch Kustomize dan gotcha strategic merge

Patch strategis bisa menghapus bidang secara tidak terduga ketika penanda $patch: delete muncul.

Render kustomize build ke berkas temp lalu konversi JSON untuk melihat objek efektif.

NetworkPolicy dan Ingress rumit secara struktural

Selector label mudah salah indentasi di bawah spec.

TLS Ingress mereferensikan Secret dengan nama—typo bisa menyebabkan controller menyajikan sertifikat default tanpa fanfare error pada aplikasi Anda.

Quota dan limits pada pod multi‑kontainer

Menempatkan resources pada kontainer yang salah bisa menguras sidecar atau meninggalkan aplikasi utama tak terbatas secara tidak sengaja.

Tampilan JSON membantu melihat struktur bersarang mana yang Anda edit.

Error YAML jarang mistis; itu whitespace dan tipe yang diprediksi dan diperbesar oleh model JSON ketat Kubernetes.

Sebelum Anda menempel manifest lain ke klaster, konversi dan periksa secara lokal—Coba Konverter YAML ↔ JSON →