İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Etiketleri biçimlendiren politikalar: ortam başına bir destek düzeyi ve onu okuyan bir hüküm

Yönetişim eklentileri, bu çalışma alanının dağıttığı her bileşeni sahibi, ortamının hak ettiği destek düzeyi, yedekleme takvimi ve kısa bir etiketle işaretler; böylece hiçbir geliştirici bunları yazmak zorunda kalmaz. Etiketler derleme sırasında dört yönetişim eklentisi tarafından türetilir:

  • üçü label-transform rolündedir ve derlemenin düğümlerindeki etiketleri biçimlendirir: Release’in ortamını okuyan bir Rego politikası ve CLI’ya derlenmiş iki etiketleme eklentisi, label-injector ve selector-tagger;
  • biri ir-verdict rolündedir; derleme grafiği üzerinde, bir düğümün destek düzeyi olmadan bırakıldığı bir üretim derlemesini durduran bir Rego politikasıdır.

Tek bir Aggregate’in iki Releases’i ortamlarında, staging ve production olarak farklılaşır ve düğümleri farklı etiketlerle sonuçlanır. check.sh’nin, politikası bir kategoriyi daha az kapsayan bu çalışma alanının bir kopyasından yaptığı üçüncü bir derleme durur ve dışarıda bıraktığı düğümü adlandırır.

Ne oluşturur

örnekkatalog Component’iburada ne olduğu
dbcore/datastore/mariadbmağazanın veritabanı
cachecore/datastore/redisoturum önbelleği
webcore/devtool/adminerdb’ye bağlı bir veritabanı yönetim arayüzü

Üçü de Docker Compose’a, dist/compose/docker-compose.yaml dosyasına derlenir. Aggregate ve iki Releases’in hiçbiri kendi etiketini adlandırmaz: aşağıdaki her etiketi bir eklenti yazar.

Dört eklenti

Bu çalışma alanının .aggrega-config.yaml dosyasında, plugins.governance altında bağlanırlar; bu yüzden burada çalıştırılan her derleme onları uygular:

eklentirolyazdığı
1governance/rego:0.9.0, policies/support-tier.rego ilelabel-transformher düğümde ops.example.com/environment; kategorisi ayarlarında listelenen her düğümde ops.example.com/support-tier
2governance/label-injector:0.9.0label-transformher düğümde ops.example.com/owner; datastore kategorisindeki her düğümde backup.example.com/schedule
3governance/selector-tagger:0.9.0label-transformpolicies/tags.yaml içindeki eşlemeden tag
4governance/rego:0.9.0, policies/production-support.rego ileir-verdicthiçbir şey: derlemeyi durdurur ya da tamamlanmasına izin verir

0.9.0, standart kütüphane kataloğundaki üç Plugin varlığının sürümüdür; eklentilerin kendileri CLI’ya derlenmiştir ve bir derleme onları oradan sunar. aggrega build --release release-production.yaml --auto-pull --detail, üçünün her biri için ikisini de listeler:

[… 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]

Bir roldeki eklentiler listelendikleri sırayla çalışır ve her biri kendinden öncekilerin yazdığı etiketleri okur: etiket enjektörü Rego politikasının yazdığı iki etiketi alır, seçici etiketleyici ise bunları ve etiket enjektörünün etiketlerini alır. Hüküm, üçünün ardından, onların bıraktığı grafik üzerinde çalışır.

Bir label-transform politikasının okudukları

label-transform konumundaki bir politika, düğüm kimliğiyle anahtarlanmış düğümleri input.graph.nodes konumunda okur; her birinde şunlar bulunur:

  • component — düğümün örneklediği Component, örneğin core/datastore/mariadb;
  • resolved_version — o Component’in çözümlendiği sürüm;
  • labels — politika çalıştığında düğümün taşıdığı etiketler: Component’in kendi etiketleri ve daha önceki herhangi bir dönüşümün yazdıkları;
  • values — düğümün örneğinin Aggregate içinde bildirdiği değerler; hiç bildirmediğinde yoktur. Burada yalnızca db bir değer bildirir: database: appdb.

Release’i input.compilation_context konumunda okur: release_name ve environment. Tek bir politikanın ortama göre farklı karar vermesini sağlayan budur.

ir-verdict konumundaki bir politika ise tüm derleme grafiğini okur ve düğümleri bir düzey daha derinde, input.graph.spec.nodes konumunda bulunur. Bir rolden diğerine taşınan bir kural kopyalanmaz, düzenlenir: yanlış yolla hiçbir şey okumaz ve hiç tetiklenmez. ir-verdict yükü compilation_context taşımaz; bu yüzden bir hüküm ortamı Release’ten okuyamaz. Buradaki ilk politikanın her düğüme ops.example.com/environment da yazmasının nedeni budur: hüküm, ortamı bu etiketten okur.

Yükleri okumak yerine görmek için, kilit dosyası oluşsun diye bir kez derleyin, ardından:

Terminal window
aggrega build --release release-production.yaml --dry-run --policy-input payloads

her eklentinin aldığı yükü payloads/ içine yazar; tek bir roldeki birkaç eklentinin farklı yükler aldığı durumlarda eklenti başına bir dosya — label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json — ve diğer her rol için birer dosya yazar, başka hiçbir şey yazmaz.

Rego politikası

policies/support-tier.rego, kararlarını labels altında, etiket başına bir tane olmak üzere toplar; düğümü, etiket anahtarını ve değeri adlandırır:

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
}

Ayarları politikanın data belgesidir ve kurumun sözcük dağarcığını tutar:

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-hours

Her yerleşik eklentinin yazdıkları

label-injector bir kurallar listesi uygular. Etiketleri bir kuralın match altındaki her çifti içeren bir düğüm, set altındaki her çifti alır; çift eklenir ya da düğümün zaten taşıdığı bir etiketin değerinin yerini alır. Çift içermeyen bir match her düğümle eşleşir. Kuralları, burada olduğu gibi rules ayarından ya da ayarlar hiç kural taşımadığında sources altında kural taşıyan ilk dosyadan okur. Buradaki iki kuralı her düğüme ops.example.com/owner: shop-team, datastore kategorisindeki iki düğüm olan db ve cache’e ise backup.example.com/schedule: nightly verir. web, devtool kategorisindedir ve yedekleme takvimi almaz.

selector-tagger her zaman tag anahtarı altında tek bir etiket yazar. Değeri, sources altındaki dosyalardan okunan, Component adlarından etiketlere bir eşlemeden gelir. Component’i eşlemede listelenmeyen bir düğüm default ayarını alır; default yoksa tag olmadan kalır. policies/tags.yaml, veritabanını ve önbelleği eşler:

core/datastore/mariadb: orders
core/datastore/redis: sessions

ve eklentinin default değeri untagged olduğundan web, untagged olarak etiketlenir.

İkisi de yalnızca bir düğümün etiketlerine ve Component’ine göre karar verir. İkisi de ortamı okumaz; bu yüzden iki Releases’te de aynı etiketleri yazarlar.

İkisi de yalnızca label-transform rolüne hizmet eder. ir-verdict konumuna bağlandığında ikisi de çalışmadan önce reddedilir; oraya bağlanan selector-tagger derlemeyi şununla durdurur:

[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 sandbox

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

Terminal window
aggrega scaffold --example policy-label-transform

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd policy-label-transform

Derleme

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

Standart kütüphane kataloğu buradaki her Component, Recipe ve Feature’ı ve üç Plugin varlığı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-label-transform` klasörü yoksa, `scaffold` aracını `example` değeri `policy-label-transform` olacak şekilde ve `dir` olmadan bir kez çağırın: örneği yeni bir `policy-label-transform` klasörüne yazar. Ardından `build` aracını her Release için birer kez, şu sırayla çağırın — `release-staging.yaml` ve `release-production.yaml` — her seferinde `workspace_root` değeri `policy-label-transform`, `release` değeri o dosya, `auto_pull` değeri true ve `write` değeri true olacak şekilde. Her derlemenin hangi dosyaları yazdığını bana söyleyin; bunlar `policy-label-transform/dist/` altındadır.

Her düğümün sonunda taşıdığı etiketler

--ir-graph, derleme grafiğini derlemenin özetinden önce standart çıktıya yazdırır ve grafik, her düğümün etiketlerini dönüşümlerin bıraktığı haliyle taşır. aggrega build --release release-production.yaml --auto-pull --ir-graph sonrasında web şöyle görünür:

"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]
}

İlk üç etiket Component’in kendisinindir; son dördünü üç dönüşüm yazmıştır. check.sh her derlemenin grafiğini okur ve eklentilerin yazdığı etiketleri listeler:

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

Releases arasında yalnızca Rego politikasının iki etiketi değişir.

Bir derleme kilit dosyasını doldurduktan sonra aggrega inspect release-production.yaml --ir-graph, aynı grafiği derleme yapmadan, Release’in okunabilir görünümünden önce yazdırır; çünkü dönüşümler dosyalarını kilit dosyasından okur. Kilit dosyası olmadan yazdırdığı grafik, bu dosyaların belirlediği etiketlerin hiçbirini taşımaz: ne ops.example.com/environment ne de ops.example.com/support-tier vardır ve her düğümde tag: untagged bulunur.

Bir dönüşüm etiketleri değiştirir, başka hiçbir şeyi değil

label-transform konumundaki bir karar bir düğümü, bir etiket anahtarını ve değerini adlandırır ya da bir etiketin kaldırılmasını ister. Düğüm ekleyen, bir düğümün Component’ini ya da sürümünü değiştiren veya değerlerine dokunan bir karar yoktur; bu yüzden bir dönüşüm bunların hiçbirini ifade edemez. Derlemede olmayan bir düğümü adlandıran bir karar yok sayılmaz: derleme E0069 ile durur ve düğümü ve ayarlayamadığı etiketi adlandırır.

release-production.yaml için bu eklentilerle ve eklentisiz yapılan iki derleme bunu gösterir. Derleme grafikleri yukarıda listelenen etiketlerde farklılaşır, başka hiçbir şeyde değil. İşlenen çıktıları ise hiç farklı değildir: buradaki Compose Recipes bu etiketlerin hiçbirini işlemez; bu yüzden dist/compose/docker-compose.yaml eklentilerle de eklentisiz de bayt bayt aynı dosyadır ve check.sh her çalıştırmada iki ağacı karşılaştırır. Etiketler, hükmün onları okuduğu derleme grafiğinde yaşar.

Hüküm ve durdurduğu derleme

policies/production-support.rego, dönüşümlerden sonra ir-verdict konumuna bağlanır ve onların yazdığı etiketleri okur:

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])
}

İki Releases de derlenir: staging’de hüküm hiçbir şey istemez, production’da ise her düğüm bir düzey taşır. Politikanın kapsamını daraltırsanız hüküm, dışarıda bıraktığı düğümü yakalar. .aggrega-config.yaml içinde supported_categories değeri [datastore] olarak yazıldığında web destek düzeyi almaz ve aggrega build --release release-production.yaml --auto-pull durur:

[… 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 violation

Derleme 1 ile çıkar ve hiçbir dist/ yazmaz. release-staging.yaml daraltılmış politikayla yine derlenir: düğümleri staging olarak etiketlenir ve hüküm onlardan hiçbir şey istemez. check.sh bu derlemeyi çalışma alanının bir kopyasında yapar; bu yüzden onu görmek için burada hiçbir şeyin düzenlenmesi gerekmez.

Bir hüküm kabul eder ya da reddeder ve başka hiçbir şey yapmaz: derlemenin geçmesi için eksik etiketi ekleyemez. Bir üretim düğümünün hangi etiketi taşıması gerektiği, kurumun politikasında yazılı kuralıdır; derleyici etiketleri grafiğe dize olarak taşır ve onlara hiçbir anlam yüklemez.

Kilit dosyasının kaydettikleri

Kilit dosyası iki tür eklentiyi farklı kaydeder. Bir üretim derlemesinden sonra release-production.lock, her dönüşüm eklentisini mutators: altında — eklentisi, rolü, ayarları ve dosyalarının her birinin içeriği ve özetiyle — taşır ve her dönüşüm eklentisini plugins: altında sabitler:

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

Hüküm eklentisi yalnızca verdict_inputs: altında, dosyasının sha256 değeriyle görünür:

verdict_inputs:
- plugin: governance/rego:0.9.0
role: ir-verdict
sources:
- digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8
path: production-support.rego

Bir hüküm eklentisi sabitlenmez. Hüküm tek başına bağlandığında — üç dönüşüm .aggrega-config.yaml dosyasından kaldırıldığında — kilit dosyası mutators: [] ve plugins: [] taşır, hükmün dosyası da verdict_inputs: altındadır. Bir dönüşüm, işlem hattının geri kalanının üzerinde çalıştığı derlemeyi değiştirir; bu yüzden kilit dosyası değişikliği yapan eklentiyi tutar. Bir hüküm yalnızca derlemenin tamamlanıp tamamlanmayacağına karar verir.

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.

Terminal window
./check.sh

check.sh, build-release yardımcısı aracılığıyla dört derleme yapar ve her sonucu bu sayfanın açıkladığıyla karşılaştırır:

  • başvuru olarak, bu çalışma alanının hiçbir yönetişim eklentisi olmayan bir kopyasında release-production.yaml;
  • buradaki release-staging.yaml ve release-production.yaml; her biri, her düğümde yukarıda listelenen etiketlerle tamamlanmalı ve üretim ağacı başvurununkiyle bayt bayt aynı olmalıdır;
  • politikası yalnızca datastore kategorisini kapsayan bir kopyada release-production.yaml; bu derleme E0005 ve yukarıdaki cümleyle durmalı, yanında başka hiçbir ret olmamalıdır.

Her derleme için bir satır, ardından etiketleri yazdırır ve herhangi bir sonuç farklıysa o derlemenin çıktısını yazdırarak 1 ile çıkar:

RELEASE GOVERNANCE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
release-production.yaml none 0 reference OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-production.yaml narrowed 1 halt OK: E0005, the expected sentence
[… omitted: the two label listings shown above]
check: every build ended as expected.

İki kopya geçici bir dizinde oluşturulur; oradan da çözümlenebilmesi için .aggrega-config.yaml dosyalarındaki katalog yolu mutlak yapılır. Bu dizindeki hiçbir dosya düzenlenmez; burada yapılan iki derleme, her derlemenin yaptığı gibi kilit dosyalarını doldurur. ./build-release.sh betiğinin çözümlediği ikili dosyayı kullanır; dolayısıyla bunu AGGREGA_BIN seçer ve -- sonrasındaki argümanlar her derlemeye ulaşır. Bu dizinde bir dist/ bulunduğu sürece başlamayı reddeder, çünkü derlemelerin yazdığı ağaçları karşılaştırır ve geride hiçbirini bırakmaz. Çıkış durumu kararın tamamıdır.

Derleyicinin yorumlamadığı yerler

Derleyici her dönüşüme düğümleri ve Release’in ortamını verir, dönüşümün karar verdiği etiketleri uygular ve sonucu hükme verir. Destek düzeyinin ne olduğunu, on-call değerinin office-hours değerinden üstün olduğunu ya da bir devtool için bir düzey gerektiğini bilmez: bu anlamlar politikaların ayarları ve kurallarıdır. Roller, yükler ve bir politikanın bir etiketi nasıl adlandırdığı için yönetişim soketi sayfasına, politikanın üründeki yeri için Yönetişim ve Uyumluluk sayfasına bakın.

Dosyalar

  • aggregate.yaml — veritabanı, önbellek ve veritabanına bağlanmış yönetim arayüzü; etiket yok.
  • manifest.yaml — her bileşen türünü ve gizli bilgi Feature’ını kendi Docker Compose Recipe’ine bağlar. İki Releases tarafından paylaşılır.
  • release-staging.yaml, release-production.yaml — iki ortam.
  • .aggrega-config.yaml — varsayılan kayıt defteri ve dört yönetişim eklemesi.
  • policies/support-tier.rego — etiket dönüştürme politikası.
  • policies/production-support.rego — karar.
  • policies/tags.yaml — seçici etiketleyicinin bileşenden etikete eşlemesi.
  • build-release.sh — tek bir Release derler ve eşdeğer aggrega build komutunu yazdırır.
  • check.sh — dört derlemeyi yapar ve her sonucu denetler.