Kapan menggunakan langkah pipeline
Sebuah FeatureRecipe memberi Anda dua cara untuk membentuk output yang dikontribusikan sebuah Feature: FeatureRecipe bertemplat yang menghasilkan dokumennya sendiri, dan langkah pipeline (pipeline:) yang menjalankan plugin Wasm atas output yang telah dirender. Keduanya menyelesaikan masalah yang berbeda. Halaman ini adalah panduan keputusan: gunakan langkah pipeline tepat pada dua pemicu, dan gunakan FeatureRecipe bertemplat untuk semua hal lainnya.
Dua alat
FeatureRecipe bertemplat bersifat lokal dan generatif. Ia menghasilkan dokumennya sendiri dari nilai-nilainya sendiri melalui template Go — ConfigMap untuk sidecar, CRD kebijakan, objek autoscaler. Semua yang dikeluarkannya merupakan fungsi dari values: dan infra: milik Feature serta konteks render yang diberikan kepada template-templatenya. Ia tidak pernah menjangkau output entitas lain; ia menambahkan dokumennya sendiri. Jika hal yang perlu Anda hasilkan dapat ditulis dari apa yang sudah diketahui Feature, FeatureRecipe bertemplat adalah alat yang tepat dan lebih sederhana — tanpa plugin, tanpa pipeline.
Langkah pipeline bersifat global dan transformatif. Ia berjalan setelah render, atas kumpulan dokumen nyata yang telah dikeluarkan oleh build. Host menyerahkan kumpulan dokumen berkunci itu secara utuh kepada langkah tersebut; langkah membaca konten yang sebenarnya, memilih dokumen yang ditargetkannya, dan mengembalikan patch RFC 6902 yang presisi terhadap strukturnya — atau mengeluarkan dokumen baru sebagai efek samping. Sebuah langkah menalar tentang apa yang telah dirender, bukan hanya tentang apa yang dideklarasikan Feature. Jangkauan itulah satu-satunya alasan keberadaannya, dan itu pula alasan Anda menggunakannya secara hemat.
Dua pemicu untuk langkah pipeline
Gunakan langkah pipeline hanya jika salah satu dari kondisi berikut terpenuhi. Jika tidak ada yang terpenuhi, hasilkan dokumen dengan FeatureRecipe bertemplat sebagai gantinya.
-
Patch lingkup host — Anda perlu menjangkau struktur entitas lain yang sudah dirender. Kasus klasiknya adalah menyisipkan variabel env, volume mount, atau kontainer sidecar ke workload komponen yang mengonsumsi — dokumen yang tidak ditulis oleh Feature itu sendiri. FeatureRecipe bertemplat tidak dapat melakukan ini: ia menghasilkan dokumennya sendiri, ia tidak menyunting dokumen milik pihak lain. Langkah pipeline dapat melakukannya, karena ia beroperasi pada kumpulan yang telah dirender dan dapat merujuk dokumen komponen host berdasarkan kunci.
-
Emit atau patch yang bergantung pada konten — output bergantung pada apa yang terkandung dalam kumpulan yang dirender. Ketika resource yang Anda keluarkan, atau patch yang Anda terapkan, merupakan fungsi dari konten yang dihasilkan build — port sebenarnya yang dideklarasikan sebuah Deployment, nama-nama kontainer yang akhirnya ada di manifest, resource hasil ekspansi sebuah chart — keputusan tersebut memerlukan konten yang telah dirender. FeatureRecipe bertemplat merender dari nilai-nilai Feature sendiri dan tidak pernah melihat kumpulan yang sudah jadi, sehingga tidak dapat membuat pilihan yang bergantung pada konten; langkah pipeline membaca konten terlebih dahulu, lalu bertindak.
Kedua pemicu memiliki bentuk yang sama: keduanya memerlukan informasi yang hanya ada setelah render — struktur entitas lain, atau konten yang dikeluarkan itu sendiri. Pembuatan lokal tidak pernah memerlukannya, sehingga pembuatan lokal tidak pernah memerlukan langkah pipeline.
Langkah mentransformasi; kebijakan memvalidasi
Langkah pipeline adalah transformer: ia mengubah kumpulan yang telah dirender. Ia bukan tempat untuk memeriksa apakah suatu hasil dapat diterima. Untuk memvalidasi sebuah build — untuk memastikan bahwa workload yang di-patch memiliki sidecar, bahwa tidak ada secret plaintext yang sampai ke output, bahwa label yang diwajibkan ada — lampirkan kebijakan tahap render: plugin tata kelola pada peran render-verdict, yang berjalan setelah render atas artefak yang dikeluarkan dan mengembalikan verdict. Verdict halt menghentikan build; verdict warn atau info memberi saran tanpa memblokir.
Pisahkan keduanya. Jangan membangun logika validasi ke dalam langkah pipeline, dan jangan menggunakan kebijakan untuk mengubah output — plugin tata kelola yang dilampirkan pada peran verdict mengembalikan verdict dan tidak pernah melakukan patch, dan host membaca output peran verdict hanya sebagai keputusan. Langkah membentuk output; kebijakan render-verdict menilainya. Halaman soket tata kelola membahas keempat peran tata kelola dan tingkat keparahan verdict.
Langkah dapat dikomposisikan
Langkah pipeline dapat mendeklarasikan kontrak input dan output bertipe, sehingga input with: dan output yang dikembalikannya merupakan bentuk tervalidasi, bukan blob bebas. Sebuah langkah juga mengembalikan outputs bernama, dan langkah yang dideklarasikan kemudian dalam pipeline yang sama membaca output langkah sebelumnya dari template with: miliknya sebagai .steps.<id>.outputs.<key>. Begitulah pola dua bagian dikomposisikan tanpa keterikatan: langkah Fetcher mengeluarkan resource kredensial dan memublikasikan nama Secret yang dihasilkan sebagai output; langkah Injector membaca nama itu dan mem-patch workload yang mengonsumsi agar me-mount-nya. Setiap langkah membawa satu urusan, dan pipeline merangkai output-output mereka sesuai urutan deklarasi.
Rujukan silang
entities/featurerecipe.md— antarmuka penulisan FeatureRecipe, termasukpipeline:.plugins/plugin-contract.md— bentuk wire langkah pipeline: kumpulan dokumen berkunci sebagai masukan, serta patch RFC 6902, efek samping, diagnostik, dan output langkah sebagai keluaran.plugins/policy-socket.md— soket tata kelola, termasuk peran verdict tahap render yang memvalidasi output sebuah build.templates/template-context-contract.md— field.steps.<id>.outputsyang dibaca oleh langkah berikutnya.examples/04-secrets.md— bentuk pipeline Fetcher + Injector.