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

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

instansComponent katalogperannya di sini
dbcore/datastore/mariadbdatabase toko
webcore/devtool/adminerUI 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

siapaberkascara build membacanyatempat lampiran ditulis
tim.aggrega-config.yamlberkas ini menandai direktori ini sebagai workspace, sehingga setiap build di sini membacanyaplugins.governance
organisasiorg/config.yamlsebagai berkas konfigurasi global, disebut untuk satu build dengan --config org/config.yamlplugins.governance_append
pipelinepipeline/.aggrega-config-append-ci.yamlsetelah disalin ke direktori ini, sebagai overlay pipelineplugins.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:

Terminal window
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 keparahanapa yang dilakukan build
haltberhenti, keluar dengan 1, dan tidak menulis dist/
warnselesai, mencetak pesan, dan menulis dist/
infoselesai, 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: info

Pipeline 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: halt

Jadi 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:

Terminal window
aggrega scaffold --example policy-org-overlay

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd policy-org-overlay

Build

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:

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

build mencetak peringatan tim dan selesai. Dengan berkas organisasi juga:

Terminal window
aggrega build --release release.yaml --auto-pull --config org/config.yaml

build 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 ship
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]

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:

Terminal window
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 violation

Build 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.

Terminal window
./check.sh

check.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 OK
team + organization 0 yes OK
team + pipeline 1 no OK
all three 1 no OK
team + 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 perintah aggrega build yang setara.
  • check.sh — menjalankan lima build dan memeriksa setiap hasil.