Validator YAML

Mengapa YAML lebih sulit dari kelihatannya

Daya tarik YAML adalah dokumen sederhana hampir tidak memerlukan sintaks. Harganya, parser harus menebak banyak hal, dan sebagian besar masalah YAML muncul karena parser menebak sesuatu yang berbeda dari maksud Anda.

Indentasi adalah struktur, dan harus berupa spasi - tab tidak pernah diizinkan, itulah sebabnya editor yang disetel untuk menyisipkan tab menghasilkan error yang tampak tanpa sebab. Indentasi juga bersifat relatif, bukan tetap, jadi blok yang diindentasi empat spasi berdampingan dengan saudara yang diindentasi dua spasi adalah error sungguhan, bukan sekadar gaya yang tidak konsisten.

Selain itu, data yang sama bisa ditulis dengan beberapa cara: gaya blok dan gaya flow, skalar dengan dan tanpa tanda kutip, tiga cara menulis null. Semua ini tidak jadi masalah sampai sebuah nilai jatuh ke celah di antaranya, dan saat itu masalahnya besar.

Jebakan tipe data implisit

Skalar tanpa tanda kutip diberi tipe berdasarkan bentuknya, dan bentuk-bentuk itu tumpang tindih dengan hal-hal yang biasa ditulis orang sebagai string.

Nomor versi adalah contoh klasiknya. 1.10 tanpa tanda kutip adalah float, dan float tidak menyimpan nol di belakang, sehingga menjadi 1.1 dan versi dependensi yang Anda kunci diam-diam menunjuk ke versi lain. Nilai yang diawali nol punya masalah sebaliknya: di YAML 1.2, 0755 adalah angka 755, bukan mode file oktal, dan Anda harus menulis 0o755. Deretan angka panjang - nomor telepon, nomor rekening, ID - kehilangan nol di depan dan, di atas enam belas digit, kehilangan presisi.

Boolean adalah yang paling terkenal. YAML 1.1 memperlakukan yes, no, on, off, y, dan n sebagai boolean, dan dari sinilah "masalah Norwegia" berasal: daftar negara yang berisi NO berubah menjadi daftar yang berisi false. YAML 1.2 core mempersempitnya menjadi hanya true dan false, dan alat ini mengikuti aturan tersebut, tetapi banyak perangkat lunak masih memakai parser 1.1 - di antaranya Psych milik Ruby dan PyYAML versi lama - jadi kebiasaan yang aman adalah memberi tanda kutip pada semua nilai yang dimaksudkan sebagai string.

Yang juga perlu diketahui: null bisa ditulis null, ~, atau tidak ditulis sama sekali, jadi kunci dengan nilai kosong adalah null, bukan string kosong. Dan di YAML 1.1, 22:22 diurai sebagai angka seksagesimal, bukan waktu.

String multibaris

Dua indikator skalar blok mencakup hampir semua kasus, dan salah memilih adalah penyebab umum konfigurasi yang rusak.

Tanda pipa (|) mempertahankan baris baru persis seperti yang ditulis. Gunakan ini untuk skrip shell, sertifikat, file konfigurasi yang disematkan, atau apa pun yang struktur barisnya bermakna. Tanda lebih besar (>) justru melipat: baris baru tunggal menjadi spasi dan baris kosong menjadi baris baru, cocok untuk paragraf panjang yang ingin dipotong di kode sumber tanpa terpotong di nilainya.

Keduanya bisa diberi indikator chomping yang mengatur baris baru di akhir. Tanpa indikator, tepat satu dipertahankan; tanda minus (-) menghapus semuanya; tanda plus (+) mempertahankan semuanya. Minus penting ketika baris baru di akhir akan merusak penerima nilai - token, kunci, argumen - dan plus ketika spasi harus dipertahankan persis.

Isi diindentasi relatif terhadap kunci, dan indentasi itu dihapus dari nilainya. Baris yang diindentasi lebih dalam dari baris lain tetap menyimpan spasi tambahannya, sehingga skrip di dalam manifest tetap mempertahankan strukturnya sendiri.

Anchor, alias, dan merge key

Anchor menandai sebuah node dengan &, dan alias merujuknya dengan *, sehingga dokumen bisa memakai ulang nilai yang sudah didefinisikan sebelumnya. Di konfigurasi CI atau file compose, inilah yang menghilangkan pengulangan antara job atau layanan yang hampir sama, dan ini salah satu alasan yang benar-benar bagus untuk menulis YAML alih-alih JSON.

Merge key, yang ditulis <<: *base, melangkah lebih jauh dengan menggabungkan kunci-kunci dari mapping yang diberi anchor ke mapping saat ini sehingga Anda bisa menimpa beberapa di antaranya. Perlu diketahui bahwa ini bukan bagian dari YAML 1.2 core - ini spesifikasi terpisah yang diimplementasikan sebagian besar parser, tetapi tidak semuanya, jadi tidak selalu aman.

Semua ini pasti hilang saat dikonversi ke JSON. Alias diuraikan menjadi nilai sebenarnya sebelum konversi, sehingga anchor yang dirujuk tiga kali menjadi tiga salinan data, bukan tiga referensi. Komentar juga hilang, karena JSON tidak punya komentar. Mengonversi konfigurasi yang banyak memakai anchor ke JSON lalu kembali lagi menghasilkan dokumen dengan makna yang sama tetapi jauh lebih panjang; dari sisi keterbacaan, ini perjalanan satu arah.

Tanda kutip: kapan penting dan yang mana dipakai

Skalar tanpa tanda kutip ditentukan tipenya dari bentuknya, jadi memberi tanda kutip adalah cara Anda mengatakan bahwa ini teks. Isi kutip tunggal bersifat harfiah, kecuali dua kutip tunggal berurutan yang berarti satu apostrof: tidak ada escape yang diproses, sehingga 'C:\path\to' persis sama dengan string itu. Kutip ganda memproses escape, sehingga \n menjadi baris baru dan garis miring terbalik harfiah harus ditulis dua kali.

Aturan yang menghindarkan Anda dari sebagian besar masalah: pakai kutip tunggal sebagai kebiasaan, kutip ganda hanya bila Anda butuh escape sequence, dan beri tanda kutip pada apa pun yang bisa terbaca sebagai tipe lain. Itu mencakup nomor versi, nilai yang isinya hanya angka, apa pun yang diawali nol, serta kata yes, no, on, dan off.

Ada beberapa karakter yang memaksa penggunaan tanda kutip di mana pun ia muncul dalam sebuah nilai: titik dua yang diikuti spasi, tanda pagar yang didahului spasi, serta &, *, !, %, @ atau backtick di awal. Nilai yang diawali kurung kurawal atau kurung siku memulai gaya flow, jadi template Jinja atau Helm seperti {{ .Values.name }} harus diberi tanda kutip, kalau tidak parser akan membacanya sebagai mapping bersarang.

Kesalahan yang merusak berkas Kubernetes dan CI

Yang pertama adalah indentasi item daftar. Sebuah sequence di bawah sebuah key boleh diindentasi atau disejajarkan dengan key-nya, keduanya sah, tetapi item-item dalam satu sequence harus konsisten satu sama lain. Mencampur keduanya di dalam berkas yang sudah disunting beberapa orang menghasilkan error yang nomor barisnya sering menunjuk ke tempat yang sama sekali berbeda.

Yang kedua adalah berkas multi-dokumen. Tiga tanda hubung memisahkan dokumen, dan perkakas yang hanya membaca dokumen pertama akan diam-diam mengabaikan semua yang ada setelah pemisah itu - begitulah sebuah manifest Kubernetes menerapkan Deployment tetapi tidak Service. kubectl menangani banyak dokumen; banyak skrip yang memakai fungsi load bawaan sebuah bahasa tidak bisa, dan perlu varian load-all.

Yang ketiga adalah nilai kosong. Key yang tidak diikuti apa pun setelah titik dua bernilai null, bukan string kosong dan bukan map kosong, sehingga blok konfigurasi yang dikomentari tetapi key-nya dibiarkan tetap ada akan terbaca sebagai null di tempat yang oleh pemakainya diharapkan berisi objek. Null dan string kosong berperilaku berbeda di setiap sistem templating yang dibangun di atas YAML.

Memvalidasi YAML dengan skema

Parser memberi tahu Anda bahwa berkasnya benar secara sintaks. Skema memberi tahu Anda bahwa isinya masuk akal, dan untuk apa pun yang bersifat operasional, itulah pemeriksaan yang lebih berguna. Karena YAML dipetakan ke model data yang sama dengan JSON, JSON Schema bisa langsung dipakai di atasnya, dan itulah yang dipakai kebanyakan editor untuk memberi pelengkapan otomatis serta penanda error langsung pada manifest Kubernetes atau berkas GitHub Actions.

Di dalam pipeline, validator khusus melangkah lebih jauh daripada skema generik: kubeconform memeriksa manifest terhadap skema Kubernetes API untuk versi yang dituju, yamllint menegakkan gaya penulisan dan menangkap masalah indentasi serta key ganda, dan sebagian besar sistem CI menyediakan cara memvalidasi berkas konfigurasinya sendiri secara lokal sebelum Anda melakukan push.

Key ganda layak disebut tersendiri. Kebanyakan parser menerimanya lalu menyimpan yang terakhir dan membuang yang pertama tanpa peringatan - sehingga nilai yang diset dua kali di dalam berkas panjang tampak seperti diabaikan. Linter akan menandainya; runtime bahasanya biasanya tidak.

Templating di atas YAML, dan mengapa itu menyakitkan

Helm, Ansible, dan sebagian besar sistem CI menghasilkan YAML dari template, artinya sebuah bahasa templating teks dipakai untuk memproduksi format yang sensitif terhadap spasi. Hasilnya bisa ditebak: nilai yang disisipkan pada indentasi yang salah, string multi-baris yang memipihkan sebuah blok, atau kondisional yang menghapus satu baris dan meninggalkan key yang menggantung.

Ada dua kebiasaan yang mengurangi penderitaan. Render dulu sebelum apply - helm template, atau dry run yang setara - lalu baca keluarannya sebagai YAML alih-alih memercayai template-nya. Dan gunakan helper indentasi yang disediakan perkakasnya, seperti nindent di Helm, alih-alih menghitung spasi sendiri di dalam template.

Alternatif yang lebih mendasar adalah menghasilkan YAML dari data, bukan dari teks: bangun strukturnya dalam bahasa pemrograman sungguhan lalu serialisasikan, sehingga indentasi menjadi urusan serializer. Untuk itulah CDK8s, Pulumi, dan beberapa bahasa konfigurasi seperti CUE dan Dhall ada, dan pendekatan ini menghapus satu kategori kegagalan secara utuh.

Rahasia, komentar, dan apa yang bertahan setelah konversi

Berkas konfigurasi YAML adalah tempat rahasia paling sering berakhir di dalam repositori, biasanya berupa nilai yang niatnya mau dihapus seseorang sebelum di-commit. Menjaganya agar tidak masuk adalah keputusan alur kerja - variabel lingkungan, secret manager, atau berkas terenkripsi dengan SOPS maupun sealed secrets - dan memindai repositori sekali untuk melihat apa yang sudah terlanjur ada di sana layak dilakukan, sambil mengingat bahwa riwayat menyimpan apa pun yang pernah di-commit.

Komentar adalah hal lain yang layak dilindungi. Bagi banyak berkas konfigurasi, komentar adalah satu-satunya dokumentasi yang ada, dan komentar tidak bertahan saat dikonversi ke JSON, atau saat berkas melewati program yang memuat lalu menyerialkan ulang isinya. Ada perkakas yang menyunting YAML di tempat sambil mempertahankan komentar - ruamel.yaml di Python, dan yq untuk penyuntingan lewat baris perintah - dan itulah pilihan yang tepat untuk perubahan terotomasi pada berkas yang dipelihara manusia.

Hal yang sama berlaku untuk anchor. Konversi ke JSON mengembangkan setiap alias menjadi salinan, sehingga konfigurasi yang dibangun di sekitar blok bersama akan kembali dalam bentuk yang jauh lebih panjang dan kehilangan struktur yang membuatnya mudah dipelihara. Bagi mesin artinya sama saja, bagi orang berikutnya yang menyuntingnya artinya jauh berkurang.