Kebijakan seluruh organisasi: aturan tim, aturan organisasi, dan aturan pipeline
Kebijakan sebuah tim, kebijakan organisasinya, dan kebijakan pipeline-nya berjalan bersama dalam satu build, masing-masing dilampirkan dalam berkas konfigurasinya sendiri. Tim melampirkan aturannya di workspace-nya; organisasi menambahkan satu aturan pada setiap build, dan pipeline menambahkan satu lagi, tanpa salah satu dari keduanya menyunting berkas tim. Sebuah build membaca semua berkas yang berlaku baginya dan menjalankan setiap lampiran yang dibawa berkas-berkas itu.
Aturan-aturan tersebut dilaporkan pada ketiga tingkat keparahan verdict: info dan warn membiarkan build selesai, dan halt menghentikannya. Salah satunya, aturan organisasi, dilampirkan dua kali dan setiap kali dilaporkan pada tingkat keparahan yang berbeda, melalui blok translation.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
db | core/datastore/mariadb | database toko |
web | core/devtool/adminer | UI administrasi database, yang terhubung ke db |
Keduanya dikompilasi ke Docker Compose, ke dalam dist/compose/docker-compose.yaml. Satu Aggregate, satu Manifest, dan satu Release, release.yaml; tidak satu pun yang menyebut kebijakan.
Tiga berkas
| siapa | berkas | cara build membacanya | tempat lampiran ditulis |
|---|---|---|---|
| tim | .aggrega-config.yaml | berkas ini menandai direktori ini sebagai workspace, sehingga setiap build di sini membacanya | plugins.governance |
| organisasi | org/config.yaml | sebagai berkas konfigurasi global, disebut untuk satu build dengan --config org/config.yaml | plugins.governance_append |
| pipeline | pipeline/.aggrega-config-append-ci.yaml | setelah disalin ke direktori ini, sebagai overlay pipeline | plugins.governance_append |
Ketiga lampiran adalah mesin Rego, governance/rego:0.9.0, pada peran ir-verdict, yang menilai graf build sebelum apa pun dirender. 0.9.0 adalah versi entitas Plugin-nya di katalog pustaka standar. Mesin itu sendiri dikompilasi ke dalam CLI — aggrega plugin list mencantumkan governance/rego di antara bawaan yang tertanam — sehingga tidak ada build di sini yang mengambil plugin.
Berkas organisasi adalah berkas konfigurasi global. Sebuah mesin memiliki satu berkas seperti ini, yang dibaca pada setiap build: dari lokasi default-nya, atau berkas yang disebut oleh variabel lingkungan AGGREGA_CONFIG. --config <path> sebaliknya menyebut satu berkas untuk satu kali jalan, dan berkas-berkas milik workspace tetap dibaca di atasnya. Dalam sebuah organisasi, berkas tersebut akan berada di lokasi default di mesin setiap pengembang dan di setiap pipeline; di sini berkas itu berada di org/, dan build yang perlu membacanya menyebutnya. Menyebut berkas global secara eksplisit menjelaskan urutan ketiga cara tersebut dicoba.
Berkas pipeline adalah overlay. Sebuah build membaca .aggrega-config-append-ci.yaml di direktori tempat ia membaca .aggrega-config.yaml, di sampingnya. Berkas ini disimpan di sini di pipeline/, tempat build yang dijalankan di direktori ini tidak membacanya, karena berkas ini menghentikan setiap build yang membacanya; langkah pipeline adalah menyalinnya ke dalam:
cp pipeline/.aggrega-config-append-ci.yaml .Setiap berkas menambahkan, dan overlay pipeline hanya menambahkan
Organisasi dan pipeline sama-sama menulis lampirannya di bawah plugins.governance_append, pendamping penambahan untuk daftar plugins.governance. Entri di bawah pendamping disambungkan ke daftar yang sudah diresolusi setelah daftar milik setiap berkas dibaca, sehingga plugins.governance milik tim dan entri organisasi sama-sama berjalan, dan tidak ada berkas yang menyebut berkas lainnya. Organisasi menulis pendampingnya, bukan plugins.governance itu sendiri, karena daftar plugins.governance di berkas workspace menggantikan daftar di berkas global: aturan organisasi yang ditulis di sana dibuang oleh daftar tim, dan build tidak mencetak apa pun tentang hal itu. Memperluas daftar alih-alih menggantinya mencantumkan pendamping untuk setiap pengaturan daftar.
Overlay pipeline hanya dapat menambahkan. Apa yang ditulisnya untuk pengaturan daftar ditambahkan ke apa yang diresolusi oleh berkas lain; overlay ini tidak menghapus apa pun, dan tidak menimpa pengaturan yang menyimpan satu nilai, seperti auto_pull. Overlay ini membawa auto_pull: true, dan build yang membacanya mengabaikan kunci tersebut dan menyatakannya dalam sebuah peringatan. Dengan <workspace> mewakili path absolut direktori tempat build dijalankan, barisnya berbunyi:
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)Aturan, dan tingkat keparahan tempat masing-masing dilaporkan
Kebijakan Rego mengumpulkan setiap keputusan di bawah sebuah kunci keputusan, dan kunci itu memilih tingkat keparahan tempat keputusan dilaporkan. Tanpa translation, kuncinya adalah deny, warn, dan audit, yang dilaporkan pada halt, warn, dan info:
| tingkat keparahan | apa yang dilakukan build |
|---|---|
halt | berhenti, keluar dengan 1, dan tidak menulis dist/ |
warn | selesai, mencetak pesan, dan menulis dist/ |
info | selesai, mencetak pesan, dan menulis dist/ |
Aturan tim, policies/team.rego, mengumpulkan di bawah warn, dan lampirannya tidak mendeklarasikan translation, sehingga aturan ini dilaporkan pada warn:
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}Aturan organisasi, org/policies/estate.rego, menolak komponen dalam kategori yang dicantumkan pengaturannya, dan mencatat apa yang dijalankan setiap komponen:
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories adalah pengaturan setiap lampiran, dan sebuah kebijakan membaca pengaturan lampirannya sebagai dokumen data.
Translasi: satu aturan, dua tingkat keparahan
Blok translation dalam pengaturan sebuah lampiran mendeklarasikan kunci keputusan mana yang dibaca dan tingkat keparahan tempat masing-masing dilaporkan. Blok ini menggantikan pemetaan default alih-alih memperluasnya: kunci yang tidak disebutkannya tidak dibaca.
Berkas organisasi meluncurkan aturannya sebagai saran. Lampirannya melaporkan deny pada warn, dan audit pada info:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoPipeline melampirkan berkas yang sama dan membuat aturan yang sama menghentikan build. Translasinya hanya menyebut deny, sehingga lampirannya tidak melaporkan catatan audit untuk kedua kalinya:
settings: refused_categories: [devtool] translation: - key: deny severity: haltJadi satu aturan, atas web yang sama, menjadi peringatan pada build pengembang dan alasan build pipeline berhenti.
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-org-overlayKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd policy-org-overlayBuild
Katalog pustaka standar menyediakan Components, Recipes, Feature, dan FeatureRecipe-nya. 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 selama build; lockfile dan output yang dirender dihasilkan, bukan dikirimkan.
Hanya dengan berkas tim:
aggrega build --release release.yaml --auto-pullbuild mencetak peringatan tim dan selesai. Dengan berkas organisasi juga:
aggrega build --release release.yaml --auto-pull --config org/config.yamlbuild mencetak catatan organisasi pada info dan aturannya pada warn, di samping peringatan tim, dan tetap selesai:
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull 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]Setiap verdict menyebut plugin yang melaporkannya, rego, dan bukan berkas yang melampirkannya, sehingga peringatan tim dan peringatan organisasi terlihat sama; pesan yang menyatakan milik siapa aturan itu, seperti pesan organisasi, adalah cara untuk membedakannya.
Dengan overlay pipeline disalin ke dalam, perintah yang sama berhenti:
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violationBuild keluar dengan 1 dan tidak menulis dist/. Aturan organisasi dilaporkan dua kali, sekali oleh setiap lampiran: pada warn oleh lampiran organisasi dan pada halt oleh lampiran pipeline. Catatan audit muncul sekali, hanya dari lampiran organisasi. Hapus .aggrega-config-append-ci.yaml dari direktori ini untuk kembali melakukan build tanpanya.
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-org-overlay`, panggil alat `scaffold` sekali dengan `example` diatur ke `policy-org-overlay` dan tanpa `dir`: alat ini menulis contoh ke folder `policy-org-overlay` yang baru. Kemudian panggil alat `build` dengan `workspace_root` diatur ke `policy-org-overlay`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true, lalu beri tahu saya apa yang dilaporkan kebijakan. Kemudian panggil alat `cli-build`, yang menjalankan `aggrega build` dan menerima flag `--config`-nya, dengan `workspace_root` diatur ke `policy-org-overlay`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `config` diatur ke `org/config.yaml`, lalu beri tahu saya apa yang dilaporkan kebijakan kali ini. Beri tahu saya file apa saja yang ditulis setiap build; file-file itu ada di bawah `policy-org-overlay/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 release.yaml lima kali, melalui helper build-release, masing-masing dalam salinan workspace ini: hanya dengan berkas tim, dengan berkas organisasi yang disebut melalui --config, dengan overlay pipeline disalin ke dalam, dengan keduanya, dan dengan salinan berkas organisasi yang menulis lampirannya di bawah plugins.governance alih-alih di pendampingnya — tempat daftar tim menggantikannya, dan hanya verdict tim yang dicetak. Untuk masing-masing, skrip ini memeriksa status keluar, apakah dist/ ditulis, dan setiap verdict yang dicetak build — tingkat keparahan dan pesannya, tanpa ada yang hilang dan tanpa yang lain — dan, ketika overlay dibaca, peringatan yang menyebut auto_pull. Skrip ini mencetak satu baris per build, lalu verdict yang dicetak masing-masing, dan keluar dengan 1 jika ada hasil yang berbeda, sambil mencetak output build tersebut:
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.Salinan dibuat di direktori sementara, dengan path katalog di .aggrega-config.yaml miliknya dijadikan absolut agar tetap dapat diresolusi dari sana; tidak ada berkas di direktori ini yang disunting atau ditulis. Skrip ini menggunakan biner yang di-resolve oleh ./build-release.sh, sehingga AGGREGA_BIN memilihnya, dan argumen setelah -- diteruskan ke setiap build. Status keluarnya adalah seluruh putusannya.
Bagian yang tidak ditafsirkan oleh kompiler
Compiler membaca ketiga berkas, menyambungkan lampiran yang dibawanya, menyerahkan graf build dan pengaturannya kepada setiap kebijakan, dan bertindak berdasarkan tingkat keparahan tempat setiap keputusan dilaporkan. Compiler tidak tahu apa itu devtool, mengapa sebuah organisasi tidak akan mengirimkannya, atau bahwa ketersediaan tinggi penting bagi sebuah tim: makna-makna itu adalah aturan dan pengaturan kebijakan. Untuk peran, payload, dan kunci keputusan, lihat soket tata kelola.
Berkas
aggregate.yaml— basis data dan UI administrasi yang terhubung dengannya.manifest.yaml— mengikat setiap tipe komponen dan Feature rahasia ke Docker Compose Recipe miliknya.release.yaml— satu-satunya Release..aggrega-config.yaml— berkas tim: registri bawaan dan lampiran tim.policies/team.rego— aturan tim.org/config.yaml— berkas konfigurasi global organisasi dan lampirannya.org/policies/estate.rego— aturan organisasi.pipeline/.aggrega-config-append-ci.yaml— overlay pipeline, yang dibaca setelah disalin ke direktori ini.build-release.sh— mem-build Release, sambil menampilkan perintahaggrega buildyang setara.check.sh— menjalankan lima build dan memeriksa setiap hasil.