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

Kebijakan yang melampirkan Features yang tidak ditulis siapa pun: anotasi yang disuntikkan di `annotation-transform`

Sebuah kebijakan tata kelola memberi setiap komponen sebuah toko pemantauan platform dan sebuah peran AWS IAM. Kebijakan itu melakukannya dengan menambahkan anotasi. Manifest mengikat dua kunci anotasi ke dua Features, dan anotasi di bawah kunci yang terikat diperluas menjadi lampiran Feature. Jadi anotasi yang ditambahkan kebijakan membawa sebuah Prometheus ServiceMonitor dan sebuah Kubernetes ServiceAccount ke setiap komponen, dan baik Aggregate maupun Release tidak menulis keduanya.

Kebijakan dilampirkan pada peran annotation-transform, sekali untuk setiap mesin kebijakan yang dikompilasi ke dalam CLI: Rego dan CEL. Bukti utamanya adalah Release kontrol yang menulis anotasi yang sama secara manual. Jika di-build tanpa kebijakan, Release ini merender berkas yang sama, byte demi byte, dengan Release yang dianotasi oleh kebijakan.

Apa yang dibangunnya

instansComponent katalogapa yang dibawanya di release.yaml
apiexample/compute/servicetidak ada
workerexample/compute/servicetidak ada
gatewayexample/compute/serviceanotasi pemantauan miliknya sendiri, dengan interval 10 detik

Ketiganya dikompilasi ke Kubernetes melalui Helm, ke dalam dist/shop/helm/. example/compute/service adalah Component demonstrasi dalam katalog pustaka standar. Setiap instansnya harus membawa lampiran core/prometheus-exporter, sebuah persyaratan yang dinyatakan Component dan diperiksa oleh build.

Dua binding anotasi

manifest.yaml memberi makna pada dua kunci anotasi:

features:
type:
core/prometheus-exporter: helm/prometheus-exporter:1.0.0
core/aws-irsa: helm/aws-irsa:1.0.0
annotations:
feature.aggrega.ai/monitoring:
feature: core/prometheus-exporter
maps:
infra:
- interval
- port
- path
aws-role:
feature: core/aws-irsa
maps:
infra:
- role_arn

Binding yang merutekan beberapa subkunci menerima sebagai nilainya sebuah objek yang menyebutkan masing-masing subkunci tersebut, sehingga feature.aggrega.ai/monitoring menerima {interval: …, port: …, path: …}. Binding yang merutekan satu subkunci menerima string, sehingga aws-role menerima ARN peran. Lampiran yang dihasilkan dari ekspansi sebuah anotasi diberi nama sesuai kuncinya. core/aws-irsa menamai ServiceAccount-nya sesuai lampiran tersebut, itulah sebabnya kunci itu tidak mengandung titik atau garis miring.

Memasang kebijakan

.aggrega-config.yaml menyebut hub sebagai registrinya, tanpa direktori katalog, dan tanpa lampiran tata kelola. Kebijakan dipasang oleh file yang disebutkan build dengan --config: governance-rego.yaml untuk mesin Rego, governance-cel.yaml untuk mesin CEL. File untuk Rego berbunyi:

plugins:
governance:
- uri: governance/rego:0.9.0
role: annotation-transform
with:
sources:
- policies/platform-defaults.rego

--config menyebutkan file konfigurasi global untuk eksekusi tersebut, sebagai pengganti file yang biasanya dibaca mesin, dan .aggrega-config.yaml milik workspace ini tetap dilapiskan di atasnya.

0.9.0 adalah versi tempat hub mempublikasikan entitas Plugin dari setiap mesin, sehingga lampiran di-resolve dari registri yang dibaca workspace, atau dari biner aggrega rilis tersebut, yang memuatnya. Mesin yang berjalan adalah mesin yang dikompilasi ke dalam biner aggrega yang menjalankan build, versi apa pun yang disebutkan lampiran. Objek yang diterima anotasi pemantauan memerlukan mesin yang dapat menyisipkan objek subkunci, dan mesin dari rilis sebelum 0.8.7 tidak dapat melakukannya.

Apa yang dibaca kebijakan annotation-transform

Kebijakan pada annotation-transform membaca dua hal:

  • input.targets mencantumkan setiap komponen yang dapat dianotasinya. Setiap target memiliki boundary_path, component_name, dan annotations yang ditulis Release pada komponen tersebut, masing-masing nilai sebagaimana ditulis.
  • input.binding_keys mencantumkan kunci anotasi yang di-bind oleh Manifest.

aggrega build --release <release> --dry-run --policy-input <dir> menulis payload yang diterima setiap peran ke <dir> dan tidak menulis apa pun selain itu. Setelah build release.yaml mengisi lockfile-nya:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '.binding_keys' payloads/annotation-transform.json
# ["feature.aggrega.ai/monitoring","aws-role"]
jq -c '.targets[]' payloads/annotation-transform.json
# {"boundary_path":"shop","component_name":"api","annotations":{}}
# {"boundary_path":"shop","component_name":"worker","annotations":{}}
# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}

annotations sebuah target berisi apa yang ditulis Release pada komponen itu sendiri. aggrega.ai/namespace milik boundary tidak termasuk di antaranya.

Kebijakan

policies/platform-defaults.rego mengumpulkan satu keputusan per anotasi di bawah annotations. Setiap keputusan menyebutkan target melalui dua field tempat target itu dibaca, lalu kunci dan nilainya:

annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": monitoring,
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
monitoring in input.binding_keys
some t in input.targets
not monitoring in object.keys(t.annotations)
}
annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": role,
"annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),
} if {
role in input.binding_keys
some t in input.targets
not role in object.keys(t.annotations)
}

Setiap aturan hanya terpicu untuk kunci yang ada di input.binding_keys, sehingga kebijakan tidak menambahkan apa pun yang belum diberi makna oleh Manifest. Setiap aturan juga melewati target yang sudah memiliki kunci tersebut. Keputusan pada kunci yang sudah dimiliki komponen akan menggantikan nilai yang ditulis Release. Tanpa pemeriksaan itu, gateway akan kehilangan interval 10 detiknya digantikan 30 detik dari kebijakan.

policies/platform-defaults.cel menyatakan dua keputusan yang sama sebagai satu ekspresi, menggabungkan dua daftar dengan +. Kunci map diuji dengan in alih-alih object.keys, dan ARN peran digabungkan dengan +, karena bahasa ekspresinya tidak memiliki sprintf. Separuh ekspresi untuk peran berbunyi:

+ input.targets
.filter(t, "aws-role" in input.binding_keys
&& !("aws-role" in t.annotations))
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "aws-role",
"annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name,
}),

Apa yang dirender build

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

menulis dua belas file di bawah dist/shop/helm/: sebuah Deployment dan sebuah Service untuk setiap komponen, ServiceMonitor hasil ekspansi anotasi pemantauannya, dan ServiceAccount hasil ekspansi anotasi aws-role-nya. spec dari ServiceMonitor milik api, dari anotasi yang disisipkan kebijakan:

spec:
selector:
matchLabels:
app.kubernetes.io/name: api
endpoints:
- port: metrics
interval: 30s
path: /metrics

Milik gateway memuat interval: 10s, nilai yang ditulis entri Release-nya. ServiceAccount tempat api berjalan, dari aws-role yang disisipkan:

apiVersion: v1
kind: ServiceAccount
metadata:
name: api-aws-role
namespace: shop
annotations:
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api"
aggrega.ai/boundary-path: shop
aggrega.ai/recipe-uri: "aws-irsa:1.0.0"
[… omitted: the labels, which carry the version of the aggrega binary that built the file]

Disisipkan atau ditulis manual: file yang sama

release-by-hand.yaml adalah release.yaml dengan anotasi yang disisipkan kebijakan ditulis secara manual pada setiap komponen. Saat di-build tanpa kebijakan yang dipasang,

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

file ini menulis dua belas file yang sama, byte demi byte, seperti release.yaml dengan kebijakan yang dipasang di mesin mana pun. Tidak ada yang dikecualikan dari perbandingan itu: apakah sebuah anotasi disisipkan tidak dicatat dalam file hasil render mana pun. check.sh membandingkan pohon-pohon tersebut pada setiap eksekusi.

Build membaca nilai yang disisipkan persis seperti membaca nilai yang sama yang ditulis dalam Release, sehingga nilai tersebut berekspansi menjadi lampiran yang sama.

Tempat penyisipan dicatat

Grafik build mencatatnya, dan --ir-graph mencetak grafik tersebut. Setiap komponen yang menerima anotasi yang disisipkan memiliki aggrega.ai/injected-by, yang menyebutkan plugin-nya, di antara anotasi Release-nya. Setelah aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api berbunyi:

"release_annotations": {
"aggrega.ai/namespace": "shop",
"aws-role": "arn:aws:iam::123456789012:role/shop-api",
"aggrega.ai/injected-by": "governance/rego"
},

Catatannya per komponen, bukan per kunci: gateway juga memilikinya, karena aws-role-nya. Setiap lampiran hasil ekspansi anotasi memiliki "origin": "annotation" di grafik, sama seperti untuk anotasi yang ditulis manual.

Target Helm tidak merender anotasi aggrega.ai/injected-by, dan menyatakan hal tersebut. Dalam build ini, setiap komponen yang menerima penyisipan menambahkan tiga peringatan ke output. Peringatan pertama untuk api berbunyi:

warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it

--no-unsupported-field-warnings membungkam kelas peringatan tersebut, dan tidak mengubah apa pun yang ditulis build.

Peran ini menambahkan anotasi, dan tidak lebih

Sebuah keputusan menyebutkan satu komponen, satu kunci anotasi, dan nilainya. Tidak ada apa pun dalam keputusan yang menambahkan komponen, mengubah label, atau memasang Feature secara langsung. Kebijakan hanya mencapai Feature melalui kunci yang di-bind oleh Manifest, dan Manifest yang menentukan Feature mana itu.

Sebuah keputusan juga tidak dapat menghapus anotasi. Nilainya berupa string atau objek subkunci, dan null ditolak, dengan menyebutkan penyisipannya, karena null adalah cara penulis mengecualikan komponen dari anotasi yang seharusnya diwarisinya.

String di tempat binding merutekan tiga subkunci

governance-monitoring-as-string.yaml memasang policies/monitoring-as-string.rego, yang menyisipkan string "30s" di bawah kunci pemantauan. Binding tersebut merutekan tiga subkunci, dan sebuah string tidak menyebutkan satu pun di antaranya, sehingga

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

berhenti, keluar dengan 1, dan tidak menulis dist/. Kebijakan menyisipkan string tersebut pada api dan pada worker, dan masing-masing ditolak. Setiap penolakan menyebutkan plugin yang menyisipkan nilai tersebut dan peran tempat plugin itu dipasang, sehingga nilai dapat ditelusuri ke kebijakan yang memutuskannya, bukan ke baris Release yang tidak pernah ditulis siapa pun:

[… omitted: a warning that the attachment is in the global configuration named with --config]
[OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")
---
[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")

Tanpa kebijakan

release.yaml yang di-build tanpa lampiran tata kelola

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

akan berhenti. Component-nya memerlukan lampiran core/prometheus-exporter, dan tidak ada yang memberikannya kepada api maupun worker:

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")

gateway tidak disebutkan, karena entri Release-nya menulis pemantauannya sendiri. Dengan kebijakan dipasang, Release yang sama berhasil di-build: lampiran hasil ekspansi anotasi yang disisipkan memenuhi persyaratan, sama seperti lampiran yang ditulis manual.

Apa yang dicatat lockfile

Lampiran annotation-transform mengubah apa yang dirender build, sehingga lockfile mem-pin-nya. Setelah build Rego, release.lock memuat lampiran tersebut di bawah mutators:, beserta plugin-nya, perannya, serta isi dan digest file kebijakannya:

mutators:
- plugin: governance/rego
role: annotation-transform
sources:
- content: |
[… omitted: the policy file, as written]
digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b
path: platform-defaults.rego

Lockfile juga mem-pin plugin di bawah plugins::

plugins:
- uri: governance/rego
[… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice]
referenced_from:
- governance/rego:0.9.0

Lampiran menyebutkan versi yang dipublikasikan hub, sehingga pin di-resolve melalui registri yang dibaca workspace, atau dari biner aggrega rilis tersebut.

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-annotation-transform

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

Terminal window
cd policy-annotation-transform

Build

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

Katalog pustaka standar menyediakan setiap Component, Feature, Recipe, dan FeatureRecipe di sini, serta entitas Plugin dari kedua mesin. 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-annotation-transform`, panggil alat `scaffold` sekali dengan `example` diatur ke `policy-annotation-transform` dan tanpa `dir`: alat ini menulis contoh ke folder `policy-annotation-transform` yang baru. Kemudian panggil alat `cli-build`, yang menjalankan `aggrega build` dan menerima flag `--config`-nya, dengan `workspace_root` diatur ke `policy-annotation-transform`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `config` diatur ke `governance-rego.yaml`; lalu panggil lagi dengan cara yang sama dengan `config` diatur ke `governance-cel.yaml`. Terakhir, panggil alat `build` dengan `workspace_root` diatur ke `policy-annotation-transform`, `release` diatur ke `release-by-hand.yaml`, `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-annotation-transform/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 menjalankan lima build melalui helper build-release dan memeriksa setiap hasil terhadap hasil yang dijelaskan halaman ini:

  • release-by-hand.yaml tanpa kebijakan adalah acuannya. Build ini harus merender enam file hasil ekspansi anotasi.
  • release.yaml tanpa kebijakan harus berhenti dengan E0162 untuk api dan worker, dan tidak untuk komponen lain.
  • release.yaml dengan kebijakan di-build sekali di setiap mesin. Setiap build harus menulis file acuan byte demi byte, mem-pin plugin di lockfile-nya, dan mencatat ketiga komponen sebagai disisipi oleh plugin tersebut.
  • release.yaml dengan string yang ditanam harus berhenti dengan penolakan di atas.

Skrip ini mencetak satu baris per build, lalu file yang dirender oleh kedua binding, dan keluar dengan 1 jika ada hasil yang berbeda, sambil mencetak output build tersebut:

POLICY RELEASE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
none release-by-hand.yaml 0 reference OK: the six attachments' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml:
shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml
shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml
shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml
shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml
shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml
shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.

Setiap build berjalan dalam salinan workspace ini sendiri, yang dibuat di direktori sementara, dengan path katalog di .aggrega-config.yaml-nya dijadikan absolut agar tetap ter-resolve dari sana. Tidak ada yang ditulis di direktori ini. Skrip ini menggunakan biner yang di-resolve helper build-release, sehingga AGGREGA_BIN memilihnya, dan argumen setelah -- diteruskan ke setiap build. Status keluarnya adalah seluruh putusannya.

Bagian yang tidak ditafsirkan oleh kompiler

Compiler menyerahkan komponen dan kunci yang di-bind kepada kebijakan. Compiler menambahkan anotasi yang diputuskan kebijakan, dan mengekspansinya melalui binding Manifest sebagaimana mengekspansi anotasi apa pun. Compiler tidak tahu bahwa sebuah layanan harus dipantau, apa itu interval scrape, atau peran IAM mana yang harus digunakan sebuah komponen: makna-makna tersebut milik kebijakan dan Manifest. Untuk peran, payload, dan kunci keputusan, lihat soket tata kelola. Untuk ekspansi anotasi tanpa kebijakan, lihat annotation-driven-monitoring.

Berkas

  • aggregate.yaml — tiga layanan, tanpa anotasi.
  • manifest.yaml — mem-bind tipe komponen dan kedua Features ke Helm Recipes masing-masing, serta kedua kunci anotasi ke kedua Features.
  • release.yaml — Release yang dianotasi kebijakan; hanya gateway yang menulis anotasi.
  • release-by-hand.yaml — kontrol: setiap anotasi ditulis manual.
  • .aggrega-config.yaml — registry bawaan; tanpa lampiran tata kelola.
  • governance-rego.yaml, governance-cel.yaml — kebijakan yang dipasang pada annotation-transform melalui masing-masing mesin, masing-masing disebutkan dengan --config.
  • governance-monitoring-as-string.yaml — kesalahan yang ditanam, disebutkan dengan --config.
  • policies/platform-defaults.rego, policies/platform-defaults.cel — kebijakan, satu per mesin.
  • policies/monitoring-as-string.rego — kesalahan yang ditanam.
  • build-release.sh — membangun satu Release, sambil menampilkan perintah aggrega build yang setara.
  • check.sh — menjalankan lima build dan memeriksa setiap hasil.