Kebijakan atas output yang dirender: satu aturan internal, empat target, dua mesin
Satu aturan internal, yang dilampirkan pada peran render-verdict, menilai berkas yang ditulis build untuk empat target dan menolak pelanggaran yang ditanam pada masing-masing. Aturan ini memiliki dua klausa:
Setiap image kontainer menyebut versi tetap — tag selain
latest, atau digest. Setiap instans basis data menyimpan datanya dalam keadaan terenkripsi.
Workspace ini mem-build satu Aggregate untuk empat target — Kubernetes melalui Helm, Docker Compose, Terraform, dan CloudFormation. Peran render-verdict menilai berkas yang ditulis build, setelah setiap target merendernya, dan aturan membaca bentuk output milik setiap target: image di objek Kubernetes dan di berkas Compose, instans RDS di berkas Terraform dan di template CloudFormation. Setiap target memiliki satu Release yang lolos dan satu Release dengan pelanggaran yang ditanam di dalamnya, yang ditolak aturan.
Aturan ini ditulis dua kali, sekali untuk setiap mesin kebijakan yang dikompilasi ke dalam CLI — Rego dan CEL — dan kedua salinan sepakat pada setiap build di sini. Sebuah skrip di samping Releases mem-build keenam belas kombinasi dan memeriksa setiap hasilnya.
aggrega buildkebijakan Anda
dipasang ke kompiler
lolos
berkas ditulis
siap ditinjau dan di-deploy
gagal
build dihentikan
Kebijakan dapat menghentikan build dan menyebutkan apa yang perlu diperbaiki. Kebijakan tidak pernah mengubah berkas Anda agar lolos.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
db | core/datastore/postgres | basis data pesanan |
report | core/compute/task | job laporan yang membaca db, dimulai secara manual: job ini membawa core/manual-trigger, sehingga tidak ada eksekusi yang dimulai ketika Release di-deploy |
report membaca alamat, port, dan nama basis data melalui koneksi database-nya, sebagai DB_HOST, DB_PORT, dan DB_NAME. Aggregate adalah berkas yang sama untuk setiap build; setiap Release menyebut Manifest yang memilih target:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, sebuah StatefulSet | helm/task, sebuah CronJob yang ditahan dalam keadaan ditangguhkan |
manifest-compose.yaml | compose/postgres, sebuah service | compose/task, sebuah service di balik profile |
manifest-terraform.yaml | terraform/postgres-rds, sebuah instans RDS | terraform/task-ecs, sebuah definisi task Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, sebuah instans RDS | cloudformation/task-ecs, sebuah definisi task Amazon ECS |
Setiap Recipe di sini merender dari katalog saja: basis data Kubernetes disintesis alih-alih diambil sebagai chart, isi basis data Terraform ditulis oleh Recipe-nya, dan modul task Terraform disimpan di samping Recipe-nya. Jadi setiap build berjalan offline.
Delapan Releases
| Release | target | apa yang ditemukan aturan | build |
|---|---|---|---|
release-helm.yaml | Kubernetes | report menjalankan registry.example.com/orders-report:1.4.2 | selesai |
release-helm-unpinned.yaml | Kubernetes | report menjalankan image yang sama dengan tag latest | dihentikan |
release-compose.yaml | Docker Compose | report menjalankan registry.example.com/orders-report:1.4.2 | selesai |
release-compose-unpinned.yaml | Docker Compose | report menjalankan image tanpa tag | dihentikan |
release-terraform.yaml | Terraform | instans dienkripsi dengan kunci yang disebut Release | selesai |
release-terraform-unencrypted.yaml | Terraform | Release tidak menyebut kunci, sehingga instans tidak dienkripsi | dihentikan |
release-cloudformation.yaml | CloudFormation | Release mengaktifkan StorageEncrypted | selesai |
release-cloudformation-unencrypted.yaml | CloudFormation | Release membiarkannya nonaktif | dihentikan |
Image ditentukan oleh Release: core/compute/task tidak mengemas perangkat lunak apa pun, sehingga Release menyebut image yang dieksekusi sebuah eksekusi di bawah infra.image, termasuk tag-nya. Pada kedua target AWS, enkripsi basis data juga ditentukan oleh Release. Terraform Recipe membaca infra.overrides.kms_key_id dan, jika nilai itu ditetapkan, merender storage_encrypted = true di samping kunci; CloudFormation Recipe membaca infra.overrides.StorageEncrypted dan KmsKeyId dengan nama properti resource itu sendiri. Release yang tidak menetapkan keduanya merender instans tanpa atribut enkripsi sama sekali, dan itulah yang dilakukan Releases yang ditanami pelanggaran.
Basis data Kubernetes dan Compose menjalankan image postgres:16, sebuah tag tetap, sehingga aturan menilainya dan meloloskannya di setiap Release.
Melampirkan aturan
.aggrega-config.yaml menyebut hub sebagai registry-nya dan tidak menyebut direktori katalog apa pun, serta tidak mendeklarasikan lampiran tata kelola. Aturan dilampirkan oleh berkas yang disebut build dengan --config: governance-rego.yaml untuk mesin Rego, governance-cel.yaml untuk mesin CEL. Berkas untuk Rego berbunyi:
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config menyebut berkas konfigurasi global untuk eksekusi tersebut, menggantikan berkas yang seharusnya dibaca mesin, dan .aggrega-config.yaml milik workspace ini tetap ditumpuk di atasnya. Daftar plugins.governance di berkas workspace akan menggantikan daftar yang dibawa berkas yang disebut, itulah sebabnya berkas workspace tidak mendeklarasikannya. 0.9.0 adalah versi entitas Plugin setiap mesin di katalog pustaka standar. Kedua mesin dikompilasi ke dalam CLI — aggrega plugin list mencantumkan governance/rego dan governance/cel di antara bawaan yang tertanam — sehingga tidak ada build di sini yang mengambil plugin.
Apa yang dibaca kebijakan render-verdict
Kebijakan pada render-verdict membaca berkas yang ditulis build di input.artifacts, satu entri per berkas, diurutkan menurut path. Masing-masing membawa:
path— path berkas di bawahdist/, sepertiterraform/modules/db/main.tf;content— teks berkas, sebagaimana ditulis;format— format yang dideklarasikan provider target untuk berkas tersebut:yamluntuk berkas Compose,jsonuntuk template CloudFormation,hcluntuk setiap berkas Terraform, termasuk isi basis data yang ditulis Recipe-nya. Jika tidak ada yang mendeklarasikannya, nilainya string kosong, seperti untuk berkas Kubernetes di sini;documents— konten berkas yang di-parse menjadi struktur, sebagai daftar dokumen: satu untuk setiap berkas di sini;parse_error— hanya ada pada berkas yang tidak dapat di-parse, menggantikandocuments.
Di samping berkas, input.sources memuat berkas kebijakan milik lampiran itu sendiri, dan input.settings memuat pengaturannya — objek kosong di sini, karena lampiran ini tidak mendeklarasikan pengaturan apa pun.
aggrega build --release <release> --dry-run --policy-input <dir> menulis payload yang diterima setiap peran ke dalam <dir> dan tidak menulis apa pun lagi. Pada render-verdict, berkas itu adalah apa yang diterima mesin, bukan apa yang dibaca kebijakan: setiap berkas di dalamnya membawa path dan content-nya serta format yang dideklarasikan provider-nya, dan mesin mem-parse documents dari konten setelah menerima payload. Jadi berkas itu mencantumkan berkas yang akan diperlihatkan kepada aturan, meskipun tidak dengan dokumennya. Setelah build release-terraform.yaml mengisi lockfile-nya:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Path yang dibaca aturan di dalam documents diperiksa dalam build, tempat mesin telah mem-parse-nya. Tidak ada berkas yang ditulis Recipes ini yang gagal di-parse, sehingga tidak ada berkas di sini yang membawa parse_error. Setiap klausa aturan ini membaca documents, sehingga berkas yang tidak berhasil di-parse akan meloloskannya tanpa diperiksa; aturan yang tidak boleh membiarkan hal itu terjadi menambahkan klausa yang menolak berkas yang membawa parse_error.
Cara setiap klausa membaca bentuk targetnya
Setiap klausa menyebut bentuk yang dibacanya, dan berkas berbentuk lain tidak membawa apa yang disebut klausa itu: di Rego path tersebut tidak terdefinisi dan klausa tidak terpenuhi. Jadi satu aturan berjalan atas output setiap target dan setiap klausa hanya menemukan miliknya sendiri.
Compose menulis satu berkas yang dokumennya memberi kunci setiap service menurut nama di bawah services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Objek Kubernetes membawa kontainernya dalam template pod, yang oleh CronJob ditempatkan satu tingkat lebih dalam daripada workload lain, di bawah spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform dalam HCL native menyarangkan blok di bawah tipenya lalu di bawah setiap labelnya, dan label terakhir memuat daftar blok, karena blok yang berbagi tipe dan label dikumpulkan ke dalam satu daftar. Jadi atribut sebuah instans berada satu indeks di bawah namanya, dan klausa menelusuri daftar tersebut:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}Daftar lebih penting di sini daripada untuk aturan yang mencari sebuah nilai, karena klausa ini menolak berdasarkan ketiadaan. Jika ditulis untuk satu blok — some name, block in doc.resource.aws_db_instance — block adalah daftar, block.storage_encrypted tidak terdefinisi padanya, dan not terpenuhi untuk apa pun yang tidak terdefinisi: klausa itu juga akan menolak release-terraform.yaml, yang instansnya terenkripsi, dengan pesan yang sama seperti Release yang ditanami pelanggaran.
Berkas .tf.json dibaca sebagaimana Recipe-nya menulisnya, dengan nama yang memuat blok itu sendiri, sehingga aturan yang ditulis untuk satu bentuk tidak membaca bentuk lainnya. Itulah sebabnya klausa membaca format terlebih dahulu: native_hcl mengambil berkas yang format-nya hcl, atau yang format-nya kosong dan namanya berakhiran .tf — berkas yang format-nya tidak dideklarasikan provider mana pun di-parse berdasarkan namanya, sehingga aturan juga mengenalinya dari namanya alih-alih melewatinya. Setiap berkas Terraform yang di-build di sini dideklarasikan hcl, sehingga tidak ada berkas di sini yang dikenali dari namanya. Recipes ini tidak menulis berkas .tf.json, sehingga aturan tidak membaca bentuk lain. Apa yang diekspos payload setiap peran menjelaskan kedua bentuk tersebut.
CloudFormation menulis satu template yang resource-nya diberi kunci menurut ID logis di bawah Resources, masing-masing dengan Type dan Properties-nya:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Instans tanpa properti StorageEncrypted, atau dengan properti itu ditetapkan ke apa pun selain true, ditolak: not … == true terpenuhi untuk keduanya.
Mengapa aturan CEL ditulis secara berbeda
policies/house-rule.cel menyatakan dua klausa yang sama dan mencapai verdict yang sama pada setiap build di sini. Aturan ini ditulis secara berbeda di tiga tempat, masing-masing karena alasan dari sisi mesin.
Aturan ini menguji setiap kunci sebelum membacanya. Membaca kunci yang tidak dibawa sebuah nilai adalah kesalahan evaluasi di CEL, bukan path yang tidak terdefinisi, dan kesalahan menghentikan build. Berkas setiap target tidak memiliki kunci yang dibawa berkas target lain — objek Kubernetes tidak memiliki services, berkas Compose tidak memiliki kind — sehingga setiap klausa menguji kunci yang dibacanya dengan has() terlebih dahulu:
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Tanpa uji has(d.services), aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull berhenti, apa pun image yang dijalankan objek Kubernetes, keluar dengan 1, dan tidak menulis dist/, dan baris yang melaporkan kesalahan menyebut berkas kebijakan dan kuncinya:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesAturan ini melaporkan satu pelanggar per berkas. Kunci keputusan mengumpulkan pesan, dan ekspresi CEL tidak memiliki cara untuk menggabungkan daftar yang dibangunnya per berkas menjadi satu daftar. Jadi setiap klausa CEL melaporkan satu pelanggar di setiap berkas: kontainer pertama dari template pod, atau, di antara service, instans, dan resource yang diberi kunci menurut nama oleh sebuah berkas, yang namanya paling awal dalam urutan. Comprehension menelusuri map tanpa urutan tetap, sehingga memilih berdasarkan nama adalah hal yang menjaga pesan tetap sama dari satu build ke build berikutnya. Aturan Rego melaporkan setiap pelanggar. Dengan dua service yang tidak dipatok dalam satu berkas Compose, mesin Rego berhenti dengan dua pesan dan mesin CEL dengan satu, untuk service yang namanya paling awal dalam urutan; dengan satu, seperti di setiap Release di sini, keduanya berhenti dengan pesan yang sama.
Aturan ini mengulang dirinya. CEL tidak menyediakan cara untuk menamai sub-ekspresi, sehingga uji yang dipakai dua kali ditulis dua kali, dan uji image dijabarkan di setiap klausa alih-alih dipanggil seperti unpinned milik Rego.
Kedua berkas ini adalah duplikat-hampir yang disengaja, masing-masing ditulis sendiri dari aturan di atas alih-alih dihasilkan satu dari yang lain, sehingga build tempat kedua mesin berbeda pendapat memperlihatkan perbedaan itu.
Verdict tidak pernah mengubah output
Kebijakan pada render-verdict menerima build atau menolaknya. Kebijakan ini diberi berkas yang ditulis build dan mengembalikan verdict; tidak ada yang dikembalikannya yang diterapkan pada berkas tersebut. Jadi sebuah build kontrol menghasilkan berkas yang sama, byte demi byte, dengan aturan dilampirkan maupun tanpa aturan, dan check.sh membandingkan kedua pohon pada setiap eksekusi. Build yang ditolak sama sekali tidak menulis dist/. Untuk memperbaiki penolakan, Release diubah — tag yang dipatok, kunci enkripsi — dan build berikutnya dinilai kembali.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example policy-render-verdictKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd policy-render-verdictBuild
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Tukar governance-rego.yaml dengan governance-cel.yaml untuk menjalankan aturan yang sama pada mesin CEL, dan terraform dalam nama berkas Release dengan helm, compose, atau cloudformation, beserta Releases mereka yang ditanami pelanggaran, release-helm-unpinned.yaml, release-compose-unpinned.yaml, dan release-cloudformation-unencrypted.yaml.
Katalog pustaka standar menyediakan setiap Component, Recipe, Feature, dan FeatureRecipe di sini dan memuat entitas Plugin kedua mesin. Semuanya di-resolve dari hub.aggrega.ai, registri bawaan yang disebutkan .aggrega-config.yaml. Dengan checkout katalog (cara mendapatkannya) yang disebutkan melalui --catalog, tidak ada yang diambil dari registri, sehingga build berjalan offline. --auto-pull mengisi lockfile setiap Release selama build; lockfile dan output yang dirender dihasilkan, bukan dikirimkan.
Kontrol Terraform selesai. Release yang ditanami pelanggaran berhenti:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationSetiap pesan menyebut berkas yang dinilai aturan, sebagai path-nya di bawah dist/, dan pelanggar di dalamnya. Releases lain yang ditanami pelanggaran berhenti dengan cara yang sama:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedSetiap baris adalah baris setelah [POLICY_ERROR E0005] dalam output build-nya, ditampilkan dari margin kiri. Yang pertama berasal dari mesin Rego dan dua lainnya dari mesin CEL, masing-masing menyebut mesin yang melaporkannya; mesin yang lain mencetak pesan yang sama dengan namanya sendiri.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder Workspace belum berisi folder `policy-render-verdict`, panggil alat `scaffold` sekali dengan `example` diatur ke `policy-render-verdict` dan tanpa `dir`: alat ini menulis contoh ke folder `policy-render-verdict` yang baru. Kemudian panggil alat `cli-build`, yang menjalankan `aggrega build` dan menerima flag `--config`-nya, sekali untuk setiap Release, dengan urutan ini — `release-terraform.yaml` dan `release-terraform-unencrypted.yaml` — setiap kali dengan `workspace_root` diatur ke `policy-render-verdict`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `config` diatur ke `governance-rego.yaml`. Build kedua memang dimaksudkan untuk ditolak, jadi bacakan penolakannya kepada saya. Beri tahu saya file apa saja yang ditulis build pertama; file-file itu ada di bawah `policy-render-verdict/dist/`.Memeriksa setiap build
Pemeriksaan mandiri ini berjalan di checkout repositori dokumentasi, yang memuat skrip pembantu build bersama yang digunakannya; salinan yang ditulis oleh aggrega scaffold --example tidak menyertakan skrip pembantu tersebut.
./check.shcheck.sh mem-build setiap kontrol sekali tanpa kebijakan terlampir, sebagai referensi, lalu kedelapan Releases di bawah setiap mesin, melalui helper build-release. Sebuah kontrol harus selesai dan menulis berkas yang sama, byte demi byte, dengan referensinya; Release yang ditanami pelanggaran harus berhenti dengan E0005 dan pesan yang diharapkan untuknya, tanpa penolakan lain di sampingnya, dan tidak menulis dist/. Kedua mesin dituntut menghasilkan pesan yang sama. Skrip ini mencetak satu baris per build dan keluar dengan 1 jika ada hasil yang berbeda, sambil mencetak output build tersebut:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.Skrip ini menggunakan biner yang di-resolve oleh ./build-release.sh, sehingga AGGREGA_BIN memilihnya, dan argumen setelah -- diteruskan ke setiap build. Skrip ini menolak berjalan selama ada dist/ di direktori ini, karena skrip ini memindahkan pohon setiap build untuk membandingkannya, dan tidak meninggalkan satu pun; build-build tersebut mengisi lockfile direktori ini, seperti build mana pun. Status keluarnya adalah seluruh putusannya.
Bagian yang tidak ditafsirkan oleh kompiler
Compiler merender berkas setiap target, menyerahkannya kepada mesin yang dilampirkan sebagai teks beserta format yang dideklarasikan provider-nya, dan bertindak berdasarkan tingkat keparahan yang dibawa setiap verdict. Compiler tidak tahu apa itu tag image, bahwa latest berpindah, atau bahwa instans RDS seharusnya dienkripsi: makna-makna itu milik aturan. Untuk peran, payload, dan kunci keputusan, lihat soket tata kelola.
Berkas
aggregate.yaml— basis data dan job laporan yang tersambung dengannya.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— mengikat setiap tipe komponen dan Feature pemicu manual ke Recipes masing-masing pada satu target.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— satu kontrol dan satu pelanggaran yang sengaja ditanam per target..aggrega-config.yaml— registry bawaan; tanpa lampiran tata kelola.governance-rego.yaml,governance-cel.yaml— aturan yang dilampirkan dirender-verdictmelalui setiap engine, masing-masing disebutkan dengan--config.policies/house-rule.rego,policies/house-rule.cel— aturan tersebut, satu kali per engine.build-release.sh— membangun satu Release, sambil menampilkan perintahaggrega buildyang setara.check.sh— menjalankan dua puluh build dan memeriksa setiap hasilnya.