Kebijakan yang membentuk label: tingkat dukungan per lingkungan, dan putusan yang membacanya
Plugin tata kelola memberi label pada setiap komponen yang di-deploy workspace ini dengan pemiliknya, tingkat dukungan yang layak bagi lingkungannya, jadwal pencadangannya, dan tag singkat, sehingga tidak ada developer yang perlu mengetikkannya. Label diturunkan selama build oleh empat lampiran tata kelola:
- tiga pada peran
label-transform, yang membentuk label pada node build: kebijakan Rego yang membaca lingkungan Release, dan dua plugin pemberi tag yang dikompilasi ke dalam CLI,label-injectordanselector-tagger; - satu pada peran
ir-verdict, kebijakan Rego atas grafik build yang menghentikan build produksi yang di dalamnya ada node yang dibiarkan tanpa tingkat dukungan.
Dua Releases dari satu Aggregate berbeda pada lingkungannya, staging dan production, dan node-nya berakhir dengan label yang berbeda. Build ketiga, yang dijalankan check.sh dari salinan workspace ini yang kebijakannya mencakup satu kategori lebih sedikit, berhenti dan menyebutkan node yang terlewat.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
db | core/datastore/mariadb | database toko |
cache | core/datastore/redis | cache sesinya |
web | core/devtool/adminer | UI administrasi database, yang terhubung ke db |
Ketiganya dikompilasi ke Docker Compose, ke dalam dist/compose/docker-compose.yaml. Aggregate dan kedua Releases tidak menyebutkan label sendiri: setiap label di bawah ini ditulis oleh sebuah lampiran.
Keempat lampiran
Lampiran tersebut dipasang di .aggrega-config.yaml milik workspace ini, di bawah plugins.governance, sehingga setiap build yang dijalankan di sini menerapkannya:
| plugin | peran | apa yang ditulisnya | |
|---|---|---|---|
| 1 | governance/rego:0.9.0, dengan policies/support-tier.rego | label-transform | ops.example.com/environment pada setiap node; ops.example.com/support-tier pada setiap node yang kategorinya tercantum dalam pengaturannya |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner pada setiap node; backup.example.com/schedule pada setiap node dalam kategori datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag, dari map di policies/tags.yaml |
| 4 | governance/rego:0.9.0, dengan policies/production-support.rego | ir-verdict | tidak ada: menghentikan build, atau membiarkannya selesai |
0.9.0 adalah versi ketiga entitas Plugin di katalog pustaka standar; plugin-nya sendiri dikompilasi ke dalam CLI, dan build menyajikannya dari sana. aggrega build --release release-production.yaml --auto-pull --detail mencantumkan keduanya, untuk masing-masing dari ketiganya:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]Lampiran pada satu peran berjalan sesuai urutan pencantumannya, dan masing-masing membaca label yang ditulis lampiran sebelumnya: penyisip label menerima dua label yang ditulis kebijakan Rego, dan pemberi tag selektor menerima label tersebut serta label milik penyisip label. Putusan berjalan setelah ketiganya, atas grafik yang mereka tinggalkan.
Apa yang dibaca kebijakan label-transform
Kebijakan pada label-transform membaca node di input.graph.nodes, dengan id node sebagai kunci, masing-masing dengan:
component— Component yang diinstansiasi node, seperticore/datastore/mariadb;resolved_version— versi hasil resolve Component tersebut;labels— label yang dimiliki node saat kebijakan berjalan: label milik Component sendiri, dan label yang ditulis transformasi sebelumnya;values— nilai yang dideklarasikan instance node di Aggregate, tidak ada jika tidak mendeklarasikan satu pun. Di sini hanyadbyang mendeklarasikan satu,database: appdb.
Kebijakan ini membaca Release di input.compilation_context: release_name dan environment. Itulah yang memungkinkan satu kebijakan memutuskan secara berbeda per lingkungan.
Sebaliknya, kebijakan pada ir-verdict membaca seluruh grafik build, dan node-nya berada satu tingkat lebih dalam, di input.graph.spec.nodes. Aturan yang dipindahkan dari satu peran ke peran lain harus disunting, bukan disalin: dengan path yang salah, aturan itu tidak membaca apa pun dan tidak pernah terpicu. Payload ir-verdict tidak memuat compilation_context, sehingga putusan tidak dapat membaca lingkungan dari Release. Itulah sebabnya kebijakan pertama di sini juga menulis ops.example.com/environment pada setiap node: putusan membaca lingkungan dari label tersebut.
Untuk melihat payload alih-alih membaca tentangnya, build sekali agar lockfile tersedia, lalu:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsmenulis payload yang diterima setiap lampiran ke payloads/, satu file per lampiran ketika beberapa lampiran pada satu peran menerima payload yang berbeda — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — di samping satu file untuk setiap peran lain, dan tidak menulis apa pun selain itu.
Kebijakan Rego
policies/support-tier.rego mengumpulkan keputusannya di bawah labels, satu per label, dengan menyebutkan node, kunci label, dan nilainya:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}Pengaturannya adalah dokumen data kebijakan, dan berisi kosakata estate:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursApa yang ditulis setiap plugin bawaan
label-injector menerapkan daftar aturan. Node yang labelnya mencakup setiap pasangan di bawah match suatu aturan menerima setiap pasangan di bawah set-nya, ditambahkan, atau menggantikan nilai label yang sudah dimiliki node. match tanpa pasangan cocok dengan setiap node. Aturan dibaca dari pengaturan rules-nya, seperti di sini, atau, bila pengaturan tidak memuat aturan, dari file pertama di bawah sources yang memuatnya. Dua aturannya di sini memberi setiap node ops.example.com/owner: shop-team, dan memberi db serta cache, dua node dalam kategori datastore, backup.example.com/schedule: nightly. web berada dalam kategori devtool dan tidak mendapat jadwal pencadangan.
selector-tagger menulis satu label, selalu di bawah kunci tag. Nilainya berasal dari map nama Component ke tag, yang dibaca dari file di bawah sources. Node yang Component-nya tidak tercantum di map mengambil pengaturan default, dan tanpa default node tersebut dibiarkan tanpa tag. policies/tags.yaml memetakan database dan cache:
core/datastore/mariadb: orderscore/datastore/redis: sessionsdan default milik lampiran adalah untagged, sehingga web diberi tag untagged.
Keduanya memutuskan hanya berdasarkan label node dan Component-nya. Keduanya tidak membaca lingkungan, sehingga menulis label yang sama di kedua Releases.
Keduanya hanya melayani label-transform. Jika dipasang pada ir-verdict, keduanya ditolak sebelum berjalan; selector-tagger yang dipasang di sana menghentikan build dengan:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxMembuat 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-label-transformKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd policy-label-transformBuild
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullKatalog pustaka standar menyediakan setiap Component, Recipe, dan Feature di sini serta ketiga entitas Plugin. Semuanya di-resolve dari hub.aggrega.ai, registry bawaan yang disebutkan .aggrega-config.yaml. Dengan checkout katalog (cara mendapatkannya) yang disebutkan melalui --catalog, tidak ada yang diambil dari registry, sehingga build berjalan offline. --auto-pull mengisi lockfile setiap Release selama build; lockfile dan output hasil render dihasilkan, bukan dikirimkan.
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-label-transform`, panggil alat `scaffold` sekali dengan `example` diatur ke `policy-label-transform` dan tanpa `dir`: alat ini menulis contoh ke folder `policy-label-transform` yang baru. Kemudian panggil alat `build` sekali untuk setiap Release, dengan urutan ini — `release-staging.yaml` dan `release-production.yaml` — setiap kali dengan `workspace_root` diatur ke `policy-label-transform`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file apa saja yang ditulis setiap build; file-file itu ada di bawah `policy-label-transform/dist/`.Label yang dimiliki setiap node pada akhirnya
--ir-graph mencetak grafik build ke output standar, sebelum ringkasan build, dan grafik memuat label setiap node sebagaimana ditinggalkan transformasi. Setelah aggrega build --release release-production.yaml --auto-pull --ir-graph, web berbunyi:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Tiga label pertama adalah milik Component sendiri; empat label terakhir ditulis oleh ketiga transformasi. check.sh membaca grafik setiap build dan mencantumkan label yang ditulis lampiran:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedHanya dua label kebijakan Rego yang berubah di antara Releases.
Setelah build mengisi lockfile, aggrega inspect release-production.yaml --ir-graph mencetak grafik yang sama tanpa melakukan build, sebelum tampilan Release yang mudah dibaca, karena transformasi membaca file-nya dari lockfile. Tanpa lockfile, grafik yang dicetaknya tidak memuat satu pun label yang ditentukan file-file tersebut: tidak ada ops.example.com/environment atau ops.example.com/support-tier, dan tag: untagged pada setiap node.
Transformasi mengubah label dan tidak lebih
Keputusan pada label-transform menyebutkan satu node, satu kunci label, dan nilainya, atau meminta satu label dihapus. Tidak ada keputusan yang menambahkan node, mengubah Component atau versi node, atau menyentuh nilainya, sehingga transformasi tidak dapat menyatakan hal-hal tersebut. Keputusan yang menyebutkan node yang tidak ada dalam build tidak diabaikan: build berhenti dengan E0069 dan menyebutkan node beserta label yang tidak dapat ditetapkannya.
Dua build release-production.yaml, dengan lampiran ini dan tanpa lampiran, menunjukkannya. Grafik build keduanya berbeda pada label yang tercantum di atas dan tidak pada hal lain. Output hasil render keduanya sama sekali tidak berbeda: Recipes Compose di sini tidak merender satu pun dari label ini, sehingga dist/compose/docker-compose.yaml adalah file yang sama, byte demi byte, dengan maupun tanpa lampiran, dan check.sh membandingkan kedua pohon pada setiap eksekusi. Label berada di grafik build, tempat putusan membacanya.
Putusan, dan build yang dihentikannya
policies/production-support.rego dipasang pada ir-verdict, setelah transformasi, dan membaca label yang ditulis transformasi tersebut:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Kedua Releases berhasil di-build: di staging putusan tidak meminta apa pun, dan di production setiap node memiliki tingkat. Persempit cakupan kebijakan, maka putusan akan menangkap node yang terlewat. Dengan supported_categories ditulis [datastore] di .aggrega-config.yaml, web tidak mendapat tingkat dukungan, dan aggrega build --release release-production.yaml --auto-pull berhenti:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationBuild keluar dengan 1 dan tidak menulis dist/. release-staging.yaml tetap berhasil di-build dengan kebijakan yang dipersempit: node-nya diberi label staging, dan putusan tidak meminta apa pun darinya. check.sh menjalankan build ini dalam salinan workspace, sehingga tidak ada yang perlu disunting di sini untuk melihatnya.
Putusan menerima atau menolak dan tidak melakukan hal lain: putusan tidak dapat menambahkan label yang hilang agar build lolos. Label mana yang harus dimiliki node produksi adalah aturan estate, yang ditulis dalam kebijakannya; compiler membawa label ke grafik sebagai string dan tidak memberinya makna apa pun.
Apa yang dicatat lockfile
Lockfile mencatat kedua jenis lampiran secara berbeda. Setelah build produksi, release-production.lock memuat setiap lampiran transformasi di bawah mutators: — plugin-nya, perannya, pengaturannya, serta isi dan digest dari setiap file-nya — dan mem-pin setiap plugin transformasi di bawah plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0Lampiran putusan hanya muncul di bawah verdict_inputs:, melalui sha256 file-nya:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoLampiran putusan tidak di-pin. Jika putusan dipasang sendirian — ketiga transformasi dihapus dari .aggrega-config.yaml — lockfile memuat mutators: [] dan plugins: [], serta file putusan di bawah verdict_inputs:. Transformasi mengubah build yang menjadi dasar kerja sisa pipeline, sehingga lockfile menyimpan plugin yang membuat perubahan tersebut; putusan hanya memutuskan apakah build selesai.
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 menjalankan empat build melalui helper build-release dan memeriksa setiap hasil terhadap hasil yang dijelaskan halaman ini:
release-production.yamldalam salinan workspace ini tanpa lampiran tata kelola, sebagai acuan;release-staging.yamldanrelease-production.yamldi sini, yang masing-masing harus selesai dengan label yang tercantum di atas pada setiap node, dengan pohon produksi sama byte demi byte dengan milik acuan;release-production.yamldalam salinan yang kebijakannya hanya mencakup kategoridatastore, yang harus berhenti denganE0005dan kalimat di atas, tanpa penolakan lain di sampingnya.
Skrip ini mencetak satu baris per build, lalu labelnya, dan keluar dengan 1 jika ada hasil yang berbeda, sambil mencetak output build tersebut:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Kedua salinan dibuat di direktori sementara, dengan path katalog di .aggrega-config.yaml-nya dijadikan absolut agar tetap ter-resolve dari sana. Tidak ada file di direktori ini yang disunting; dua build yang dijalankan di sini mengisi lockfile-nya, seperti build mana pun. 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 membandingkan pohon yang ditulis oleh build, dan tidak meninggalkan satu pun. Status keluarnya adalah seluruh putusannya.
Bagian yang tidak ditafsirkan oleh kompiler
Compiler menyerahkan node dan lingkungan Release kepada setiap transformasi, menerapkan label yang diputuskannya, dan menyerahkan hasilnya kepada putusan. Compiler tidak tahu apa itu tingkat dukungan, bahwa on-call lebih tinggi daripada office-hours, atau bahwa sebuah devtool memerlukan tingkat: makna-makna tersebut adalah pengaturan dan aturan kebijakan. Untuk peran, payload, dan cara kebijakan menyebutkan label, lihat soket tata kelola, dan untuk posisi kebijakan dalam produk, lihat Tata Kelola dan Kepatuhan.
Berkas
aggregate.yaml— basis data, cache, dan UI administrasi yang terhubung ke basis data; tanpa label.manifest.yaml— mengikat setiap tipe komponen dan Feature rahasia ke Docker Compose Recipe miliknya. Dipakai bersama oleh kedua Releases.release-staging.yaml,release-production.yaml— dua lingkungan..aggrega-config.yaml— registri bawaan dan empat lampiran tata kelola.policies/support-tier.rego— kebijakan transformasi label.policies/production-support.rego— verdict.policies/tags.yaml— peta komponen-ke-tag milik penanda selector.build-release.sh— membangun satu Release, sambil menampilkan perintahaggrega buildyang setara.check.sh— menjalankan empat build dan memeriksa setiap hasilnya.