Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Soket tata kelola

Seluruh soket, bukan hanya satu perannya: keempat peran — dua yang menilai build, dua yang membentuknya — kedua mesin kebijakan yang disertakan dalam compiler, dan cara operator memasang plugin.

Operator memasang plugin tata kelola Wasm untuk memeriksa build dan bertindak berdasarkan apa yang ditemukannya. Host compiler tetap netral terhadap konten dan tanpa opini sendiri: host merutekan payload build ke guest dan bertindak berdasarkan apa yang dikembalikan guest, dan host tidak pernah menafsirkan kebijakan itu sendiri. Seluruh kecerdasan kebijakan domain — bahasa kebijakan, mesinnya, dan aturan-aturannya — berada di dalam guest.

Ini adalah kontrak kemurnian ahead-of-time yang sama yang berlaku untuk setiap soket: guest mengevaluasi payload yang diberikan kepadanya dan mengembalikan hasil yang dikonsumsi host apa adanya (lihat kontrak sandbox). Host tidak mengetahui apa pun tentang bahasa kebijakan yang digunakan guest dan tidak membawa kode mesin kebijakan miliknya sendiri.

Plugin tata kelola dipasang pada tepat satu peran, dan peran itulah — bukan plugin — yang menentukan payload mana yang tiba sekaligus apa yang boleh dilakukan pemasangan tersebut terhadapnya. Dua di antaranya adalah peran verdict: pemasangan menilai build, dan host mengambil tepat satu dari tiga tindakan untuk setiap verdict yang dikembalikannya. Dua lainnya adalah peran transform: pemasangan melaporkan perubahan pada label atau anotasi build, dan host menerapkannya. Plugin yang melayani lebih dari satu peran dipasang satu kali per peran, dan plugin tersebut tidak mendeklarasikan peran sendiri — pemasanganlah yang membawanya.

Halaman ini adalah pembahasan menyeluruh tentang soket tata kelola: keempat peran dan payload yang dibawa masing-masing, tingkat keparahan verdict yang ditindaklanjuti host, kanal input yang agnostik terhadap mesin yang disediakan operator, cara menulis kebijakan untuk salah satu dari dua mesin kebijakan yang disertakan dalam compiler — satu mengevaluasi Rego, satu mengevaluasi CEL — cara guest membungkus mesin kebijakan asing, guest referensi yang disertakan, dan cara operator memasang plugin ke workspace. Untuk posisi soket dalam pipeline dan bentuk wire bertipenya, lihat plugin-contract.md; untuk menulis dan menerbitkan plugin sebagai entitas katalog, lihat panduan pengembang plugin Wasm.

Model mental: host merutekan, guest memutuskan

Pada sebuah build, host menyusun payload untuk peran attachment, menyerahkannya melintasi batas ABI, dan membaca kembali apa yang dikembalikan guest. Pada peran verdict, hasil itu berupa daftar verdict, masing-masing membawa tingkat keparahan dan pesan yang dapat dibaca manusia: host memetakan setiap tingkat keparahan ke sebuah tindakan build, dan host tidak membaca makna pesan tersebut, tidak mengetahui apa yang diperiksa oleh kebijakan, dan tidak mengetahui mesin mana yang menghasilkan keputusan itu. Pada peran transform, hasil itu berupa perubahan yang harus dibuat, yang ditujukan kepada label atau anotasi yang diatur oleh peran tersebut dan tidak kepada yang lain.

Karena host tidak menafsirkan isi kebijakan, seluruh permukaan kebijakan adalah milik guest: dalam bahasa apa aturan ditulis, mesin mana yang mengevaluasinya, dan bagaimana aturan yang terpicu menjadi verdict atau perubahan. Kontrak socket sengaja dibuat sempit — sebuah peran, sekumpulan input, dan sebuah hasil — sehingga teknologi kebijakan apa pun yang dapat dikompilasi ke Wasm dapat melayaninya.

Peran verdict menerima atau menolak dan tidak melakukan hal lain: host membaca outputnya hanya sebagai keputusan dan tidak pernah menerapkannya sebagai perubahan, sehingga sebuah kebijakan tidak dapat diam-diam membuat build yang tidak patuh menjadi patuh. Peran transform adalah pengecualian yang disengaja, dan yang menjadikannya pengecualian adalah bahwa operator yang memasangnya — memasang plugin untuk membentuk label merupakan pernyataan bahwa label memang akan dibentuk. Apa yang dapat diubah oleh attachment semacam itu dibatasi pada permukaan perannya sendiri, dan build berhenti secara tegas pada apa pun di luar permukaan tersebut.

Empat peran

Sebuah plugin dipasang tepat pada satu peran, dan peran tersebut menentukan di titik mana dalam pipeline host mengevaluasinya, payload apa yang diterimanya, dan apa yang boleh dikembalikannya. Plugin yang perlu melayani dua peran dipasang dua kali — sekali per peran.

Peran verdict: ir-verdict dan render-verdict

  • ir-verdict — guest menalar atas graf representasi perantara (intermediate representation), sebelum rendering. Payload memuat graf IR lengkap yang agnostik terhadap kapabilitas (setiap node, edge, dan attachment yang dimiliki compiler) beserta jalur routing yang dienumerasi oleh analyzer, sehingga policy dapat menalar topologi dan keterjangkauan tanpa menelusuri ulang graf. Daftar jalur tersebut dibatasi per node awal — topologi yang terhubung padat atau siklik dapat memuat lebih banyak rute berbeda daripada yang dikeluarkan enumerasi, dan begitu batas tercapai, rute selebihnya dari node awal tersebut tidak dicantumkan. Karena itu, jalur yang ada memang nyata, sedangkan tidak adanya suatu jalur bukan bukti bahwa jalur itu tidak ada: policy yang verdict-nya bergantung pada sesuatu yang tidak terjangkau sebaiknya menetapkannya dari node dan edge, yang dimuat payload secara lengkap, bukan dari daftar jalur saja. Satu hal dalam graf tidak sesuai dengan yang ditulis: setiap nilai yang dideklarasikan penulis sebagai sensitif — dalam values atau infra milik attachment, dalam infra milik attachment boundary, dalam values atau infra milik node itu sendiri, atau dalam values atau infra milik koneksi itu sendiri — tiba sebagai penanda yang ditahan {"aggrega_withheld": "declared"}, sedangkan kuncinya, penanda sensitivitasnya, dan setiap nilai tak terdeklarasi di sebelahnya tiba sesuai yang ditulis. Policy menilai ke mana materi yang dideklarasikan sensitif berpindah dan tidak pernah menerima materi itu; lihat fakta attachment yang dibaca policy tata kelola. Policy ir-verdict dijalankan pada gerbang analisis statis, sebelum artefak apa pun dihasilkan. Gunakan untuk policy tentang arsitektur dan wiring — invarian topologi, autentikasi lintas boundary, bentuk aliran kredensial — yang harus menghentikan build sebelum build me-render apa pun.
  • render-verdict — guest menalar atas output yang telah di-render, setelah rendering. Payload memuat artefak yang dikeluarkan, diurutkan menurut path, sehingga data yang dikirim identik per byte di setiap eksekusi dengan input yang identik. Setiap artefak memuat path output dan teks hasil render-nya; selain itu artefak memuat format tempat ia di-render, bila provider yang menghasilkannya mendeklarasikannya, serta tampilan terstruktur hasil parsing atas kontennya, bila konten berada dalam format yang di-parse sebelum policy. Policy render-verdict melihat persis apa yang dihasilkan build, dan tidak ada yang ditahan di dalamnya: nilai yang di-render sebuah Recipe ke dalam artefak tiba sebagaimana di-render, karena artefak itulah yang dinilai policy. Gunakan untuk policy tentang output konkret — misalnya aturan yang memeriksa service Docker Compose atau objek Kubernetes yang telah di-render.

Peran transform: annotation-transform dan label-transform

  • annotation-transform — guest melaporkan anotasi yang akan ditambahkan, selama resolusi dan sebelum ekspansi anotasi. Payload memuat setiap komponen yang boleh dianotasi oleh attachment, masing-masing dengan anotasi yang sudah dimilikinya, serta kunci anotasi yang binding-nya didaftarkan oleh Manifest. Anotasi yang disisipkan di bawah kunci terdaftar selanjutnya diekspansi menjadi attachment Feature, dan dengan cara itulah peran ini menambahkan ke build kapabilitas yang tidak diketik oleh developer.

    Komponen yang boleh dianotasinya adalah setiap komponen yang disebutkan sebuah boundary di bawah components:, dan setiap komponen yang dirutekan masuk oleh entri routing aggregates: milik boundary. Entri routing menempatkan setiap komponen dari modulnya, termasuk komponen dari modul yang bersarang di dalamnya, baik components: miliknya sendiri menyebutkan semuanya, sebagian, atau tidak satu pun, seperti documents: {} yang tidak menyebutkan satu pun; payload membawa masing-masing. Komponen yang dirutekan dialamatkan dengan id yang dibawanya dalam graf build — nama modul, sebuah titik, dan nama komponen di dalam modul, seperti pada documents.backend, dengan satu nama modul dan titik lagi untuk setiap modul bersarang — yang merupakan cara graf build dan diagnostiknya menuliskannya, sehingga sebuah keputusan juga menyebutkannya dengan cara itu. Komponen yang ditempatkan entri routing tanpa menyebutkannya tidak membawa anotasi sendiri di payload, dan anotasi yang diinjeksikan ke komponen itu diterapkan sebagai anotasi yang ditulis padanya di bawah entri routing.

  • label-transform — guest melaporkan perubahan label yang akan diterapkan, selama konstruksi topologi: setelah graf dibangun, dan sebelum graf dinilai. Payload memuat proyeksi node build — masing-masing dengan Component yang diinstansiasinya, versi yang di-resolve untuknya, label yang saat ini dimilikinya, dan nilai yang dideklarasikan instance-nya, hanya-baca dan dengan setiap nilai yang dideklarasikan sensitif oleh Component-nya ditahan sebagaimana verdict graf menahannya — serta nama dan environment Release. Gunakan untuk metadata turunan yang seharusnya tidak perlu diketik developer (cakupan kepatuhan, kepemilikan, atribusi biaya) dan untuk label kapabilitas yang layak didapat oleh konfigurasi yang dideklarasikan developer.

Peran-peran membawa payload yang berbeda karena bertindak pada saat yang berbeda dan menjawab pertanyaan yang berbeda. Keempatnya membawa kanal masukan yang sama yang disediakan operator, yang dijelaskan di bawah. Untuk melihat payload alih-alih membaca tentangnya, aggrega build --release <release> --policy-input <dir> menuliskan payload yang diserahkan setiap peran kepada plugin yang dilampirkan di sana — termasuk peran yang tidak memiliki lampiran — sebagai satu file JSON per peran, atau per lampiran bila lampiran-lampiran suatu peran menerima payload yang berbeda, dan bila dikombinasikan dengan --dry-run perintah ini menuliskan file-file tersebut dan tidak melakukan apa pun lagi. Pada annotation-transform, label-transform, dan ir-verdict, file tersebut adalah dokumen input yang dibaca kebijakan. Pada render-verdict, mesin kebijakan membentuk ulang payload sebelum kebijakan membacanya — documents setiap artefak di-parse darinya — sehingga kebijakan render-verdict pada mesin di dalam compiler diuji dalam sebuah build, dilampirkan pada warn atau info, sebagaimana ditunjukkan Menguji kebijakan sebelum kebijakan itu menjaga build. Untuk plugin yang .wasm-nya Anda build sendiri, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json menjalankannya pada file tersebut.

Verdict dan tingkat keparahan

Tingkat keparahan di bawah ini adalah kosakata peran verdict. Peran transform melaporkan perubahan, bukan verdict, sehingga tidak membawa tingkat keparahan.

Guest mengembalikan daftar verdict. Setiap verdict membawa tingkat keparahan yang menentukan tindakan build:

  • halt — menghentikan build; host menampilkan pesan verdict sebagai alasannya. Build tidak menghasilkan artefak apa pun.
  • warn — menandai verdict; build tetap berjalan.
  • info — mencatat verdict; hasil build tidak berubah.

Ketiganya adalah keseluruhan himpunan, dan ketiganya sama dengan yang digunakan diagnostik setiap socket lain, sehingga suatu tingkat keparahan bermakna sama di mana pun Anda membacanya.

Verdict yang membawa nilai lain merupakan pelanggaran kontrak, bukan rute keempat. Build berhenti, dan pesannya menyebutkan plugin, nilai yang dibawa verdict, serta tiga nilai yang dideklarasikan kontrak — sehingga tingkat keparahan yang salah eja dilaporkan sebagai error build alih-alih lolos sebagai verdict yang tidak ditindaklanjuti. Guest yang melaporkan dengan salah satu dari ketiganya tidak terpengaruh.

Evaluasi yang mengizinkan tidak mengembalikan apa pun. Guest mengeluarkan verdict hanya ketika suatu aturan terpicu, sehingga daftar verdict yang kosong berarti policy mengizinkan build. Tidak ada verdict “pass” untuk dikeluarkan — diam berarti mengizinkan.

Guest dapat mengembalikan banyak verdict dalam satu evaluasi, dengan tingkat keparahan campuran. Host memproses semuanya: halt mana pun menghentikan build (dan setiap pesan halt ditampilkan), sedangkan verdict warn dan info dilaporkan tanpa memblokir. Hal ini mencerminkan pemisahan antara menghentikan dan menyarankan yang membedakan policy penghenti build dari pemeriksaan lint yang bersifat saran.

Kanal with: sumber dan pengaturan

Guest kebijakan biasanya bersifat generik terhadap aturan spesifik yang ditegakkannya — mesinnya tertanam di dalam guest, tetapi aturannya disediakan per lampiran. Kanal with membawa masukan per lampiran tersebut. Kanal ini memiliki dua bidang yang agnostik terhadap mesin:

  • sources — berkas definisi kebijakan yang dimuat oleh guest. Host membaca setiap berkas yang disebutkan pada waktu build dan meneruskan byte-nya ke guest secara buram: host tidak pernah mengurai sumber, dan path yang diberikannya kepada guest adalah nama dasar berkas, tidak pernah path host absolut. Makna byte tersebut sepenuhnya urusan guest — berkas .rego bagi satu guest, format kebijakan lain bagi guest lain, dan arsip berenkode base64 dari seluruh set kebijakan bagi guest yang membacanya.
  • settings — peta konfigurasi yang dipetakan guest ke mesinnya. Guest membaca parameter penyesuaiannya (batas atas replika, kunci label wajib) dari peta ini. Secara bawaan host meneruskannya apa adanya tanpa menindaklanjutinya; guest juga dapat mendeklarasikan skema untuknya (lihat di bawah), dan dalam hal itu host memvalidasi peta tersebut terhadap skema itu sebelum menjalankan guest.

Guest yang sepenuhnya tertanam — yang aturannya dikompilasi di dalamnya alih-alih disediakan pada waktu pelampiran — sama sekali menghilangkan with. Kanal ini opsional pada setiap peran.

Pengaturan bertipe

Guest dapat mendeklarasikan JSON Schema untuk settings yang diharapkannya. Jika demikian, host memvalidasi settings milik lampiran terhadap skema itu sebelum menjalankan guest. Pengaturan yang tidak sesuai menghentikan build dengan pesan yang menyebutkan kunci yang bermasalah dan apa yang diharapkan skema — kunci wajib yang hilang, nilai dengan tipe yang salah, kunci yang tidak dikenal, atau nilai di luar rentang ditangkap sejak awal alih-alih muncul sebagai kegagalan guest yang sulit dipahami atau, lebih buruk lagi, build yang berhasil tetapi salah.

Pengaturan bertipe bersifat opsional dan dideklarasikan oleh guest, bukan oleh host. Guest yang tidak mendeklarasikan skema pengaturan mempertahankan perilaku bebas bentuk: host meneruskan settings-nya tanpa diperiksa. Host menjalankan validasi JSON Schema biasa terhadap skema apa pun yang dideklarasikan guest; host tidak menafsirkan makna pengaturan tersebut. Hal ini menjaga pemeriksaan tetap netral terhadap mesin — setiap guest menjelaskan bentuk pengaturan yang dibacanya, dan host menegakkan tepat bentuk itu dan tidak lebih.

Lampiran yang tidak mendeklarasikan pengaturan divalidasi sebagai JSON null. Itulah yang memungkinkan guest menjadikan pengaturannya wajib: skema yang hanya menerima objek menolak lampiran yang tidak menyediakan pengaturan, dan build berhenti. Konsekuensinya berlaku pula ke arah sebaliknya, dan inilah yang perlu ditulis dengan sengaja: guest yang pengaturannya benar-benar opsional harus mendeklarasikan skema yang menerima null selain objek, atau guest itu sama sekali tidak dapat dilampirkan tanpa pengaturan. Dua mesin kebijakan yang disertakan di dalam compiler mendeklarasikan "type": ["object", "null"] tepat karena alasan ini — lampirkan salah satunya tanpa blok with: dan mesin itu berjalan dengan nilai bawaannya. Guest yang hanya mendeklarasikan "type": "object" telah menjadikan pengaturannya wajib, terlepas dari apakah itu memang dimaksudkan atau tidak.

ABI adalah milik Aggrega sendiri

Kontrak soket adalah ABI milik Aggrega sendiri, bukan milik mesin kebijakan mana pun. Itulah yang memungkinkan teknologi kebijakan apa pun yang dikompilasi ke Wasm berfungsi sebagai guest pengganti langsung: guest berbicara dengan antarmuka Aggrega ke luar — describe(), ditambah ekspor yang dipanggil oleh peran yang dilayaninya — dan mesin apa pun yang digunakannya merupakan detail implementasi di balik antarmuka tersebut.

Guest yang membungkus mesin kebijakan asing menyerap ABI mesin tersebut di dalam dirinya sendiri. Jika mesin tersebut memiliki ABI Wasm sendiri, titik masuk sendiri, atau protokol host-callback sendiri, guest pembungkus membuat instans dan menjalankannya secara internal serta memetakan keputusan mesin kembali ke bentuk verdict soket. Host compiler hanya melihat antarmuka verdict tata kelola standar; host tidak pernah mengetahui mesin mana yang terlibat dan tidak membawa kode khusus mesin apa pun. Mengganti kebijakan dari satu mesin ke mesin lain adalah perubahan lampiran, bukan perubahan host.

Dua mesin kebijakan disertakan di dalam compiler

Dua mesin kebijakan dikompilasi ke dalam biner CLI, dan operator memasang salah satunya — atau keduanya — dengan cara yang sama seperti memasang plugin tata kelola mana pun:

KoordinatBahasa kebijakanSumber yang dipasang
governance/regoRegoBerkas .rego, atau arsip berenkode base64 dari satu set kebijakan utuh
governance/celCommon Expression Language (CEL)Berkas ekspresi .cel, atau dokumen aturan .yaml / .yml

Segala sesuatu di sekitar bahasanya digunakan bersama. Keduanya melayani keempat peran, keduanya membaca payload per peran yang sama dengan nama field yang sama, keduanya memetakan keputusannya ke tiga tingkat keparahan verdict yang sama melalui setelan translation yang sama, dan keduanya gagal secara terang-terangan alih-alih mengizinkan build yang tidak dapat dievaluasinya. Masing-masing membawa rilis compiler yang menyertakannya sebagai versinya, dan tidak satu pun memerlukan toolchain eksternal atau mengambil apa pun saat build. Apa yang dapat diungkapkan oleh masing-masing bahasa tidak sama: aturan yang berupa beberapa aturan pembantu di Rego dapat memerlukan setelan dan pengulangan di CEL — lihat Apa yang dapat diungkapkan sebuah ekspresi sebelum menulis aturan yang menelusuri sebuah rute.

Yang berbeda adalah bahasa yang digunakan untuk menulis aturan, dan itulah seluruh dasar pemilihannya. Estate yang sudah memiliki korpus Rego — atau tim yang menulis Rego untuk admission control di tempat lain — memasang mesin Rego, dan kebijakannya berjalan apa adanya. Tim yang mengungkapkan aturannya sebagai ekspresi tunggal atas sebuah dokumen, seperti yang dilakukan validating-admission policy Kubernetes, memasang mesin CEL. Keduanya dipasang per peran, sehingga sebuah workspace dapat menjalankan Rego di satu peran dan CEL di peran lain, atau keduanya di peran yang sama sebagai dua pemasangan.

Host agnostik terhadap dari mesin mana sebuah keputusan berasal: host merutekan payload, membaca kembali sebuah verdict atau perubahan, lalu bertindak berdasarkan itu. Memindahkan kebijakan dari satu bahasa ke bahasa lainnya adalah perubahan pemasangan dan penulisan ulang aturan — tidak pernah perubahan host.

Kebijakan Rego: dua jalur

Rego adalah bahasa kebijakan yang umum, dan ada dua jalur untuk menjalankannya — sebuah engine berhambatan rendah yang disertakan di dalam compiler, dan sebuah jalan keluar dengan fidelitas penuh.

Engine Rego di dalam compiler adalah jalur berhambatan rendah. Engine ini membawa evaluator Rego native Wasm, sehingga operator cukup meletakkan file .rego ke dalam sources dan melampirkan plugin — tanpa toolchain eksternal, dan tanpa ada yang diambil saat build. Engine ini melayani keempat peran: plugin yang sama menilai graf build, menilai output yang dirender, membentuk label, atau menyisipkan anotasi, sesuai dengan peran tempat plugin itu dilampirkan. Identitas katalognya adalah nama polos rego di bawah pluginType: governance — koordinat governance/rego — dan versinya adalah rilis compiler yang menyertakannya. Menulis kebijakan untuknya dibahas di bagian berikutnya.

Evaluator ini mengimplementasikan ulang Rego secara independen alih-alih menyematkan implementasi referensi, dan tidak mengimplementasikan setiap builtin Rego. Ketika sebuah kebijakan memanggil builtin yang tidak diimplementasikan evaluator, lampiran tersebut gagal secara terang-terangan: lampiran mengembalikan fault, bukan izin. Build kemudian berhenti dengan fault yang menyebutkan plugin tersebut — sengaja dibedakan dari verdict halt, sehingga “engine tidak dapat mengevaluasi kebijakan ini” tidak pernah disalahartikan sebagai “kebijakan mengizinkan build.” Kebijakan yang tidak dapat dievaluasi menghentikan build; kebijakan itu tidak pernah lolos diam-diam.

Jalan keluar opa build -t wasm adalah jalur dengan fidelitas penuh. Ketika sebuah kebijakan membutuhkan seluruh cakupan builtin atau semantik engine referensi yang persis, kompilasi kebijakan itu dengan toolchain milik OPA sendiri menjadi modul Wasm dan jalankan modul itu di balik guest adaptor yang tipis. Adaptor menyerap ABI Wasm milik OPA sepenuhnya di dalam dirinya (sesuai ABI adalah milik Aggrega sendiri di atas): adaptor menginstansiasi modul hasil build OPA, menetapkan input, memanggil evaluasi, dan memetakan keputusan kembali ke bentuk verdict. Host hanya melihat cakupan verdict governance standar.

Sebuah guest adaptor referensi disertakan sebagai contoh yang dikerjakan. Adaptor ini menyematkan kebijakan yang ditulis dalam Rego dan dikompilasi sebelumnya dengan opa build -t wasm menjadi modul WebAssembly — sebuah artefak yang dipin dan di-check-in, sehingga evaluasi berjalan sepenuhnya di dalam guest tanpa proses OPA dan tanpa ada yang diambil. Pada setiap build, adaptor menginstansiasi modul yang sudah dipanggang itu di dalam dirinya dengan interpreter Wasm tersemat, memenuhi impor milik modul itu sendiri (memori liniernya dan callback builtin-nya), membaca payload sebagai dokumen input OPA dan settings milik lampiran sebagai dokumen data OPA, mengevaluasi setiap entrypoint yang dikompilasi, dan memetakan nama entrypoint deny / warn / audit dari setiap entrypoint ke tingkat keparahan verdict — masing-masing halt, warn, dan info. Jika kebijakan yang dipanggang membutuhkan builtin yang disediakan host yang tidak diimplementasikan adaptor, adaptor gagal secara terang-terangan — menolak modul alih-alih mengembalikan izin — sehingga kebijakan yang tidak dapat dievaluasi menghentikan build alih-alih lolos diam-diam. Membuat ulang modul yang dipanggang dari sumber Rego-nya adalah langkah penulisan yang dijalankan dengan CLI OPA, bukan dependensi saat build. ../examples/policy-data-class-route/ membangun adaptor tersebut di sekitar modulnya sendiri, dan memberikan perintah untuk membuat ulang keduanya.

Kedua jalur berbagi kontrak host yang sama, sehingga memindahkan kebijakan dari engine di dalam compiler ke engine penuh hanyalah perubahan lampiran.

Menulis kebijakan untuk mesin Rego

Mesin ini mengevaluasi Rego yang ditulis operator sepenuhnya di dalam guest, pada peran mana pun dari keempat peran tempat mesin itu dilampirkan. Melampirkannya dua kali, pada dua peran, dengan dua berkas kebijakan yang berbeda, adalah cara satu mesin mencakup dua momen dari build yang sama.

Payload untuk peran lampiran adalah dokumen input kebijakan, dan objek settings lampiran adalah dokumen data kebijakan — sehingga kebijakan membaca ambang batas yang disediakan operator sebagai data.max_replicas. Setiap berkas yang dideklarasikan lampiran di bawah sources menjadi modul kebijakan, dan setiap paket yang dideklarasikan berkas-berkas itu dievaluasi.

Sintaksis aturan yang digunakan untuk menulis kebijakan

Rego ditulis dalam dua sintaksis aturan dan mesin ini menerima keduanya, modul demi modul. Karena itu, kumpulan kebijakan yang disusun sebelum sintaksis saat ini ada dievaluasi berdampingan dengan kebijakan yang ditulis hari ini, dalam lampiran yang sama.

Dalam sintaksis saat ini, badan aturan diawali dengan if, aturan yang mengumpulkan ke dalam suatu set menyatakannya dengan contains, dan modul menyatakan sintaksis yang digunakannya dengan mendeklarasikan import rego.v1 pada barisnya sendiri di bawah deklarasi paket:

package example
import rego.v1
deny contains msg if {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Dalam sintaksis lama dengan kepala berkurung, nilai yang dikumpulkan aturan berada dalam kurung siku pada kepala aturan dan badannya langsung mengikutinya. Modul dalam sintaksis tersebut tidak mendeklarasikan apa pun, karena modul itu dikenali dari tidak dapat di-parse sebagai sintaksis saat ini:

package example
deny[msg] {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

Modul yang dapat di-parse sebagai sintaksis saat ini tetapi tidak mendeklarasikan apa pun ditolak, dengan menyebutkan namanya. Deklarasi itulah yang menetapkan cara pembacaan, dan tanpanya teks aturan yang sama dapat mencapai keputusan yang berlawanan: badan aturan yang tidak pernah terpenuhi tidak menyumbang keputusan dalam sintaksis saat ini tetapi menyumbang satu keputusan dalam sintaksis lama — sehingga kebijakan yang seharusnya diam menghentikan build, dan pada kasus sebaliknya meloloskan build yang aturannya ditulis untuk dihentikan. Alih-alih memilih cara pembacaan untuk modul seperti itu, mesin menolaknya dan menyebutkan apa yang harus ditambahkan:

policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.

Penolakan ini adalah fault build yang menyebutkan nama plugin, bukan verdict, sehingga penolakan ini menghentikan build seperti halnya kebijakan yang tidak dapat dievaluasi dan tidak pernah terbaca sebagai kebijakan yang mengizinkannya.

Ada dua kasus batas yang perlu Anda ketahui sebelum mengejutkan Anda. Modul yang sama sekali tidak memiliki badan aturan — yang hanya mendeklarasikan data — dapat di-parse sebagai sintaksis saat ini, sehingga modul itu juga diminta mencantumkan deklarasi, meskipun kedua cara pembacaan tidak mungkin berbeda untuknya. Dan modul yang ditulis dalam sintaksis lama tidak pernah ditolak, karena modul itu tidak dapat di-parse sebagai sintaksis saat ini: mesin itu sendirilah yang membedakan keduanya, sehingga kebijakan berkepala kurung yang disengaja tidak pernah dikira sebagai kebijakan sintaksis saat ini yang lupa menyatakannya.

Kebijakan mengumpulkan keputusannya di bawah kunci keputusan

Setiap peran membaca keputusan kebijakan dari sebuah kunci keputusan — aturan bernama tempat kebijakan mengumpulkan keputusannya. Kunci mana yang dibaca, dan apa arti keputusan di bawah suatu kunci, ditetapkan oleh peran.

Pada peran verdict, keputusan adalah pesan, dan kunci tempat pesan itu dikumpulkan menetapkan tingkat keparahan pesan itu dilaporkan. Secara bawaan, kuncinya adalah nama koleksi Rego konvensional:

Dikumpulkan di bawahDilaporkan sebagaiEfek pada build
denyhaltmenghentikan build
warnwarnmuncul bersama build yang selesai
auditinfodicatat; hasil build tidak berubah

Pisahkan kedua kosakata ini, karena memang ada dua: deny, warn dan audit adalah nama dalam kebijakan Anda, sedangkan halt, warn dan info adalah tingkat keparahan yang dilaporkan oleh socket. Kolom kiri boleh Anda ganti namanya; kolom kanan adalah set tertutup yang sama untuk setiap socket.

Kebijakan yang menamai keputusannya secara berbeda mendeklarasikan pemetaannya dalam pengaturan lampiran:

with:
settings:
translation:
- key: blocked
severity: halt
- key: advisory
severity: warn

Pemetaan yang dideklarasikan menggantikan bawaan alih-alih memperluasnya: kunci yang disebutkannya adalah tepat kunci yang dibaca, sehingga kebijakan yang masih mengumpulkan ke deny tidak mencapai verdict apa pun setelah pemetaan di atas dideklarasikan. Urutan deklarasi aturan adalah urutan pelaporan verdict. Kunci yang tidak dideklarasikan kebijakan merupakan keputusan yang tidak ada, bukan kegagalan, sehingga satu berkas kebijakan dapat melayani beberapa lampiran.

Tingkat keparahan di luar ketiganya, dan pemetaan yang dideklarasikan kosong, ditolak oleh skema pengaturan yang dideklarasikan plugin — host memvalidasi pengaturan lampiran terhadap skema itu sebelum dispatch. Kunci yang sama yang dipetakan dua kali ditolak saat pemetaan dibaca, yang juga terjadi sebelum kebijakan apa pun dijalankan. Dalam kedua kasus, build berhenti sebelum keputusan dicapai, tidak pernah dengan pemetaan yang diterapkan setengah.

Selain itu, pengaturan adalah data milik kebijakan sendiri: pemetaan dibaca dari objek dan objek tersebut mencapai dokumen data kebijakan tanpa perubahan, sehingga kebijakan yang ditulis untuk kunci bawaan melihat dokumen data yang persis sama dengan yang akan dilihatnya tanpa pemetaan yang dikonfigurasi sama sekali.

Pada peran transform, keputusan adalah perubahan yang harus dilakukan, bukan pesan, sehingga tidak ada tingkat keparahan yang perlu ditetapkan dan kuncinyalah yang ditetapkan: labels pada peran pembentukan label, annotations pada peran penyisipan anotasi. Pengaturan translation hanya dibaca di tempat verdict dilaporkan, sehingga lampiran transform yang mendeklarasikannya membawa pengaturan yang tidak digunakan oleh perannya.

Kunci keputusan dibaca dari setiap paket yang dimuat lampiran, sehingga kumpulan kebijakan dapat menyebarkan aturannya ke beberapa paket dan masing-masing menyumbang apa yang dikumpulkannya. Sisi lainnya perlu diketahui sebelum menimbulkan masalah: dalam satu lampiran, kunci keputusan adalah nama aturan yang dicadangkan di setiap paket, sehingga paket pembantu yang kebetulan mengumpulkan ke labels untuk keperluannya sendiri akan dibaca entri-entrinya sebagai keputusan label. Hal itu gagal secara jelas, bukan diam-diam — lampiran melaporkan bahwa sesuatu yang dikumpulkan di bawah kunci itu bukan keputusan dengan bentuk tersebut — tetapi cara tercepat untuk memahami pesan seperti itu adalah sebagai benturan nama, jadi gunakan kunci itu hanya untuk keputusan dan beri aturan pembantu nama yang berbeda.

Apa yang diekspos payload setiap peran

Payload adalah dokumen input milik policy, sehingga policy membacanya dengan nama-nama yang diberikan oleh wire.

Graf build berada di path yang berbeda pada dua peran yang membawanya. Sebuah verdict atas graf menerima seluruh dokumen graf, sehingga node-nodenya berada di input.graph.spec.nodes; peran pembentuk label menerima proyeksi node, sehingga node-nodenya berada di input.graph.nodes. Karena itu, aturan yang dipindahkan di antara kedua peran tersebut harus disunting, bukan disalin — dan gejala jika hal ini terlupa adalah aturan yang tidak pernah aktif, bukan error, karena path yang tidak ada hanya bernilai undefined.

PeranApa yang dibaca policy
ir-verdictinput.graph — seluruh dokumen graf build: node di input.graph.spec.nodes dengan kunci id node, edge di input.graph.spec.edges. Nilai yang dinyatakan sensitif oleh penulis terbaca sebagai {"aggrega_withheld": "declared"}. input.precalculated_paths — path routing yang dienumerasi, masing-masing membawa daftar nodes yang berurutan dan attached_features, yaitu tipe Feature yang dilampirkan di mana pun pada path tersebut (lihat di bawah). Daftar ini selalu ada: build tanpa rute antar-komponen membawa daftar kosong.
render-verdictinput.artifacts — satu entri per file yang dihasilkan, masing-masing dengan path, content, format, dan documents, yaitu dokumen-dokumen file yang telah di-parse. format adalah format yang dideklarasikan untuk file tersebut oleh penyedia yang merendernya — penyedia Terraform mendeklarasikan hcl untuk setiap file .tf yang dihasilkannya dan json untuk setiap file .tf.json, termasuk file modul yang di-vendor — dan string kosong jika tidak ada penyedia yang mendeklarasikannya, seperti untuk file yang dikontribusikan sebuah Recipe ke keluaran bersama sebuah boundary. File seperti itu tetap di-parse berdasarkan ekstensinya, sehingga documents-nya tetap ada dalam kedua kasus. Artefak yang tidak dapat dibaca secara struktural membawa parse_error dan tanpa dokumen, sehingga policy dapat menolak berdasarkan kegagalan itu sendiri alih-alih membiarkan file yang tidak terbaca lolos tanpa diperiksa.
label-transforminput.graph.nodes — node-node build dengan kunci id node, masing-masing dengan component, resolved_version, labels, dan values: nilai-nilai yang dideklarasikan instance node di Aggregate, dengan template-nya dievaluasi terhadap parameternya, dan tidak ada jika instance tidak mendeklarasikan apa pun. Nilai yang dideklarasikan sensitif oleh Component node dibaca sebagai {"aggrega_withheld": "declared"}, seperti di ir-verdict, dan nilai-nilai saudaranya yang tidak dideklarasikan dibaca sebagaimana tertulis. Aturan membaca input.graph.nodes[id].values untuk memutuskan sebuah label; aturan tidak dapat mengubah nilai. input.compilation_context — release_name dan environment milik Release, sehingga policy dapat memutuskan secara berbeda per environment.
annotation-transforminput.targets — setiap komponen yang dapat dianotasi oleh lampiran, masing-masing dengan boundary_path, component_name — untuk komponen yang ditempatkan entri routing, id-nya dalam graf build, seperti metrics.query — dan annotations yang ditulis Release pada komponen itu sendiri, setiap nilai sebagaimana tertulis: string, objek subkunci, atau null jika komponen memilih keluar dari anotasi yang seharusnya diwarisinya. Setiap kunci yang dibawa komponen hadir apa pun nilainya, sehingga aturan dapat membiarkan kunci yang sudah ditulis seseorang. input.binding_keys — kunci anotasi yang binding-nya didaftarkan oleh Manifest.

Resource Terraform dibaca di path yang berbeda pada masing-masing dari dua bentuk Terraform. Di dalam documents sebuah file .tf native, sebuah blok bersarang di bawah tipenya lalu di bawah setiap labelnya, dan label terakhir menyimpan daftar blok, karena blok yang berbagi tipe dan label dikumpulkan ke dalam satu daftar sesuai urutan sumber. Karena itu, atribut resource dibaca di input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — untuk instance RDS dengan nama apa pun, input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. File .tf.json dibaca sebagaimana Recipe menulisnya, sehingga bentuk objeknya yang lazim, tempat nama menyimpan blok itu sendiri, dibaca di resource.<type>.<name>.<attr>, dan policy yang ditujukan untuk kedua bentuk membaca kedua path. Hal itu berlaku untuk kedua engine policy di dalam compiler. Aturan Rego yang ditulis untuk bentuk lainnya mendapati path yang disebutkannya tidak terdefinisi: aturan yang menguji sebuah nilai di sana tidak pernah aktif, dan aturan yang menolak saat nilai tidak ada, dengan not, aktif pada setiap resource; ekspresi CEL yang mengindeks atau memilih ke dalam bentuk lainnya menghentikan build dengan kesalahan evaluasi yang menyebut file policy-nya. Adaptor render Rego referensi, yang dijelaskan di Adaptor policy tahap render di bawah, mem-parse sendiri file .tf native dan membaca satu blok sebagai objek, sehingga path Terraform harus disunting, bukan disalin, ketika policy berpindah antara adaptor itu dan engine di dalam compiler.

Setiap peran juga membawa input.sources — file milik lampiran itu sendiri, masing-masing dengan path berupa nama dasar dan content-nya. Policy hanya berjalan sebagai salah satu file tersebut, sehingga di mana pun aturan membaca daftar itu, daftar tersebut setidaknya memuat file itu.

input.settings adalah objek settings lampiran, objek yang sama dengan dokumen data milik policy, dan hadir ketika lampiran mendeklarasikan settings. Ketika lampiran tidak mendeklarasikan apa pun, apa yang ditemukan aturan bergantung pada perannya: di ir-verdict, label-transform, dan annotation-transform field tersebut tidak ada, sehingga input.settings tidak terdefinisi seperti path apa pun yang tidak dibawa payload, dan di render-verdict nilainya objek kosong. Jadi aturan yang bergantung pada apakah sebuah pengaturan telah dikonfigurasi menguji pengaturan yang dibacanya, bukan objeknya, dan cara ini berperilaku sama di setiap peran — max_nodes yang dikonfigurasi akan dibaca, sedangkan yang tidak dikonfigurasi membuat input.settings.max_nodes tidak terdefinisi dan aturan diam:

package example
import rego.v1
deny contains msg if {
limit := input.settings.max_nodes
count(input.graph.spec.nodes) > limit
msg := sprintf("this build declares more than %v nodes", [limit])
}

Engine CEL memperlakukan objek settings yang tidak dideklarasikan secara berbeda, dan menjelaskannya di bagiannya sendiri di bawah.

attached_features dan binding_keys adalah daftar, bukan objek, sehingga policy menguji keanggotaan dengan in:

package security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some gateway in path.nodes
input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"]
not "core/data-masking" in path.attached_features
msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])
}

attached_features adalah gabungan tipe Feature dari setiap lampiran yang dimiliki node mana pun pada path — termasuk lampiran yang ditulis pada salah satu koneksi node tersebut, koneksi mana pun tempat lampiran itu ditulis — sehingga aturan terpenuhi oleh lampiran core/data-masking pada gateway itu sendiri, yang merupakan tempat Feature tersebut dilampirkan: Feature itu memilih berdasarkan kapabilitas content-masking yang dideklarasikan gateway. Yang dimask oleh lampiran adalah teks chat dan completion yang melewati gateway tersebut; aturan memeriksa bahwa lampiran itu ada, bukan apa yang dicantumkannya.

Karena merupakan gabungan atas seluruh path, daftar ini menyatakan bahwa sebuah Feature dilampirkan di suatu tempat pada rute, tetapi tidak pernah di mana. Aturan yang perlu mengetahui apakah sebuah Feature berada di antara dua komponen tertentu pada rute — komponen yang menyimpan data terbatas dan komponen yang dijangkaunya — membaca nodes milik rute secara berurutan beserta lampiran milik setiap node, di input.graph.spec.feature_values_mapping[<node>]; jika diajukan kepada attached_features, pertanyaan yang sama meloloskan rute yang Feature-nya berada melewati komponen kedua. ../examples/policy-data-class-route/ ditulis dengan cara itu, untuk engine Rego, engine CEL, dan OPA.

Objek node tidak membawa id sendiri: id adalah kunci tempat objek itu berada di input.graph.spec.nodes, itulah sebabnya aturan di atas membawa id yang dibacanya dari path.nodes ke dalam pesannya alih-alih membaca field id.

Urutan policy menjumpai kunci sebuah map

Graf mempertahankan urutan yang ditulis penulisnya: node dalam urutan komponen dideklarasikan, dan label setiap node dalam urutan node membawanya. Urutan itu sampai ke guest secara utuh — payload membawa keduanya sebagai entri berurutan (lihat map yang mempertahankan urutannya). Apakah policy menjumpai urutan itu ditentukan oleh cara engine yang mengevaluasi policy menyimpan objek, bukan oleh payload:

  • Engine Rego menyimpan kunci objek dalam keadaan terurut. Aturan yang mengiterasi input.graph.spec.nodes, labels milik sebuah node, atau objek lain mana pun — termasuk objek yang ditulis di dalam policy itu sendiri — menjumpai kunci dalam urutan terurut: komponen yang dideklarasikan web, api, metrics dijumpai sebagai api, metrics, web.
  • Engine CEL tidak menetapkan urutan untuk map. Comprehension atas input.graph.spec.nodes atau atas labels milik sebuah node dapat menjumpai kunci dalam urutan berbeda pada dua build dengan input identik, dan dua penelusuran map yang sama dalam satu ekspresi dapat berbeda satu sama lain. Itulah sebabnya pesan di bawah satu kunci keputusan diurutkan: tulislah aturan yang keputusannya tidak bergantung pada posisi sebuah kunci.
  • Guest yang ditulis dengan plugin kit menjumpai urutan penulis. Setelah didekode melalui kit-nya, node dan label setiap node tiba di container kit yang mempertahankan urutan, dalam urutan yang dibawa payload, dan kerangka adapter governance yang disertakan setiap kit menyerahkan kepada engine-nya dokumen JSON yang ditulis dalam urutan yang sama. Engine yang mengonversi dokumen itu menjadi tipe nilainya sendiri menjumpai urutan tipe tersebut, sebagaimana dijelaskan dalam map yang mempertahankan urutannya.

Membentuk label: policy menamai label, dan engine mengalamatkannya

Pada peran pembentuk label, policy mengumpulkan satu keputusan per label di bawah labels, yang menyebutkan node, kunci label, dan nilai yang diambil label tersebut:

package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

Menetapkan kunci yang sudah ada akan menggantikan nilainya. Sebagai gantinya, keputusan dapat meminta agar sebuah kunci dihapus:

labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if {
some id, node in input.graph.nodes
node.labels["draft.example.com/scratch"]
}

Policy menamai label alih-alih menulis instruksi edit yang diterapkan build, dan alasannya patut diketahui: instruksi mengalamatkan label melalui path, dan kunci label Aggrega lazimnya mengandung /, yang merupakan pemisah path — sehingga path yang ditulis manual akan mengalamatkan lokasi bersarang alih-alih satu label. Engine mengalamatkan label yang disebutkan keputusan, sehingga escaping ditulis sekali alih-alih di setiap policy, dan policy tetap terbaca sebagai pernyataan tentang label, bukan tentang path.

Keputusan hanya dapat mengubah label. Setiap instruksi yang dihasilkan engine mengalamatkan satu label pada satu node, sehingga policy tidak memiliki cara untuk menyatakan perubahan pada Component sebuah node, versi yang telah di-resolve, himpunan node, atau nilai label yang bukan string. Keputusan yang menyebutkan node yang tidak dimiliki build, atau menghapus label yang tidak dibawa node, ditolak oleh build dengan pesan yang menyebutkan instruksi tersebut — tidak pernah diabaikan secara diam-diam.

../examples/policy-label-transform/ memasang policy seperti itu di samping dua plugin penandaan bawaan, beserta verdict atas graf yang membaca label yang ditulis keduanya. Apa yang dibaca dan ditulis masing-masing plugin itu ada di Plugin penandaan bawaan.

Menyisipkan anotasi

Pada peran penyisip anotasi, policy mengumpulkan satu keputusan per anotasi di bawah annotations, yang menyebutkan target melalui koordinat yang dibawa target itu sendiri, serta kunci dan nilainya:

package tagging
import rego.v1
annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
} if {
some target in input.targets
not target.annotations["backup.example.com/schedule"]
}

Nama field yang ditulis keputusan adalah nama field tempat keputusan itu membaca targetnya, sehingga konvensi ini dapat dipelajari dari payload saja. Membaca input.binding_keys memungkinkan policy hanya menyisipkan kunci yang maknanya telah didaftarkan Manifest — kunci-kunci itulah yang diekspansi menjadi lampiran Feature.

Nilai sebuah keputusan adalah nilai yang dapat Anda tulis sendiri pada anotasi itu: string, atau objek subkunci. Binding yang merutekan satu subkunci menerima string; binding yang merutekan beberapa subkunci menerima objek yang menyebut masing-masing subkunci, persis seperti yang ditulis operator di Release:

annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "feature.aggrega.ai/monitoring",
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
some target in input.targets
not target.annotations["feature.aggrega.ai/monitoring"]
}

Build membaca nilai yang disisipkan persis seperti membaca nilai yang sama yang ditulis di Release, sehingga nilai itu diekspansi dengan cara yang sama dan diperiksa terhadap Feature yang terikat dengan cara yang sama. Engine menyimpan kunci-kunci objek dalam keadaan terurut, sehingga subkunci mencapai build dalam urutan terurut. Nilai dengan bentuk lain apa pun — null, list, angka, boolean, atau objek tanpa subkunci — ditolak oleh build dengan menyebut penyisipannya: peran ini menambahkan anotasi, dan null atau objek kosong dibaca sebagai opt-out yang ditulis penulis untuk menghapus anotasi. Keputusan yang menyebut komponen yang tidak dibawa payload ditolak dengan cara yang sama, dengan menyebut koordinat dan anotasinya.

Ketika build menolak anotasi yang disisipkan karena cara perutean atau isinya — string yang diberikan ke binding yang merutekan beberapa subkunci, nilai subkunci yang tidak diterima skema Feature yang terikat, atau subkunci yang dirutekan melalui pilar values, yang tidak boleh digunakan anotasi di sisi Release — penolakan itu menyebut plugin yang menyisipkannya dan peran governance tempat plugin itu dipasang, sehingga nilai tersebut dapat ditelusuri ke policy yang memutuskannya, bukan ke baris Release yang tidak pernah ditulis siapa pun.

../examples/policy-annotation-transform/ memasang policy seperti itu, menyisipkan string di bawah satu binding dan objek subkunci di bawah binding lain, dan membangun file yang sama dengan Release yang menulis anotasi-anotasi itu secara manual.

Melampirkan seluruh set kebijakan sebagai satu arsip

Sebuah set kebijakan dilampirkan berkas demi berkas, atau sebagai satu arsip yang membawa berkas kebijakan dan dokumen datanya bersama-sama — bentuk yang dibangun oleh toolchain Rego. Konten berkas yang dilampirkan dikirim ke guest sebagai teks, sedangkan arsip terkompresi berupa byte sembarang, bukan teks, sehingga arsip dilampirkan dalam enkode base64, dengan nama yang berakhiran .base64:

Terminal window
tar czf bundle.tar.gz policy.rego data.json
base64 -w0 bundle.tar.gz > bundle.tar.gz.base64
with:
sources:
- ./policies/bundle.tar.gz.base64

Namalah yang menandai sebuah berkas sebagai arsip, bukan sebagai teks kebijakan, sehingga pilihan itu tetap menjadi pernyataan operator sendiri: arsip yang rusak kemudian dilaporkan sebagai arsip yang rusak, dengan menyebut berkas dan langkah yang gagal, alih-alih dibaca sebagai berkas kebijakan yang tidak dapat di-parse. Mengenkode arsip adalah langkah yang ditambahkan operator setelah toolchain mereka membangunnya.

Di dalam arsip, setiap anggota .rego adalah modul kebijakan dan setiap anggota data.json atau data.yaml adalah dokumen data yang bersarang di bawah direktori tempatnya berada — limits/data.json yang berisi {"max": 3} dibaca oleh kebijakan sebagai data.limits.max. Anggota dengan jenis lain dibawa oleh arsip untuk toolchain-nya sendiri dan bukan merupakan input kebijakan.

Arsip yang tidak dapat dibuka merupakan kegagalan yang menyebut berkas yang dilampirkan: enkode yang tidak dapat didekode, aliran yang tidak dapat didekompresi, arsip yang terpotong, berkas data yang tidak dapat dibaca, atau arsip yang sama sekali tidak berisi kebijakan. Tidak satu pun dari kasus ini menghasilkan set kebijakan kosong, karena set kebijakan kosong tidak mencapai keputusan apa pun — dan “arsip tidak dapat dibaca” tidak boleh sampai tidak dapat dibedakan dari “kebijakan mengizinkan build”.

Menulis kebijakan untuk mesin CEL

Mesin ini mengevaluasi CEL yang ditulis operator sepenuhnya di dalam guest, pada peran mana pun dari keempat peran tempat mesin itu dipasang. Identitas katalognya adalah nama polos cel di bawah pluginType: governance — koordinat governance/cel — dan versinya adalah rilis kompiler yang menyertakannya. Memasangnya dua kali, pada dua peran, dengan dua berkas kebijakan yang berbeda, adalah cara satu mesin mencakup dua momen dari build yang sama.

plugins:
governance:
- uri: governance/cel:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.cel
settings:
max_nodes: 20

Sebuah kebijakan mengakses seluruh payload melalui satu nama, input, sehingga nama-nama yang dibacanya adalah nama yang diberikan oleh wire: graf build di input.graph, jalur perutean yang dienumerasi di input.precalculated_paths, berkas yang dirender di input.artifacts, target anotasi di input.targets. Jalur per peran tersebut adalah jalur yang ditabulasikan dalam Apa yang diekspos oleh payload setiap peran di atas, dan jalur tersebut identik untuk kedua mesin — satu wire, dibaca di bawah satu nama akar.

Berkas milik pemasangan itu sendiri berada di input.sources dan pengaturannya di input.settings, sehingga ambang batas yang diberikan operator dibaca sebagai input.settings.max_nodes. Tidak ada dokumen kedua yang perlu dipelajari: pengaturan adalah bagian dari input seperti yang lainnya. Keduanya selalu hadir sebagai nilai — pengaturan berupa objek kosong di setiap peran ketika pemasangan tidak mendeklarasikan apa pun — sehingga ekspresi yang mengaksesnya tidak perlu berjaga terhadap ketiadaannya, dan apakah suatu pengaturan telah dikonfigurasi diuji pada kuncinya: has(input.settings.max_nodes).

Dua bentuk penulisan, dan nama berkas yang memilih di antaranya

Sebuah kebijakan dipasang dalam salah satu dari dua bentuk, dan nama berkas menentukan yang mana:

Nama berkas berakhiranDibaca sebagai
.celsatu ekspresi, dievaluasi apa adanya
.yaml atau .ymldokumen aturan — daftar aturan
lainnyasatu ekspresi

Nama itulah seluruh aturannya. Tidak ada pengaturan yang memilih bentuk, dan teks berkas tidak diperiksa untuk menebaknya — teks itu memang tidak dapat menjawab pertanyaan tersebut, karena nilai terluar sebuah ekspresi adalah map, begitu pula nilai terluar dokumen aturan, sehingga kedua bentuk tidak dapat dibedakan dari strukturnya.

Jadi aturan ini berlaku dua arah, dan kedua kesalahan ditolak alih-alih salah dibaca. Dokumen aturan bernama policy.cel ditolak, karena daftar aturan YAML bukanlah ekspresi; ekspresi bernama policy.yaml ditolak, karena ekspresi bukanlah daftar aturan. Setiap penolakan menyebutkan nama berkasnya. Mengganti nama berkas adalah perbaikannya di kedua arah.

Sebuah set kebijakan terdiri atas sebanyak mungkin berkas yang dibutuhkan, dan kedua bentuk dapat dicampur bebas dalam satu pemasangan.

Ekspresi, dalam berkas bernama .cel

Bahasa ekspresi tidak memiliki nama aturan untuk mengumpulkan keputusan, sehingga keputusan-keputusan itu adalah nilai yang dihasilkan ekspresi: sebuah map dari kunci keputusan ke apa yang dikumpulkan kunci tersebut. Pada peran verdict, sebuah kunci mengumpulkan pesan yang dicapai di bawahnya; pada peran yang membentuk build, kunci itu mengumpulkan keputusan yang akan diterapkan.

{
"deny": input.graph.spec.nodes
.filter(n, input.graph.spec.nodes[n].resolved_version == "latest")
.map(n, "component " + n + " tracks the latest version; pin it"),
"warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],
}

Kunci yang tidak dicantumkan berkas berarti tidak mencapai keputusan di sana, sehingga berkas tidak perlu menyebut setiap kunci — dan setiap peran hanya membaca kunci yang relevan baginya, sehingga satu set kebijakan dapat melayani peran verdict dan peran yang membentuk build dari berkas yang sama. Sebuah kunci membawa daftar apa yang dikumpulkannya, satu item saja, atau nilai null untuk tidak ada.

Ekspresi yang dievaluasi menjadi apa pun selain map akan ditolak, dengan menyebutkan bentuk yang harus ditulis. size(input.graph.spec.nodes) <= 5 yang polos adalah kesalahan yang patut diantisipasi: itu adalah boolean, dan membaca false sebagai halt berarti mengarang pesan yang tidak pernah ditulis penulisnya.

Dokumen aturan, dalam berkas bernama .yaml atau .yml

Dokumen aturan adalah daftar aturan, yang masing-masing menyebutkan kunci keputusan yang dicapainya, ekspresi yang menentukan apakah aturan itu tercapai, dan apa yang dilaporkan ketika tercapai:

- key: deny
expression: size(input.graph.spec.nodes) > 20
message: this build declares a lot of components
- key: warn
expression: has(input.settings.max_nodes)
message: a component ceiling is configured for this environment

Apa yang dilaporkan sebuah aturan mengikuti kunci keputusan yang dicapainya, persis seperti dalam ekspresi. Teks adalah pesan yang dibawa verdict. Mapping adalah field dari satu keputusan yang dibaca oleh peran yang membentuk build:

- key: labels
expression: input.compilation_context.environment == "production"
message:
node: app
key: compliance.example.com/tier
value: gold

Mana dari keduanya yang ditulis sebuah aturan ditentukan oleh aturan itu sendiri — tidak ada pengaturan yang memilihnya — dan aturan yang menulis bentuk yang salah untuk kuncinya akan ditolak, dengan menyebut namanya.

Satu detail YAML yang perlu diketahui sebelum menimbulkan masalah: ekspresi yang diawali tanda kutip ganda harus dikutip untuk pembaca dokumen, karena nilai yang dibuka dengan " dibaca sebagai skalar berkutip, bukan sebagai teks yang diawali tanda kutip.

- key: annotations
expression: '"backup.example.com/schedule" in input.binding_keys'
message:
boundary_path: main
component_name: app
annotation_key: backup.example.com/schedule
annotation_value: nightly

Dokumen aturan dibaca sebagai ekspresi yang diwakilinya sebelum apa pun dievaluasi. Setiap aturan menjadi kunci keputusannya yang membawa laporannya ketika ekspresi bernilai benar dan tidak membawa apa pun ketika tidak, dan aturan yang berbagi kunci digabungkan. Jadi satu evaluator menjalankan kedua bentuk, dan dokumen aturan memutuskan persis apa yang diputuskan ekspresi yang diwakilinya — pada setiap peran, baik verdict maupun keputusan yang membentuk build. Dua konsekuensi muncul. Sebuah dokumen dan ekspresi tulisan tangan yang diwakilinya mencapai keputusan yang sama, karena keduanya adalah evaluasi yang sama. Dan aturan pengurutan di bawah ini berlaku untuk bentuk yang dievaluasi, bukan untuk dokumen — aturan-aturan dalam dokumen tidak dilaporkan sesuai urutan penulisannya.

Bentuk mana yang cocok — keduanya tidak dapat saling menggantikan

Kedua bentuk dijalankan melalui satu evaluator, sehingga tidak ada yang lebih cepat atau lebih tepercaya daripada yang lain. Yang berbeda adalah apa yang dapat dinyatakan masing-masing, dan karena dua bentuk berarti dua hal yang harus dipelajari, pembagiannya layak dinyatakan dengan jelas alih-alih diserahkan pada selera. Pilih berdasarkan apa yang dilaporkan aturan.

  • Dokumen aturan, ketika laporannya tetap. Pesan atau keputusan ditulis sekali, di samping ekspresi yang mencapainya, dan berkas terbaca sebagai daftar penjaga. Inilah bentuk yang lebih ringkas untuk “jika ini benar, katakan persis ini”.
  • Ekspresi, ketika laporannya menyebutkan apa yang ditemukannya. Satu ekspresi menyaring komponen dalam sebuah build dan menghasilkan pesan — atau keputusan — per komponen, sehingga pembaca mendapatkan component payments tracks the latest version; pin it untuk setiap pelanggar, alih-alih satu kalimat tentang jumlah.

Tugas kedua itulah yang tidak dapat dilakukan dokumen aturan: setiap aturannya membawa satu laporan yang ditulis sebelumnya, sehingga tidak dapat mengatakan komponen mana yang memicunya. Memilih bentuk dokumen lalu menginginkan nama pelanggar dalam pesan adalah jalan yang berakhir dengan menulis ulang aturan sebagai ekspresi, jadi sebaiknya pilihan dibuat berdasarkan pertanyaan itu sejak awal.

Apa yang dapat dinyatakan ekspresi

Ekspresi yang dievaluasi mesin ini menggunakan comprehension filter, map dan exists, + pada string dan list, size, in, startsWith, string(), operator kondisional, dan list yang diindeks dengan bilangan bulat hasil perhitungan. Ekspresi ini tidak menyediakan fungsi ekstensi yang ditambahkan sebagian lingkungan CEL: join, split, substring, indexOf, flatten, cel.bind dan lists.range masing-masing ditolak sebagai referensi yang tidak dideklarasikan, dan sebuah comprehension menerima satu variabel, sehingga bentuk dua variabel seperti exists(i, v, …) ditolak dengan cara yang sama. Penolakan adalah kesalahan build yang menyebutkan berkas dan referensinya:

policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'

Tiga konsekuensi membentuk aturan yang menelusuri sebuah rute:

  • Tidak ada cara untuk menamai nilai antara. Subekspresi yang digunakan dua kali ditulis dua kali, atau diikat dengan memetakan list berisi satu item: [value].map(name, …)[0] mengevaluasi badannya sekali dengan name terikat pada value.
  • Tidak ada cara untuk menelusuri posisi-posisi sebuah list. Aturan yang membandingkan komponen sebuah rute berdasarkan posisi mengambil posisi dari pengaturannya — list positions seperti [0, 1, 2, …] — dan mengindeks rute pada setiap posisi, sehingga aturan itu harus berjaga terhadap rute yang lebih panjang daripada list itu sendiri, dengan melakukan halt pada rute tersebut, alih-alih membacanya sebagian.
  • Kunci keputusan mengumpulkan pesan, bukan list pesan. Ekspresi yang menghasilkan satu list pesan per rute ditolak di bawah kunci keputusan — kesalahannya menyatakan bahwa kunci itu mengumpulkan nilai bertipe list alih-alih pesan — sehingga aturan menghasilkan satu record per rute dan menyusun pesan darinya. Dan pesan yang dihasilkan ekspresi dua kali dilaporkan dua kali: pengurutan yang dijelaskan di bawah mengurutkan apa yang dikumpulkan sebuah kunci, dan tidak menghapus pengulangan.

../examples/policy-data-class-route/ memuat aturan CEL yang ditulis dengan memperhatikan ketiganya, di samping aturan yang sama untuk mesin Rego.

Kunci keputusan dan tingkat keparahan

Kunci keputusan, pemetaan bawaan ke tingkat keparahan, dan pengaturan translation yang menamainya ulang sama seperti pada mesin Rego — lihat Sebuah kebijakan mengumpulkan keputusannya di bawah sebuah kunci keputusan di atas. Secara bawaan deny dilaporkan pada halt, warn pada warn, dan audit pada info; translation yang dideklarasikan menggantikan bawaan tersebut alih-alih memperluasnya, dan urutan yang dideklarasikannya adalah urutan pelaporan verdict.

Kedua mesin mendeklarasikan skema pengaturan yang sama untuknya, sehingga blok translation bermakna sama apa pun bahasa yang mengekspresikan keputusan, dan blok yang tidak valid ditolak sebelum kebijakan apa pun dijalankan.

Pada peran yang membentuk build, kuncinya tetap alih-alih dipetakan: labels pada peran pembentuk label, annotations pada peran penyisip anotasi.

Pengurutan: terurut dalam satu kunci, dan urutan total atas keputusan

Pesan di bawah satu kunci keputusan dilaporkan dalam urutan terurut. Hal itu bagian dari kontrak, bukan pilihan penyajian, dan alasannya patut diingat: sebuah komprehensi atas map — .filter(...) dan .map(...) atas input.graph.spec.nodes, yang merupakan cara paling wajar untuk menulis aturan per komponen — menelusuri map itu dalam urutan yang tidak ditetapkan oleh evaluator. Jika dibiarkan, input yang identik akan melaporkan pesan yang sama dalam urutan berbeda pada setiap build. Pengurutan menghilangkan hal itu.

Dua hal berikut mudah dianggap sebagai bug padahal bukan:

  • Aturan dalam dokumen aturan juga dilaporkan secara terurut, bukan dalam urutan penulisannya — karena dokumen dievaluasi sebagai ekspresi yang diwakilinya, dan pengurutan berlaku pada apa yang dikumpulkan sebuah kunci.
  • Daftar yang ditulis tangan juga diurutkan. Kunci yang membawa ["second", "first"] melaporkan first sebelum second. Tidak ada apa pun dalam hasil evaluasi yang membedakan daftar yang diketik penulis dari daftar yang dihasilkan komprehensi, sehingga tidak ada urutan tulisan yang perlu dipertahankan.

Antarkunci, urutannya adalah urutan yang dideklarasikan translation. Antarfile, urutannya adalah urutan nama file, karena sumber sebuah lampiran tiba terurut berdasarkan nama alih-alih dalam urutan yang dicantumkan lampiran tersebut.

Pada peran yang membentuk build, penalaran yang sama berlaku pada keputusan itu sendiri, dan urutannya lebih kuat: keputusan dilaporkan dalam urutan menaik dari semua yang dinamainya, yang merupakan urutan total atas apa yang dapat diekspresikan sebuah keputusan — node, lalu kunci label, lalu apakah label ditambahkan atau dihapus, lalu nilainya; dan untuk penyisipan, boundary, lalu komponen, lalu kunci anotasi, lalu nilainya. Perubahan pada label atau anotasi mencapai output yang dirender, sehingga urutan sembarang berarti input identik dirender berbeda dari satu build ke build berikutnya.

Membentuk label

Pada peran pembentuk label, policy mengumpulkan satu keputusan per label di bawah labels, yang menyebutkan node, kunci label, dan nilai yang diambil label tersebut:

{
"labels": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server")
.map(n, {
"node": n,
"key": "compliance.example.com/tier",
"value": input.compilation_context.environment == "production" ? "gold" : "bronze",
}),
}

Menetapkan kunci yang sudah ada akan mengganti nilainya. Sebagai gantinya, sebuah keputusan dapat meminta agar kunci dihapus, dengan menetapkan op sebagai remove:

{
"labels": input.graph.nodes
.filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels)
.map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),
}

Satu keputusan tidak memerlukan daftar di sekelilingnya, dan file yang tidak menyebut kunci labels tidak memutuskan label apa pun.

Kebijakan menamai label alih-alih menulis instruksi edit yang diterapkan build, dengan alasan yang diberikan di bagian pembentukan label mesin Rego: kunci label Aggrega lazim memuat /, dan path yang ditulis tangan akan menunjuk lokasi bersarang alih-alih satu label. Mesin menunjuk label yang dinamai keputusan.

Membaca label yang mungkin tidak dimiliki sebuah node adalah kegagalan, bukan nilai kosong, itulah sebabnya contoh kedua memeriksa apakah kunci ada sebelum membacanya. Itu adalah aturan bahasa ekspresi itu sendiri tentang membaca kunci yang tidak ada, dan aturan itu jelas terlihat: kebijakan yang mencari label yang tidak dimiliki node mana pun melaporkan bahwa ia tidak dapat dievaluasi alih-alih diam-diam tidak memutuskan apa pun.

Sebuah keputusan hanya dapat mengubah label. Keputusan yang menamai node yang tidak ada dalam build, atau menghapus label yang tidak dimiliki node, ditolak oleh build dengan pesan yang menyebut instruksinya — tidak pernah diabaikan diam-diam.

Capai satu keputusan per node dan kunci label. Aturan yang dapat menghasilkan dua nilai berbeda untuk label yang sama pada node yang sama tidak terspesifikasi dengan cukup: tentukan nilainya di dalam ekspresi — dengan kondisional, atau dengan filter yang meloloskan satu cabang — alih-alih mengeluarkan kedua keputusan.

../examples/policy-label-transform/ menunjukkan peran pembentuk label dari awal hingga akhir, dengan policy-nya ditulis untuk engine Rego.

Menyisipkan anotasi di bawah kunci yang terdaftar

Pada peran penyisip anotasi, kebijakan mengumpulkan satu keputusan per anotasi di bawah annotations, menamai target dengan koordinat yang dibawa target itu sendiri, ditambah kunci dan nilainya:

{
"annotations": input.targets
.filter(t, "backup.example.com/schedule" in input.binding_keys)
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
}),
}

Nama field yang ditulis sebuah keputusan adalah nama field tempat ia membaca targetnya, sehingga konvensi dapat dipelajari dari payload saja. Membaca input.binding_keys memungkinkan kebijakan hanya menyisipkan kunci yang maknanya telah didaftarkan Manifest — yaitu kunci yang diperluas menjadi lampiran Feature. Setiap field wajib: anotasi dengan kunci kosong atau nama komponen kosong bukanlah sesuatu yang dimaksudkan untuk diminta kebijakan. Boundary tempat sebuah komponen berada dapat secara sah dinamai dengan string kosong, sehingga field tersebut harus ada tetapi boleh kosong.

Nilainya adalah nilai yang dapat Anda tulis sendiri pada anotasi itu: string, atau map subkunci, yang menjadi masukan bagi binding yang merutekan beberapa subkunci sekaligus — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Engine menulis subkunci sebuah map dalam urutan terurut, karena bahasa ekspresi tidak menetapkan urutan untuk map, dan meneruskan nilainya sebagaimana dihasilkan ekspresi; nilai yang tidak dapat ditampung model JSON — byte, timestamp, durasi — ditolak alih-alih diubah menjadi teks. Build kemudian membaca nilai itu persis seperti membaca nilai yang sama yang ditulis di Release, dan menolak null, list, angka, boolean, atau map kosong, dengan menyebut penyisipannya. Dua keputusan untuk satu komponen dan kunci dengan nilai berbeda diurutkan berdasarkan JSON nilainya. annotations milik target membawa setiap nilai yang ada sebagaimana tertulis — string, map, atau null untuk opt-out — sehingga menguji "feature.aggrega.ai/monitoring" in t.annotations menemukan kunci apa pun nilainya.

Keputusan yang menamai komponen yang tidak dibawa payload ditolak oleh build, dengan menyebut koordinat dan anotasinya. Ketika build menolak anotasi yang disisipkan karena peruteannya, nilai subkuncinya, atau pilarnya, penolakan itu menyebut plugin yang menyisipkannya dan peran tempat plugin itu dipasang. Seperti pada label, capai satu keputusan per komponen dan kunci anotasi, dengan menentukan nilainya di dalam ekspresi alih-alih mengeluarkan dua keputusan untuk satu kunci.

../examples/policy-annotation-transform/ menunjukkan peran penyisip anotasi dari awal hingga akhir, dengan policy-nya ditulis untuk kedua engine.

Ketika kebijakan atau keputusan tidak dapat dibaca

Kebijakan yang tidak dapat dibaca atau dievaluasi oleh mesin, atau yang menghasilkan sesuatu selain keputusan dalam bentuk yang terdokumentasi, membuat build gagal alih-alih mengembalikan verdict atau perubahan. Kegagalan dilaporkan sebagai kesalahan build yang menyebut file dan, jika kesalahan itu milik satu bagian file, posisi di dalamnya — sengaja dibedakan dari verdict halt, sehingga “kebijakan ini tidak dapat dievaluasi” tidak pernah disalahartikan sebagai “kebijakan ini mengizinkan build”.

Untuk sebuah ekspresi, hal itu mencakup sumber yang tidak dapat di-parse — dilaporkan dengan baris dan kolom dari parser itu sendiri serta tanda caret di bawah posisi yang bermasalah — dan sumber yang dievaluasi menjadi sesuatu selain map dari kunci keputusan ke apa yang dikumpulkan kunci tersebut.

Untuk sebuah dokumen aturan, hal itu mencakup teks yang bukan daftar aturan, daftar tanpa aturan di dalamnya, aturan yang kehilangan field atau membawa field kosong, field yang tidak didefinisikan oleh bentuk tersebut, laporan yang bukan teks maupun pemetaan teks ke teks, dan ekspresi yang tidak dapat dibaca. Kesalahan yang milik satu aturan menyebut posisi aturan itu — dihitung mulai dari satu, seperti penulis menghitung filenya sendiri — dan kunci keputusannya. Aturan yang ekspresinya tidak dapat di-parse ditolak sebelum evaluasi, sehingga caret jatuh di dalam ekspresi yang ditulis penulis alih-alih pada posisi dalam teks terjemahan yang tidak pernah mereka lihat.

Untuk sebuah keputusan pada peran yang membentuk build, hal itu mencakup pesan di tempat yang seharusnya berisi keputusan, koordinat yang hilang, dan field yang tidak didefinisikan oleh bentuk keputusan mesin ini. Yang terakhir patut disebut tersendiri: annotation_valu yang salah eja ditolak, bukan diabaikan, sehingga kesalahan dilaporkan alih-alih diam-diam menyisipkan nilai kosong dan meninggalkan build yang selesai tanpa perubahan tersebut. Setiap penolakan semacam itu menyebut file dan diakhiri dengan menyebut apa yang harus dinamai oleh keputusan jenis tersebut.

Adaptor kebijakan tahap render

Adaptor tahap render bernalar atas keluaran hasil render build, bukan atas graf IR-nya. Payload render membawa artefak yang dihasilkan — masing-masing dengan jalur keluaran dan konten hasil rendernya, serta, bila berlaku, format yang digunakan untuk merendernya dan tampilan terstruktur hasil parsing-nya — ditambah sumber dan pengaturan milik lampiran itu sendiri, masing-masing bila lampiran mendeklarasikannya. Adaptor membaca konten tersebut untuk bentuk keluaran yang ditargetkannya, mengevaluasi kebijakan atas hasil terstruktur, dan memetakan hasilnya ke verdict halt / warn / info. Karena payload tidak menyebut bentuk keluaran apa pun miliknya sendiri, satu pola adaptor melayani target render apa pun; bentuk keluaran baru adalah adaptor baru, bukan perubahan pada host.

Setiap adaptor tahap render adalah adaptor dalam pengertian di atas: ia berbicara dengan ABI Aggrega ke arah luar dan menyerap format khusus target atau kontrak mesin kebijakan asing ke arah dalam, sehingga compiler tetap bebas dari logika format keluaran maupun logika kebijakan. Mesin Rego dan CEL di dalam compiler melayani peran render-verdict secara langsung; di luar keduanya, dua adaptor tahap render referensi disertakan sebagai contoh lengkap di antara contoh Rust milik kit pengembangan plugin, satu untuk setiap bentuk keluaran yang umum.

../examples/policy-render-verdict/ memasang satu aturan di render-verdict atas keluaran empat target — objek Kubernetes, file Docker Compose, konfigurasi root Terraform, dan template CloudFormation — yang ditulis sekali untuk setiap engine di dalam compiler, dan memeriksa bahwa pelanggaran yang ditanam di setiap target menghentikan build dan kontrolnya lolos.

Untuk menulis adaptor Anda sendiri, di peran ini atau peran lainnya, mulailah dari kerangka adaptor governance yang disertakan setiap kit pengembangan plugin: Menulis plugin governance Anda sendiri memandu dari kerangka itu hingga build yang ditolak adaptor tersebut.

Keluaran YAML, JSON, dan Terraform HCL — adaptor render Rego referensi

Adaptor render Rego referensi menjalankan Rego yang disediakan operator atas keluaran render YAML atau JSON apa pun, dan atas keluaran HCL native Terraform. Adaptor ini adalah contoh lengkap dari bentuk tahap render: evaluator Rego Wasm-native yang sama dengan mesin di dalam compiler, dan konvensi pengumpulan deny / warn / audit yang sama, dipetakan ke tiga tingkat keparahan verdict yang sama, bernalar atas berkas hasil render alih-alih atas graf build.

Adaptor ini independen terhadap bentuk keluaran di seluruh target YAML/JSON. Adaptor mem-parsing konten setiap artefak sebagai satu atau beberapa dokumen YAML atau JSON — YAML adalah superset dari JSON, sehingga templat JSON seperti stack CloudFormation di-parsing melalui parser yang sama — dan mengekspos dokumen hasil parsing kepada kebijakan bersama konten mentahnya. Kebijakan bernalar atas keluaran render terstruktur dari target semacam itu dengan Rego biasa: input.artifacts[_].documents[_] menghasilkan dokumen hasil parsing (services dari berkas Docker Compose, Resources dari templat CloudFormation), input.artifacts[_].content menghasilkan teks mentah, dan objek settings milik lampiran adalah dokumen data Rego. Kebijakan require-approved- registry atas keluaran Docker Compose, misalnya, menolak setiap layanan yang image-nya tidak membawa prefiks registry.

Adaptor ini juga bernalar atas keluaran render HCL native Terraform. Berkas .tf native bukan YAML maupun JSON, sehingga adaptor memproyeksikannya ke objek kanonis yang sama dengan hasil parsing berkas Terraform-JSON (.tf.json): kebijakan membaca atribut resource di input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — untuk instans RDS, input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage — dengan cara yang sama, apa pun bentuk Terraform yang dihasilkan compiler. Tipe atribut dipertahankan (angka tetap angka, boolean tetap boolean), dan ekspresi Terraform yang belum terselesaikan tetap berupa string dalam bentuk ${ ... }. Badan Terraform-JSON (.tf.json, .auto.tfvars.json) di-parsing melalui jalur YAML/JSON tanpa perubahan, dan berkas templat Terraform (.tftpl) — teks templat, bukan konfigurasi mandiri — tidak diproyeksikan dan memunculkan parse_error seperti konten non-terstruktur lainnya.

Daftar itu menyatakan apa yang diterima parser adaptor, bukan apa yang dihasilkan compiler. Keduanya bukan himpunan yang sama, dan berkas variabel yang dimuat otomatis adalah kasus ketika keduanya berbeda: compiler tidak menghasilkan overlay semacam itu di jalur mana pun — input modul bersumber adalah argumen dari blok modul komponen tersebut dalam konfigurasi root boundary — sehingga bentuk itu hanya mencapai tampilan kebijakan ketika modul vendored menyertakan miliknya sendiri, yang disalin apa adanya ke keluaran oleh jalur bersumber. Kebijakan yang ditulis dengan harapan compiler menghasilkan berkas semacam itu tidak akan pernah terpicu.

Ketika konten artefak tidak dapat di-parsing, adaptor tidak diam-diam mengizinkannya: adaptor menyimpan konten mentah, tidak mengekspos dokumen hasil parsing untuk artefak itu, dan mencatat pesan parser di bawah input.artifacts[_].parse_error, sehingga kebijakan dapat menghentikan build secara eksplisit pada artefak yang cacat. Seperti pada mesin Rego di dalam compiler, kebijakan yang memanggil builtin yang tidak diimplementasikan oleh evaluator tertanam gagal secara terang-terangan — kesalahan yang menyebut nama plugin, tidak pernah izin diam-diam.

Keluaran Kubernetes — adaptor render Kubewarden

Adaptor render Kubewarden menjalankan kebijakan admission bergaya Kubewarden atas manifest Kubernetes hasil render. Adaptor ini menyerap kontrak admission-review Kubernetes ke arah dalam: kebijakan Kubewarden menerima permintaan yang membungkus satu objek dan mengembalikan respons terima-atau-tolak. Pada tahap render, keluaran build sudah merupakan sekumpulan resource Kubernetes, sehingga tahap itu menjadi tempat alami untuk menjalankan kebijakan berbentuk admission. Untuk setiap objek hasil render, adaptor menurunkan field admission dari objek hasil parsing itu sendiri, membungkus objek dalam permintaan berbentuk admission-review di dalam guest, menjalankan kebijakan, dan memetakan respons ke verdict: penolakan menjadi satu verdict; penerimaan tidak menghasilkan apa pun. Kebijakan referensi yang disertakan adalah aturan require-label — setiap objek harus membawa kunci label yang disebut oleh settings — sebuah pola Kubewarden yang umum.

Cakupan bersama adaptor tahap render

  • Tahap render, satu bentuk keluaran per adaptor. Adaptor tahap render bernalar atas artefak hasil render, bukan graf IR, dan menargetkan bentuk keluaran yang di-parsing-nya — YAML/JSON dan HCL native Terraform untuk adaptor render Rego referensi, objek Kubernetes untuk adaptor Kubewarden. Kebijakan tahap graf, atau kebijakan atas bentuk keluaran yang tidak di-parsing oleh adaptor bawaan mana pun, adalah guest yang berbeda.
  • Hanya validasi. Adaptor tahap render menerima atau menolak; adaptor tidak pernah mengembalikan objek yang dimutasi. Objek hasil mutasi dari kebijakan yang memutasi diabaikan — compiler tidak pernah menulis ulang keluaran hasil render berdasarkan verdict kebijakan. Kebijakan memutuskan; kebijakan tidak menyunting.

Melampirkan kebijakan

Operator melampirkan plugin tata kelola melalui daftar plugins.governance dalam konfigurasi workspace (.aggrega-config.yaml). Setiap entri menyebutkan sebuah plugin, role tempat plugin itu dilampirkan, dan, secara opsional, kanal with yang memasok aturan dan parameter penyetelannya:

plugins:
governance:
- uri: <resolvable-plugin-reference>
role: ir-verdict
with:
sources:
- ./policies/replicas.rego
settings:
max_replicas: 3

uri di-resolve ke plugin tersebut. Host membaca setiap berkas sources pada waktu build dan menyerahkan byte-nya kepada guest, serta meneruskan settings apa adanya. Build tanpa plugin tata kelola yang dilampirkan menjalankan socket sebagai no-op, sehingga lampiran sepenuhnya bersifat aditif terhadap workspace.

Satu plugin yang melayani beberapa peran dilampirkan sekali per peran, masing-masing lampiran dengan aturan dan pengaturannya sendiri:

plugins:
governance:
- uri: governance/rego:<version>
role: label-transform
with:
sources:
- ./policies/tagging.rego
- uri: governance/rego:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.rego
settings:
translation:
- key: blocked
severity: halt

Versi mana yang disebut lampiran. Sebuah uri menyebut entitas Plugin — koordinat <pluginType>/<name> dan, setelah titik dua, sebuah versi — dan versi tersebut ikut serta dalam resolusi. Untuk dua engine yang dikompilasi ke dalam CLI, entitasnya berasal dari salah satu dari dua tempat. Setiap rilis compiler memublikasikan entitas Plugin untuk governance/rego dan governance/cel pada versinya sendiri, dan katalog pustaka standar memuatnya, masing-masing pada versi rilis yang memublikasikannya; workspace membacanya dari direktori katalog yang dicantumkannya. Biner aggrega membawa satu entitas untuk masing-masing engine, pada versi rilisnya sendiri dan tidak ada versi lain. Lampiran yang menyebut versi yang tidak dibawa keduanya, dan yang belum diambil oleh pull mana pun ke dalam cache konten, menghentikan build dengan E0137, dengan menyebut referensinya.

Jadi lampiran menyebut versi yang dibawa katalog yang dibaca workspace. Versi itu juga ter-resolve dari katalog di bawah rilis aggrega selain rilisnya sendiri, sedangkan versi yang hanya dibawa biner — versi rilisnya sendiri — hanya ter-resolve dengan rilis itu saja, baik di peran verdict maupun di peran transform. Di peran transform, pull menyematkan versi yang di-resolve-nya di lockfile, dan menolak dengan E0103 versi yang tidak dibawa oleh katalog yang dibaca workspace maupun oleh biner. Versi memilih entitas Plugin, yang mencatat ekspor dan batas runtime plugin, bukan engine-nya: begitu referensi ter-resolve, engine yang berjalan adalah yang dikompilasi ke dalam biner yang menjalankan build, karena plugin yang tertanam di biner adalah tempat pertama modul plugin dibaca. Plugin governance yang dideklarasikan sendiri oleh workspace — entitas Plugin di direktori katalognya sendiri, dengan .wasm-nya di sampingnya — disebut pada versi yang dicatat entitas tersebut.

Setiap peran memilih fungsi entri bawaan — verdict_ir untuk peran yang menilai graf, verdict_render untuk peran yang menilai artefak hasil render, mutate untuk peran pembentuk label, transform_annotations untuk peran penyisip anotasi — dan sebuah lampiran dapat mengarahkan peran ke export lain dengan function:. Host menolak dispatch ke export yang tidak dideklarasikan guest dalam laporan diri describe()-nya, sehingga lampiran yang menyebutkan peran yang tidak dilayani guest-nya dilaporkan berdasarkan nama, sebelum guest berjalan, alih-alih diam-diam tidak melakukan apa pun.

function: menyebut sebuah ekspor pada plugin yang disebut oleh uri. Lampiran dalam peran putusan — ir-verdict atau render-verdict — yang menyebut function: tanpa uri: menyebut fungsi yang tidak berada pada plugin mana pun, sehingga konfigurasi ditolak saat dibaca, dengan E0224, dengan menyebutkan berkas dan posisi entri dalam daftarnya: tambahkan uri dari plugin yang mengekspor fungsi tersebut.

Daftar plugins.governance memiliki pendamping aditif, plugins.governance_append: entri dalam pendamping digabungkan ke daftar governance yang telah di-resolve pada setiap lapisan konfigurasi, sehingga konfigurasi workspace atau global menyusun lampiran kebijakan alih-alih menutupi daftar dasar.

Overlay milik CI

Di samping .aggrega-config.yaml yang ditulis secara manual, pipeline otomatis dapat memiliki berkas overlay terpisah, .aggrega-config-append-ci.yaml. Berkas ini ada agar pipeline dapat melampirkan kebijakan (atau konfigurasi bernilai daftar lainnya) yang dikendalikannya tanpa pernah mengedit konfigurasi dasar yang ditulis manual oleh pengembang — pipeline dapat menimpa berkas overlay miliknya sendiri secara keseluruhan.

Overlay ini sepenuhnya aditif. Overlay divalidasi terhadap skema konfigurasi yang sama dengan berkas dasar, dan untuk setiap field bernilai daftar, entrinya digabungkan ke daftar yang telah di-resolve. Overlay hanya dapat menambah: overlay tidak dapat menghapus entri dasar dan tidak dapat menimpa nilai dasar secara skalar — kunci skalar atau map yang dibawanya tidak memiliki makna aditif dan diabaikan (serta disebutkan dalam peringatan resolusi) alih-alih diterapkan. Selain itu, overlay tidak pernah menjadi jangkar root workspace: hanya .aggrega-config.yaml yang membawa blok workspace: yang melakukannya, sehingga menaruh overlay ke dalam direktori menambahkan lampiran tanpa mengubah tempat workspace dimulai.

Hal ini memberi pipeline sambungan yang bersih untuk menegakkan kebijakan tingkat organisasi: pipeline menaruh .aggrega-config-append-ci.yaml yang menyebutkan plugin kebijakan wajib, dan lampiran tersebut digabungkan di atas apa pun yang ditulis pengembang, tidak pernah menggantikannya.

# .aggrega-config-append-ci.yaml — owned by the pipeline, additive only
plugins:
governance_append:
- uri: <organization-policy-plugin-reference>
role: render-verdict
with:
settings:
required_label: app.kubernetes.io/name

examples/policy-org-overlay/ membangun satu workspace dengan lampiran sebuah tim, lampiran sebuah organisasi yang ditambahkan melalui governance_append di file konfigurasi global, dan lampiran sebuah pipeline yang ditambahkan melalui overlay ini, lalu memeriksa apa yang dicetak setiap kombinasi dan apakah kombinasi itu selesai.

Menguji policy sebelum policy itu mengendalikan build

Aturan Rego yang menyebut path yang tidak dibawa payload perannya bukanlah error: path tersebut tidak terdefinisi, aturan tidak pernah terpenuhi, dan build selesai seolah-olah policy mengizinkannya. Jadi policy baru mendapatkan halt dalam tiga langkah: pasang dengan severitas yang melapor tanpa menghentikan, periksa setiap path yang disebutnya terhadap payload yang diterima perannya, dan baca apa yang dilaporkannya pada build yang akan dinilainya.

Perintah di bawah ini dijalankan dalam salinan examples/policy-org-overlay/ yang .aggrega-config.yaml-nya memasang satu policy baru sebagai pengganti policy tim. Policy ini dimaksudkan untuk menolak datastore yang berjalan dengan ketersediaan tinggi dimatikan, dan aturannya disalin dari policy pembentuk label:

package datastores
import rego.v1
deny contains msg if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v is a datastore running with high availability off", [id])
}

Pasang agar policy melapor. Policy mengumpulkan di bawah deny, yang secara default menghentikan build. translation yang hanya menyebut deny, pada warn, melaporkan setiap keputusannya sebagai peringatan dan membiarkan build selesai; info justru mencatatnya. Policy itu sendiri tetap seperti saat akan diberlakukan:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/datastore-ha.rego
settings:
translation:
- key: deny
severity: warn

Tulis payload, lalu cari path di dalamnya. Setelah sebuah build mengisi lockfile milik Release,

Terminal window
aggrega build --release release.yaml --dry-run --policy-input payloads

menulis payload yang diserahkan setiap peran kepada lampirannya ke payloads/ dan tidak menulis apa pun selain itu, sambil melaporkan, dengan <workspace> mewakili direktori tempat build dijalankan:

policy input: 4 file(s) written to <workspace>/payloads
[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]

Keempatnya adalah annotation-transform.json, ir-verdict.json, label-transform.json, dan render-verdict.json; peran tanpa lampiran apa pun juga ditulis, sehingga policy dapat diperiksa terhadap perannya sebelum dipasang di mana pun. Di ir-verdict, label-transform, dan annotation-transform, file tersebut adalah dokumen input yang dibaca policy, sehingga setiap path yang disebut aturan dapat dibaca darinya dengan alat JSON apa pun sebelum aturan itu dipercaya:

Terminal window
jq '.graph.nodes' payloads/ir-verdict.json
# null
jq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json
# ["db","web"]
jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json
# {"enabled":false,"read_replicas":0}

Node yang dicari aturan tidak ada di sana: input.graph.nodes adalah tempat peran pembentuk label membawanya, dan di ir-verdict node-node itu berada di input.graph.spec.nodes (lihat Apa yang diekspos payload setiap peran). File itu juga menyatakan apa yang harus diputuskan aturan yang telah diperbaiki: db adalah datastore, ketersediaan tingginya mati, dan ia harus dilaporkan.

Jika OPA terpasang, policy Rego dievaluasi langsung terhadap file yang sama: opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Engine Rego di dalam compiler adalah implementasi independen, sehingga build tetap merupakan evaluasi yang menentukan: builtin yang tidak diimplementasikannya menghentikan build alih-alih dievaluasi.

Di render-verdict, file tersebut bukan input milik policy. Setiap artefak di dalamnya membawa path, content, dan format-nya; documents yang dibaca aturan di-parse dari konten oleh engine policy setelah menerima payload, sehingga aturan atas documents tidak menemukan apa pun di file itu. Policy di peran tersebut diuji di tempat engine mem-parse-nya: di dalam build, seperti yang ditunjukkan langkah berikutnya.

Jalankan build, dan bandingkan apa yang dilaporkannya dengan apa yang dikatakan payload. Dengan path yang disalin,

Terminal window
aggrega build --release release.yaml --auto-pull

selesai dan tidak melaporkan apa pun:

Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Payload memuat datastore dengan ketersediaan tinggi mati, dan policy tidak mengatakan apa pun tentangnya: diam itulah kesalahannya, dan tidak ada hal lain di build yang menunjuk ke sana. Dengan aturan yang membaca input.graph.spec.nodes, perintah yang sama melaporkan db dan selesai:

policy plugin "rego" warning: db is a datastore running with high availability off
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: the build's time and the line naming the dist/ directory it wrote]

Menambahkan --dry-run melaporkan verdict yang sama dan tidak menulis dist/, sehingga siklus ini berjalan terhadap workspace tanpa mengganggu keluarannya.

Aturan yang sama yang ditulis untuk engine CEL tidak gagal secara diam-diam. Membaca kunci yang tidak dibawa payload merupakan kesalahan evaluasi di sana, sehingga dengan path yang disalin, di policies/datastore-ha.cel yang dipasang dengan translation yang sama,

{
"deny": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore"
&& input.graph.spec.infra_mapping[n].ha.enabled == false)
.map(n, n + " is a datastore running with high availability off"),
}

menghentikan build bahkan pada warn. Perintah itu keluar dengan 1, dan baris terakhirnya menyebut file policy dan kuncinya:

ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodes

Policy render-verdict diuji dengan cara yang sama. Dipasang di render-verdict dalam workspace yang sama, dengan translation yang sama, aturan yang menolak service Compose yang memublikasikan port di host

package published
import rego.v1
deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
count(service.ports) > 0
msg := sprintf("%v publishes a port on the host", [name])
}

melaporkan satu-satunya service yang melakukannya:

policy plugin "rego" warning: web publishes a port on the host
[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]

Lalu berlakukan. Menghapus translation mengembalikan deny ke halt, dan build yang melaporkan db kini berhenti karenanya, keluar dengan 1, dan tidak menulis dist/:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db is a datastore running with high availability off
caused by: policy violation

Lampiran yang melapor tidak perlu dihapus di semua tempat sekaligus. Satu file konfigurasi dapat mempertahankan translation lampirannya pada warn sementara overlay pipeline memasang policy yang sama dengan deny pada halt, dan begitulah cara examples/policy-org-overlay/ meluncurkan aturan organisasi: peringatan pada build pengembang, dan alasan build pipeline berhenti.

Menjalankan kebijakan di CI, atas keluaran build

Semua yang dijelaskan di atas memasang kebijakan di dalam build. Ada rute kedua, dan rute ini tidak memerlukan apa pun dari socket: jalankan alat Anda sendiri di pipeline, atas berkas yang ditulis oleh build.

Ini berfungsi karena apa yang dihasilkan sebuah build. Target Kubernetes dan Compose menulis YAML; target Terraform menulis HCL native, atau JSON dalam bentuk .tf.json-nya. Itulah format yang sudah dibaca oleh alat konfigurasi di ekosistem — dan aggrega build menulis berkas biasa ke sebuah direktori, tanpa format pembungkus, tanpa indeks, dan tanpa apa pun yang perlu dibongkar. Jadi alat yang membaca YAML, JSON, atau HCL berjalan atas keluaran build dengan cara yang sama seperti atas konfigurasi yang ditulis tangan oleh seseorang, dan Aggrega tidak menambahkan socket, jenis plugin, maupun kunci konfigurasi untuk itu.

Jadi korpus aturan yang sudah ada tidak perlu di-port. Jika Anda sudah menyimpan aturan di Conftest, Kyverno CLI, kubeconform, Checkov, atau OPA, aturan tersebut berjalan atas keluaran build Aggrega apa adanya, dan alat yang mengevaluasinya adalah alat yang sudah dipasang oleh pipeline Anda.

Dua skrip aturan siap pakai, masing-masing dengan langkah pipeline yang memanggilnya dan kedua penolakan yang dihasilkannya atas build nyata, tersedia di examples/policy-in-ci/. Skrip tersebut menggunakan yq dan tidak ada yang lain, sehingga dapat dijalankan tanpa toolchain kebijakan terpasang; pola yang ditunjukkannya — membaca direktori keluaran, memutuskan, keluar dengan kode bukan nol sambil menyebut artefak yang melanggar — adalah pola yang diambil oleh alat apa pun dalam posisi ini.

Rute mana yang tepat untuk sebuah aturan

Kedua rute sama-sama kelas utama, dan sebuah workspace umumnya menggunakan keduanya. Yang menentukan adalah apa yang perlu dilihat oleh aturan dan kapan aturan itu perlu bertindak.

Pasang aturan pada socket jika:

  • build sama sekali tidak boleh menghasilkan artefak tersebut. Kebijakan ir-verdict berjalan pada gerbang analisis statis, sebelum apa pun di-render, sehingga penghentian di sana tidak meninggalkan apa pun yang tertulis — tidak ada berkas keluaran untuk ditinjau, dikarantina, atau tanpa sengaja diterapkan. Pemeriksaan pipeline mau tidak mau berjalan setelah berkas ada.
  • aturan memerlukan fakta yang hanya dimiliki build. Peran ir-verdict membaca graf yang telah dirakit: node, edge beserta socket-nya, setiap pemasangan beserta slot yang diisinya, nilai mana yang dinyatakan sensitif oleh penulis, dan jalur routing. Tidak satu pun dari itu bertahan hingga keluaran yang di-render — manifest Kubernetes tidak mencatat socket mana yang mengirimkan suatu nilai atau Feature mana yang menyumbangkan suatu resource — sehingga aturan tentang topologi atau provenance hanya memiliki satu tempat, yaitu socket.
  • aturan harus berlaku di mana pun build berjalan. Pemasangan governance berada di konfigurasi workspace, sehingga berlaku untuk build lokal developer sama seperti untuk build pipeline. Pemeriksaan pipeline berlaku di tempat pipeline berjalan.
  • aturan harus membentuk build alih-alih menilainya. Hanya peran transform yang melakukannya, dan hanya karena operator memasangnya.

Jalankan di CI jika:

  • aturan sudah ada, di alat yang dijalankan dan ditinjau oleh tim Anda, atas format yang sudah di-parse oleh alat tersebut. Menuliskannya ulang sebagai konten kebijakan socket adalah pekerjaan yang pada akhirnya tidak menambah cakupan baru.
  • aturan menyangkut artefak sebagaimana akan diterima oleh target — set berkas akhir, setelah setiap transform, dalam bentuk yang diterapkan. Itu juga subjek peran render-verdict, sehingga pada poin ini saja kedua rute melihat hal yang sama dan pilihannya bergantung pada poin lainnya.
  • temuan ditujukan bagi peninjau alih-alih bagi build. Pipeline yang menerbitkan artefak dan temuan secara berdampingan memberi peninjau keduanya; build yang dihentikan hanya memberinya sebuah pesan.
  • pemeriksaan menjangkau lebih dari satu build — membandingkan keluaran build ini dengan build sebelumnya, dengan status live sebuah cluster, atau dengan inventaris yang tidak dibawa oleh payload build mana pun. Kebijakan pada salah satu peran verdict melihat build tempat ia dipasang, dan hanya itu yang dilihatnya.

Kedua rute saling melengkapi alih-alih bersaing: invarian topologi menghentikan build dari ir-verdict, lalu pipeline yang sama menjalankan aturan artefak yang sudah ada di estate atas apa yang ditulis build tersebut.

Rujukan silang

  • plugin-contract.md — penempatan socket dalam pipeline, bentuk data bertipe yang dibawanya, dan sandbox tempat setiap plugin berjalan.
  • plugin-developer-guide.md — penulisan plugin, laporan diri describe(), dan siklus hidup publish → pull → build.
  • ../entities/plugin.md — entitas Plugin yang membawa plugin ke dalam katalog.
  • ../cli/aggrega-build.md — perintah build yang menjalankan socket.
  • ../schema/other/aggrega-config.md — skema konfigurasi workspace, termasuk permukaan pemasangan plugins.governance.
  • ../examples/policy-in-ci/ — dua skrip aturan yang dapat dijalankan atas keluaran build, beserta langkah pipeline untuk masing-masing.
  • ../examples/policy-data-class-route/ — satu aturan ir-verdict atas rute, ditulis untuk engine Rego, engine CEL, dan OPA di balik guest adapter referensi, dipasang per build dengan satu berkas --config per engine, beserta skrip yang memeriksa bahwa ketiganya mencapai hasil yang sama pada setiap Release.