Kimsenin yazmadığı Features'ı ekleyen bir politika: `annotation-transform` aşamasında enjekte edilen ek açıklamalar
Bir yönetişim politikası, bir mağazanın her bileşenine platformun izlemesini ve bir AWS IAM rolünü verir. Bunu ek açıklamalar ekleyerek yapar. Manifest iki ek açıklama anahtarını iki Features’a bağlar ve bağlı bir anahtar altındaki ek açıklama bir Feature ekine genişler. Böylece politikanın eklediği ek açıklamalar her bileşene bir Prometheus ServiceMonitor ve bir Kubernetes ServiceAccount getirir; Aggregate da Release de bunların hiçbirini yazmaz.
Politika, CLI’ye derlenmiş her politika motoru için bir kez olmak üzere annotation-transform rolüne eklenir: Rego ve CEL. Temel kanıt, aynı ek açıklamaları elle yazan bir kontrol Release’idir. Politika olmadan derlendiğinde, politikanın ek açıklama eklediği Release ile bayt bayt aynı dosyaları işler.
Ne oluşturur
| örnek | katalog Component’i | release.yaml içinde taşıdığı şey |
|---|---|---|
api | example/compute/service | hiçbir şey |
worker | example/compute/service | hiçbir şey |
gateway | example/compute/service | 10 saniyelik aralıkla kendi izleme ek açıklaması |
Üçü de Helm aracılığıyla Kubernetes için dist/shop/helm/ dizinine derlenir. example/compute/service, standart kütüphane kataloğundaki bir gösterim Component’idir. Onun her örneği bir core/prometheus-exporter eki taşımalıdır; bu, Component’in belirttiği ve derlemenin denetlediği bir gerekliliktir.
İki açıklama bağlaması
manifest.yaml, iki açıklama anahtarına bir anlam verir:
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_arnBirden çok alt anahtarı yönlendiren bir bağlama, değer olarak bunların her birini adlandıran bir nesne alır; bu yüzden feature.aggrega.ai/monitoring, {interval: …, port: …, path: …} alır. Tek bir alt anahtarı yönlendiren bir bağlama bir dize alır; bu yüzden aws-role, rolün ARN’sini alır. Bir açıklamanın genişlediği eklenti, anahtarının adını taşır. core/aws-irsa, ServiceAccount’una eklentinin adını verir; bu anahtarın nokta ya da eğik çizgi içermemesinin nedeni budur.
Politikayı bağlamak
.aggrega-config.yaml, hub’ı kayıt defteri olarak belirtir, hiçbir katalog dizini belirtmez ve hiçbir yönetişim eklentisi bildirmez. Politika, bir derlemenin --config ile belirttiği dosya tarafından bağlanır: Rego motoru için governance-rego.yaml, CEL motoru için governance-cel.yaml. Rego dosyası şöyledir:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config, o çalıştırma için genel yapılandırma dosyasını, makinenin aksi halde okuyacağı dosyanın yerine belirtir ve bu çalışma alanının .aggrega-config.yaml dosyası yine onun üzerine katmanlanır.
0.9.0, hub’ın her motorun Plugin varlığını yayımladığı bir sürümdür; bu nedenle eklenti, çalışma alanının okuduğu kayıt defterinden ya da onu taşıyan o sürümün aggrega ikili dosyasından çözümlenir. Çalışan motor, eklentinin hangi sürümü belirttiğinden bağımsız olarak, derlemeyi çalıştıran aggrega ikili dosyasına derlenmiş olandır. İzleme açıklamasının aldığı nesne, alt anahtarlardan oluşan bir nesne enjekte edebilen bir motor gerektirir ve 0.8.7’den önceki sürümlerin motorları bunu yapamaz.
Bir annotation-transform politikasının okudukları
annotation-transform konumundaki bir politika iki şey okur:
input.targets, açıklama ekleyebileceği her bileşeni listeler. Her hedefin birboundary_pathdeğeri, bircomponent_namedeğeri ve Release’in o bileşene yazdığıannotationsdeğerleri vardır; her değer yazıldığı gibidir.input.binding_keys, Manifest’in bağladığı açıklama anahtarlarını listeler.
aggrega build --release <release> --dry-run --policy-input <dir>, her rolün aldığı yükü <dir> içine yazar ve başka hiçbir şey yazmaz. release.yaml için yapılan bir derleme kilit dosyasını doldurduktan sonra:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -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"}}}Bir hedefin annotations değerleri, Release’in bileşenin kendisine yazdıklarını tutar. Sınırın aggrega.ai/namespace değeri bunların arasında değildir.
Politika
policies/platform-defaults.rego, annotations altında açıklama başına bir karar toplar. Her karar, hedefi altında okunduğu iki alanla adlandırır, ardından anahtarı ve değeri verir:
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)}Her kural yalnızca input.binding_keys içindeki bir anahtar için tetiklenir; bu nedenle politika, Manifest’in anlam vermediği hiçbir şey eklemez. Her kural, anahtarı zaten taşıyan bir hedefi de atlar. Bileşenin zaten taşıdığı bir anahtar altındaki bir karar, Release’in yazdığı değerin yerini alır. Bu sınama olmasaydı gateway, 10 saniyelik aralığını politikanın 30 saniyesine kaptırırdı.
policies/platform-defaults.cel, aynı iki kararı tek bir ifade olarak belirtir ve iki listeyi + ile birleştirir. İfade dilinde sprintf olmadığından, bir eşleme anahtarı object.keys yerine in ile sınanır ve rolün ARN’si + ile birleştirilir. İfadenin rolle ilgili yarısı şöyledir:
+ 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, }),Derlemenin işledikleri
aggrega build --release release.yaml --config governance-rego.yaml --auto-pulldist/shop/helm/ altına on iki dosya yazar: her bileşen için bir Deployment ve bir Service, izleme açıklamasının genişlediği ServiceMonitor ve aws-role açıklamasının genişlediği ServiceAccount. Politikanın enjekte ettiği açıklamadan gelen, api’nin ServiceMonitor’ünün spec bölümü:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsgateway’inki, Release girdisinin yazdığı değer olan interval: 10s taşır. Enjekte edilen aws-role’den gelen, api’nin altında çalıştığı ServiceAccount:
apiVersion: v1kind: ServiceAccountmetadata: 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]Enjekte edilmiş ya da elle yazılmış: aynı dosyalar
release-by-hand.yaml, politikanın enjekte ettiği açıklamaların her bileşene elle yazıldığı release.yaml dosyasıdır. Hiçbir politika bağlanmadan derlendiğinde,
aggrega build --release release-by-hand.yaml --auto-pullpolitika iki motordan herhangi birinde bağlanmış release.yaml ile bayt bayt aynı on iki dosyayı yazar. Bu karşılaştırmadan hiçbir şey hariç tutulmaz: bir açıklamanın enjekte edilip edilmediği, işlenen hiçbir dosyaya kaydedilmez. check.sh her çalıştırmada ağaçları karşılaştırır.
Derleme, enjekte edilen bir değeri, Release’te yazılan aynı değeri okuduğu gibi okur; bu yüzden değer aynı eklentiye genişler.
Enjeksiyonun kaydedildiği yer
Bunu derleme grafiği kaydeder ve --ir-graph grafiği yazdırır. Enjekte edilmiş bir açıklama alan her bileşen, Release açıklamaları arasında eklentiyi adlandıran aggrega.ai/injected-by taşır. aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph sonrasında api şöyle görünür:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},Kayıt anahtar başına değil, bileşen başınadır: gateway de aws-role’ü için bunu taşır. Açıklamaların genişlediği her eklenti, elle yazılmış bir açıklamada olacağı gibi, grafikte "origin": "annotation" değerine sahiptir.
Helm hedefi aggrega.ai/injected-by açıklamasını işlemez ve bunu belirtir. Bu derlemede, enjeksiyon alan her bileşen çıktıya üç uyarı ekler. api için olanların ilki şöyledir:
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 bu uyarı sınıfını susturur ve derlemenin yazdığı hiçbir şeyi değiştirmez.
Rol açıklama ekler, başka hiçbir şey yapmaz
Bir karar bir bileşeni, bir açıklama anahtarını ve onun değerini adlandırır. Bir kararda bileşen ekleyen, etiket değiştiren ya da doğrudan bir Feature bağlayan hiçbir şey yoktur. Politika bir Feature’a yalnızca Manifest’in bağladığı bir anahtar aracılığıyla ulaşır ve bunun hangi Feature olduğuna Manifest karar verir.
Bir karar bir açıklamayı da kaldıramaz. Değeri bir dize ya da alt anahtarlardan oluşan bir nesnedir ve null, enjeksiyonu adlandırılarak reddedilir; çünkü null, bir yazarın bir bileşeni aksi halde devralacağı bir açıklamanın dışında bırakma yoludur.
Bağlamanın üç alt anahtar yönlendirdiği yerde bir dize
governance-monitoring-as-string.yaml, izleme anahtarı altında "30s" dizesini enjekte eden policies/monitoring-as-string.rego politikasını bağlar. Bu bağlama üç alt anahtar yönlendirir ve bir dize bunların hiçbirini adlandırmaz; bu yüzden
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pulldurur, 1 ile çıkar ve hiçbir dist/ yazmaz. Politika dizeyi api ve worker üzerine enjekte etti ve her biri reddedilir. Her ret, değeri enjekte eden eklentiyi ve bağlandığı rolü adlandırır; böylece değer, kimsenin yazmadığı bir Release satırına değil, ona karar veren politikaya kadar izlenir:
[… 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")Politika olmadan
Hiçbir yönetişim eklentisi olmadan derlenen release.yaml
aggrega build --release release.yaml --auto-pulldurur. Component’i bir core/prometheus-exporter eklentisi gerektirir ve hiçbir şey bunu api’ye ya da worker’a vermez:
[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 adlandırılmaz, çünkü Release girdisi kendi izlemesini yazar. Politika bağlandığında aynı Release derlenir: enjekte edilmiş bir açıklamanın genişlediği eklenti, elle yazılmış olan gibi gereksinimi karşılar.
Kilit dosyasının kaydettikleri
Bir annotation-transform eklentisi derlemenin işlediklerini değiştirir; bu yüzden kilit dosyası onu sabitler. Rego derlemesinden sonra release.lock, eklentiyi mutators: altında; eklentisi, rolü ve politika dosyasının içeriği ve özetiyle birlikte taşır:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoAyrıca eklentiyi plugins: altında sabitler:
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.0Eklenti, hub’ın yayımladığı bir sürümü adlandırır; bu yüzden sabitleme, çalışma alanının okuduğu kayıt defteri üzerinden ya da o sürümün aggrega ikili dosyasından çözümlenir.
Örneği oluşturun
Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example policy-annotation-transformArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd policy-annotation-transformDerleme
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullStandart kütüphane kataloğu buradaki her Component, Feature, Recipe ve FeatureRecipe’i ve iki motorun Plugin varlıklarını sağlar. Bunlar, .aggrega-config.yaml dosyasının adlandırdığı varsayılan kayıt defteri olan hub.aggrega.ai üzerinden çözümlenir. Kataloğun bir çalışma kopyası (nereden edinilir) --catalog ile belirtildiğinde bir kayıt defterinden hiçbir şey çekilmez; bu yüzden derlemeler çevrimdışı çalışır. --auto-pull, derleme sırasında her Release’in kilit dosyasını doldurur. Kilit dosyaları ve işlenen çıktı üretilir, birlikte gönderilmez.
Bir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Workspace klasöründe henüz `policy-annotation-transform` klasörü yoksa, `scaffold` aracını `example` değeri `policy-annotation-transform` olacak şekilde ve `dir` olmadan bir kez çağırın: örneği yeni bir `policy-annotation-transform` klasörüne yazar. Ardından `aggrega build` komutunu çalıştıran ve onun `--config` bayrağını alan `cli-build` aracını `workspace_root` değeri `policy-annotation-transform`, `release` değeri `release.yaml`, `auto_pull` değeri true ve `config` değeri `governance-rego.yaml` olacak şekilde çağırın; sonra aynı şekilde `config` değeri `governance-cel.yaml` olacak biçimde yeniden çağırın. Son olarak `build` aracını `workspace_root` değeri `policy-annotation-transform`, `release` değeri `release-by-hand.yaml`, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Her derlemenin hangi dosyaları yazdığını bana söyleyin; bunlar `policy-annotation-transform/dist/` altındadır.Her derlemenin denetlenmesi
Bu öz denetim, kullandığı ortak derleme yardımcı betiğini barındıran belgelendirme deposunun bir çalışma kopyasında çalışır; aggrega scaffold --example tarafından yazılan bir kopya bu yardımcı betiği içermez.
./check.shcheck.sh, build-release yardımcısı aracılığıyla beş derleme yapar ve her sonucu bu sayfanın açıkladığıyla karşılaştırır:
- Politikasız
release-by-hand.yamlbaşvuru noktasıdır. Açıklamaların genişlediği altı dosyayı işlemelidir. - Politikasız
release.yaml,apiveworkeriçinE0162ile durmalıdır; başka hiçbir bileşen için durmamalıdır. - Politikalı
release.yamlher motorda bir kez derlenir. Her derleme, başvurunun dosyalarını bayt bayt aynı yazmalı, eklentiyi kilit dosyasında sabitlemeli ve üç bileşenin tümünü o eklenti tarafından enjekte edilmiş olarak kaydetmelidir. - Yerleştirilmiş dizeyi içeren
release.yaml, yukarıdaki retle durmalıdır.
Her derleme için bir satır, ardından iki bağlamanın işlediği dosyaları yazdırır ve herhangi bir sonuç farklıysa o derlemenin çıktısını yazdırarak 1 ile çıkar:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring 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.Her derleme, bu çalışma alanının geçici bir dizinde oluşturulan kendi kopyasında çalışır; oradan da çözümlenebilmesi için kopyanın .aggrega-config.yaml dosyasındaki katalog yolu mutlak yapılır. Bu dizine hiçbir şey yazılmaz. build-release yardımcısının çözümlediği ikili dosyayı kullanır; dolayısıyla bunu AGGREGA_BIN seçer ve -- sonrasındaki argümanlar her derlemeye ulaşır. Çıkış durumu kararın tamamıdır.
Derleyicinin yorumlamadığı yerler
Derleyici, bileşenleri ve bağlanmış anahtarları politikaya verir. Politikanın karar verdiği açıklamaları ekler ve herhangi bir açıklamayı genişlettiği gibi bunları Manifest’in bağlamaları aracılığıyla genişletir. Bir hizmetin izlenmesi gerektiğini, kazıma aralığının ne olduğunu ya da bir bileşenin hangi IAM rolü altında çalışması gerektiğini bilmez: bu anlamlar politikaya ve Manifest’e aittir. Roller, yükler ve karar anahtarları için yönetişim soketi sayfasına bakın. Politikasız açıklama genişletmesi için annotation-driven-monitoring sayfasına bakın.
Dosyalar
aggregate.yaml— açıklamasız üç hizmet.manifest.yaml— bileşen türünü ve iki Features’ı kendi Helm Recipes’lerine, iki açıklama anahtarını da iki Features’a bağlar.release.yaml— politikanın açıklama eklediği Release; yalnızcagatewaybir açıklama yazar.release-by-hand.yaml— kontrol: her açıklama elle yazılmıştır..aggrega-config.yaml— varsayılan kayıt defteri; yönetişim eklentisi yok.governance-rego.yaml,governance-cel.yaml— her motor aracılığıylaannotation-transformkonumuna bağlanan politika; her biri--configile belirtilir.governance-monitoring-as-string.yaml— yerleştirilmiş hata;--configile belirtilir.policies/platform-defaults.rego,policies/platform-defaults.cel— politika, her motor için bir kez.policies/monitoring-as-string.rego— yerleştirilmiş hata.build-release.sh— tek bir Release derler ve eşdeğeraggrega buildkomutunu yazdırır.check.sh— beş derlemeyi yapar ve her sonucu denetler.