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

İyi bilinen ek açıklamalar

Providers, platforma özgü bağlamı yapılandırmak için belirli ek açıklamaları okur — bunlar bir Release sınırında ya da bir Release bileşen girdisinde ayarlanır veya Aggregate’te bir alt sistem ya da bileşen örneği üzerinde bildirilir. Derleyicinin kendisi bu ek açıklamaların değerlerinden bağımsızdır — onları opak dizeler olarak aktarır. Her provider hangi ek açıklamaları, hangi kapsamda okuduğunu ve ek açıklama bulunmadığında hangi varsayılanın uygulanacağını bildirir. Bu bildirim, provider oluşturan bir Plugin’in spec.provider.wellKnownAnnotations alanında yer alır ve bilinçli olarak dar tutulmuştur: bir provider bir anahtarı yalnızca onu okuduğu yerde listeler. Bunların hiçbirini okumayan bir provider ise bunun yerine spec.provider.readsNoWellKnownAnnotations: true bildirir.

Bu bölümdeki destek matrisi, bildirimin taşıdığı ayrıntı düzeyinde bu bildirimlerden üretilir — provider başına girdi türü başına, çünkü bir provider bir dağıtım birimini sentezlerken bir anahtarı okuyabilir, ancak dahil edilmiş bir yapıtı oluştururken onu okuyamayabilir. Yazarken buradaki matrisi esas alın: bir hücre, o provider’ın o yolda neyi okuduğunu söyler, çünkü bir hücre provider’ın bildirmediği hiçbir şeyi söyleyemez. Provider’ın kendi oluşturma davranışı sözleşmesinin oluşturmadığı bir girdi türünü adlandıran bir bildirim, Plugin varlığı okunurken reddedilir; böylece iki iddia birbiriyle çelişemez.

Ayrılmış sözcük dağarcığı daha geniş kümedir ve bunun yerine iki yerde bulunur — hiçbir provider’ın okumadığı anahtarlar da dahil olmak üzere ayrılmış her anahtarı adlandıran bu bölüm ve yayımlama lint denetiminin kontrol ettiği ayrılmış önek kümesi.

Değişmezler

  1. Derleyici, bir provider’ın iyi bilinen ek açıklamasının değerini hiçbir zaman yorumlamaz ya da doğrulamaz: anahtarı ve değerini kademe boyunca taşır ve bir hedefin anahtara göre işlem yapmadığı yerde uyarır.
  2. Her sağlayıcı hangi ek açıklamaları okuduğunu ve hangi varsayılanları uyguladığını belgeler.
  3. Ek açıklamalar bir sınır içinde tek biçimde uygulanır. Bir değer bileşene göre değişiyorsa, bileşen düzeyindeki ek açıklamalara (sınır ek açıklamalarını geçersiz kılarak) veya bileşenin infra alanına aittir.
  4. Provider’ın iyi bilinen ek açıklamaları hiçbir zaman bileşen etiketlerini yinelemez. Component etiketleri bir bileşenin ne olduğunu tanımlar. Sınır ek açıklamaları bir bileşenin nereye dağıtıldığını tanımlar.
  5. Recipes, sağlayıcıların iyi bilinen ek açıklamalarıyla ilgilenmez. Sağlayıcı, Recipe içeriğini ürettikten sonra yerleşim bağlamını (namespace, kayıt defteri öneki, hizmet hesabı) otomatik olarak uygular.
  6. aggrega.ai/ öneki standart kitaplık için ayrılmıştır. Özel kurumsal ek açıklamalar kendi öneklerini kullanır.
  7. Release’teki Component düzeyindeki ek açıklamalar, sınır düzeyindeki ek açıklamaları geçersiz kılar (derin birleştirme, bileşen kazanır). Bir sağlayıcının birden çok sınırın çıktısını tek bir yapıtta birleştirdiği durumlarda, bir ek açıklamanın bu sınırların tümünde aynı değere çözümlenmesini gerektirebilir: helm-chart sağlayıcısı şemsiye chart’ın adını aggrega.ai/chart-name üzerinden alır ve aynı chart’a birden fazla sınır katkıda bulunup bu ek açıklamayı farklı değerlere çözümlediğinde, derleme uyuşmayan sınırları adlandırarak durur; çünkü bir chart iki ad taşıyamaz.
  8. Aggregate’in bildirdiği ek açıklamalar aynı anahtarlara, Release’in ek açıklamalarından daha düşük bir öncelikle ulaşır. Bir alt sistemde ya da bir bileşen örneğinde bildirilen bir anahtar — Aggregate’in kendisinde ya da onun içe aktardığı ve modülün kendi bileşenlerine ulaştığı bir modülde — Release’in o anahtar için değer ayarlamadığı her yerde bileşene uygulanır; Release bir değer ayarladığında, ister sınırda ister bileşenin girdisinde olsun, uygulanan Release’in değeridir. Bir katalog varlığının kendi ek açıklamaları bunu asla ayarlamaz. aggrega.ai/chart-name, Aggregate’in erişim alanının istisnasıdır: bir bileşeni değil bir birleştirmeyi adlandırır ve ona katkıda bulunan Release sınırlarından okunur.

Eksiksiz annotation matrisi

Bu matris nasıl okunur

Aşağıdaki altı kategori tablosu, ayrılmış aggrega.ai/ sözcük dağarcığındaki her annotation’ı, neyi denetlediğini ve yokluğunda provider’ın ne yaptığını adlandırır. Belirli bir provider’ın belirli bir anahtarı uygulayıp uygulamadığı daha ince bir sorudur; çünkü bir provider birden fazla girdi türü işler — dışarıdan alınmış bir yapıt (sourced), provider’ın kendisinin sentezlediği bir Workload (synthesized) ya da bir Recipe’nin artifacts: alanının bir düğümün tüm çıktısı olması (artifacts-only) — ve bir anahtar bu yollardan birinde okunurken bir başkasında erişilemez olabilir. Hangi provider’ın hangi girdi türünü işlediği ../../architecture/16-recipe-input-composition.md sayfasındadır; her birinin neyi uyguladığı ise aşağıdaki Provider ve girdi türüne göre destek bölümündedir ve bu, bu sayfanın yetkili ifadesidir.

O tablodaki her hücre üç düzeyden birini taşır:

  • Uygulanır — provider anahtarı bu girdi türünde uygular ve bunun sonucunda işlenen çıktı deterministik biçimde değişir.
  • Koşullu uygulanır — derleyici, hedef yapıtı düzenlemek yerine onun yanına ek bir geçersiz kılma üretir; dolayısıyla değerin etkili olup olmayacağı, o yapıtın kendine ait eşleşen bir anahtar sunmasına bağlıdır. Pratikte etkilidir, ama asla bir garanti değildir. Hiçbir provider koşullu bir hücre uygulamaz ve bildirim yüzeyi bunu ifade etmenin bir yolunu taşımaz; bu nedenle aşağıda üretilen tablo yalnızca diğer iki düzeyi gösterir. Bu düzey adlandırılmıştır, çünkü bu yol dışarıdan alınmış bir yapıt için gerçekten vardır ve iki düzeyli bir sözcük dağarcığı matrisi ya veremeyeceği bir garantiyi iddia etmeye ya da yolun var olduğunu tümden inkâr etmeye zorlardı.
  • Uygulanmaz — bu yolda hiçbir provider anahtarı uygulamaz: hedefin orada onun için bir işleme yuvası yoktur, dolayısıyla yerleşim mekanizması işlenen çıktıya hiçbir katkı yapmaz ve bunun yerine ne elde edeceğinizi kategori tablosunun Varsayılan sütunu söyler. Değer yine de derlemeden opak bir dize olarak, dokunulmadan geçer. Düzey, değerin akıbetine göre değil mekanizmaya göre adlandırılmıştır; çünkü bunlar farklı sorulardır ve bir hücrenin yanıtlayabileceği yalnızca ilkidir: bir provider’ın neyi uyguladığı, o hedefin işleme yuvalarının bir özelliğidir ve her hücrenin arkasındaki bildirimin ifade ettiği de tam olarak budur.

İki kapsam vardır ve girdi türünü anlamlı bir eksen yapan yalnızca biridir:

  • Düğüm kapsamlı — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account ve aggrega.ai/kubernetes-version, bir bileşenin kendi işlenen çıktısını biçimlendirir; bu çıktıyı, bileşenin girdi türünün seçtiği yol üretir. Bunlar tablonun sütunlarıdır.
  • Derleme ve başvuru kapsamlı — aggrega.ai/chart-name, bir şemsiye chart birleştirildiğinde bir kez çözümlenir; üç aggrega.ai/aws-* anahtarı ise bir başvuru bir sınırı geçtiğinde çözümlenir. Girdi türü ikisi için de bir eksen değildir: katkıda bulunan her düğüm nasıl işlenmiş olursa olsun, değer birleştirmede ya da başvuruda okunur. Bunların kendi tablosu Birleştirme ve başvuru başına çözümlenen anahtarlar bölümündedir.

Kategori 1 — Yerleşim

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/namespacehelm (sourced, synthesized); compose (sourced, synthesized)Kubernetes namespace’i (helm); Docker ağ adı (compose)Yoksa eklenmez (helm); compose dosyasının yoluna göre adlandırılan ve o dosyada ek açıklaması olmayan her düğümün paylaştığı bir ağ (compose)
aggrega.ai/project-nameayrılmıştır; hiçbir provider okumazBir Docker Compose proje adı için ayrılmıştır—
aggrega.ai/regionayrılmıştır; hiçbir provider okumazYerleşim kapsamında bir bulut bölgesi için ayrılmıştır—
aggrega.ai/account-idayrılmıştır; hiçbir provider okumazYerleşim kapsamında bir bulut hesap tanımlayıcısı için ayrılmıştır—
aggrega.ai/kubernetes-versionhelm (sourced)Bileşenin dağıtıldığı kümenin Kubernetes sürümü; kaynaktan işlenen bir chart bunu .Capabilities.KubeVersion olarak okurAynı helm sürümünün standart helm template komutunun işlediği sürüm: provider’ın derlendiği Kubernetes istemci kütüphanesinin sürümü

aggrega.ai/namespace tasarım gereği çift amaçlıdır. Aynı mantıksal yalıtım niyetini — “bu sınırın kaynakları kendi adreslenebilir kapsamlarında yaşar” — her hedefin yerel biçiminde ifade eder: helm için bir Kubernetes metadata.namespace, compose için bir Docker ağ adı. Recipe yazarları tek bir annotation belirler; her provider bunu hedef için uygun biçimde somutlaştırır. Compose durumunda ağ adı, düğüm başına o düğümdeki annotation’dan çözümlenir; düğüm annotation taşımıyorsa compose dosyasının yoluna geri dönülür — böylece tek bir compose dosyasını paylaşan annotation’sız sınırlar tek bir ağı paylaşır ve onları ayıran şey aggrega.ai/namespace olur. Kimliği bu ikisinden hangisi sağlarsa sağlasın, kimlik ardından bir compose ağ adının kabul ettiği karakterlerle yazılır — diğer her karakter yerine başka bir karakter konmak yerine bir kaçış dizisi olarak yazılır; böylece herhangi bir biçimde farklılaşan iki kimlik iki ayrı ağda kalır ve kimliğin büyük/küçük harf durumu yazıldığı gibi korunur. Compose provider başvurusu, kodlanmış bir adın nasıl okunacağı ve bir yeniden adlandırmanın neye mal olduğu da dahil olmak üzere türetmeyi eksiksiz belgeler.

aggrega.ai/kubernetes-version, bileşenin kümenin neresine yerleştiğini değil, dağıtıldığı kümenin bir özelliğini belirtir: chart şablonları bir API sürümünü, bir alanı ya da bütün bir mekanizmayı işlendikleri sürüme göre seçer ve derlemenin soracağı bir küme yoktur. Helm provider değeri, helm template --kube-version komutunun kendi bayrağını okuduğu şekilde okur ve sürüm olmayan bir değerde derlemeyi durdurur; hiçbir sürüm belirtilmemişse chart, aynı helm sürümünün helm template komutunun işlediği sürüm için işlenir. Helm provider başvurusu kabul edilen biçimleri ve varsayılanı belgeler.

Kategori 2 — Kayıt defteri

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/image-registryhelm, compose — yalnızca synthesizedKapsayıcı imajları için kayıt defteri öneki; sentezlenen her kapsayıcı imajı başvurusuna uygulanırÖnek yok
aggrega.ai/image-pull-secrethelm — yalnızca synthesizedKubernetes imagePullSecrets adı; sentezlenen pod’un mevcut girdileriyle birleştirilirYok

Kategori 3 — Ağ

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/cluster-domainayrılmıştır; hiçbir provider okumazNamespace’ler arası hizmet keşfi için bir DNS soneki için ayrılmıştır—
aggrega.ai/ingress-classayrılmıştır; hiçbir provider okumazIngress kaynaklarında bir Kubernetes IngressClass için ayrılmıştır—
aggrega.ai/service-meshayrılmıştır; hiçbir provider okumazMesh sidecar ekleme annotation’ları için ayrılmıştır—

Kategori 4 — Güvenlik

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/service-accounthelm — yalnızca synthesizedSentezlenen Pod’lar için Kubernetes ServiceAccount; ikisi de belirlendiğinde Recipe’nin workload.serviceAccount değerini geçersiz kılarRecipe’nin workload.serviceAccount değeri ya da Recipe hiçbirini bildirmiyorsa belirlenmemiş
aggrega.ai/pod-security-standardayrılmıştır; hiçbir provider okumazBir Pod Security Standards düzeyi için ayrılmıştır—
aggrega.ai/iam-roleayrılmıştır; hiçbir provider okumazBir iş yüküne bağlı bir bulut kimlik rolü için ayrılmıştır—

Kategori 5 — Paketleme

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/chart-namehelm-chart — birleştirme başınaŞemsiye chart adıAggregate adı ile şemsiyenin derleme yolunun birleşimi — bkz. Chart adı çözümlemesi
aggrega.ai/chart-versionayrılmıştır; hiçbir provider okumazBir Helm chart sürümü için ayrılmıştır—
aggrega.ai/stack-nameayrılmıştır; hiçbir provider okumazAçıkça adlandırılmış bir yığın için ayrılmıştır—
aggrega.ai/tf-backendayrılmıştır; hiçbir provider okumazBir Terraform durum arka ucu tanımlayıcısı için ayrılmıştır—

Kategori 6 — Bulut hedefi

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/aws-accountcloudformation — sınırlar arası her başvuru içinYığının (sınırın) dağıtıldığı AWS hesabıAynı hesap — yığınlar arası bir başvuru, aynı hesaptaki bir yığın dışa aktarımının içe aktarılmasıyla çözümlenir
aggrega.ai/aws-regioncloudformation — sınırlar arası her başvuru içinYığının (sınırın) dağıtıldığı AWS bölgesiAynı bölge — yığınlar arası bir başvuru, aynı bölgedeki bir yığın dışa aktarımının içe aktarılmasıyla çözümlenir
aggrega.ai/aws-assume-role-arncloudformation — sınırlar arası her başvuru içinHesaplar arası bir yığın okumasının, eş yığının dışa aktarılan değerlerine ulaşmak için üstlendiği IAM rolü ARN’siHesaplar arası bir başvuruda hiçbir rol sağlanmaz

Her CloudFormation sınırı tek bir yığına işlenir. Bir uses kenarı bir sınırdan diğerine geçtiğinde, cloudformation provider’ının başvuruyu biçimlendirmek için eş yığının nerede bulunduğunu bilmesi gerekir: aynı hesap ve bölgedeki iki yığın değerleri bir yığın dışa aktarımı ve içe aktarımıyla paylaşır; farklı bir hesap veya bölgedeki bir eş ise isteğe bağlı olarak üstlenilen bir rol altında, hesaplar arası bir yığın çıktısı okuması gerektirir. Bu ek açıklamalar söz konusu yerleşim bağlamını taşır. Her biri, provider böyle bir başvuruyu biçimlendirdiği anda okunur ve o anda olağan ek açıklama kademesiyle çözümlenir — bileşende ayarlanan bir değer, sınırda ayarlanan bir değere üstün gelir ve Release’in ayarladığı bir değer, Aggregate’in bildirdiği bir değere üstün gelir. Bu nedenle sınır düzeyinde bir değer, bunları ifade etmenin yaygın yoludur, ancak tek yolu değildir. Bunlar opak skaler işaretçi dizeleridir — provider bunları oluşturduğu başvuruya aktarır ve hiçbir zaman canlı AWS durumuna karşı çözümlemez; hesap, bölge ve rol Release tarafından sağlanır ya da Aggregate’te bildirilir ve son fiziksel okumayı çalışma zamanı ortamı çözümler. Ek açıklamaların hiçbiri bulunmadığında provider, eşi aynı hesapta ve aynı bölgede kabul eder ve hiçbir rol sağlamaz.

Provider ve girdi türüne göre destek

Düğüm kapsamlı anahtarlar, provider başına ve girdi türü başına. Sütun başlıkları her anahtarın taşıdığı aggrega.ai/ önekini içermez. applied ve — yukarıda tanımlanan katmanları taşır; — uygulanmaz anlamındadır; n/a, provider’ın o girdi türünü hiç işlemediği, dolayısıyla orada anahtarın uygulanabileceği veya kaçırılabileceği bir yolun bulunmadığı anlamına gelir.

ProviderGirdi türünamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Derleyiciyle birlikte dağıtılan her provider’ın burada satırları vardır; hiçbir yerleşim ek açıklamasını okumayan provider da buna dahildir — boş bir satır kümesi, henüz kimsenin tanımlamadığı bir provider’dan ayırt edilemezdi. Ayrıca sağlanan bir provider okuduklarını aynı şekilde bildirir ve burada listelenmez, çünkü yayımlanmış bir sayfa hiç görmediği provider’ları sayamaz.

Bir Recipe aynı anda birden fazla girdi türü bildirebilir — örneğin yanında artifacts: bulunan bir workload:. Tabloyu tür başına okuyun: böyle bir düğümün sentezlenmiş çıktısı synthesized satırıdır, yapıt dosyaları ise yapıtlar durumudur. artifacts-only satırı, bir Recipe’nin yalnızca artifacts: bildirdiği girdi türüdür.

Bunu öğrenmek için tabloya bakmanız gerekmez. İşlemelerinizden birinin hedefinin, o işlemenin girdi türlerinin hiçbirinde okumadığı bir anahtarı ayarlamak; anahtarı, hedefi ve o işlemenin bildirdiği her girdi türünü belirten bir uyarı üretir; böylece yanlışlıkla düştüğünüz bir hücre, sizin buraya bakmayı akıl etmenizi beklemeden, derleme anında kendini gösterir:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Birden fazla girdi türü bildiren bir işlemede uyarı, yarılarından biriyle değil, o işlemenin bütünüyle ilgilidir. Türler toplama yoluyla birleştiğinden, anahtarı bunlardan herhangi birinde okuyan bir hedef anahtarı gerçekten uygular ve o işlemenin çıktısı sonucu taşır — bu yüzden uyarı verilmez. Uyarı yalnızca o işlemenin bildirdiği her tür anahtarı kaçırdığında görünür ve hepsini belirtir:

warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it

Dolayısıyla bir source: yanındaki bir workload:, aggrega.ai/service-account anahtarının o düğümde etkili olması için yeterlidir ve derleme bu konuda sessiz kalır — bu dürüst bir rapordur, çünkü değer sentezlenmiş yarıya ulaşır ve üretilen manifestlerde görünür.

Tabloyu bileşen başına değil, işleme başına okuyun. Bir düğüme bağlanan bir özellik, kaynaklarını kendi FeatureRecipe’sinin adlandırdığı hedef üzerinden, o FeatureRecipe’nin bildirdiği girdi türlerinde üretir — bu yüzden bu tabloda kendi satırına düşer ve bu satırın, ev sahibi bileşenin düştüğü satır olması gerekmez. Workload’unu sentezleyen ve bağlı bir özelliğin yanına artifacts: kattığı bir bileşen, kendi manifestleri için synthesized satırını, bağlantının dosyaları için artifacts-only satırını okur; ilkinde uygulanan bir anahtar ikincisinde kaçırılabilir. Uyarı da aynı ayrımı izler ve her birini ayrı ayrı bildirir, çünkü bunlar farklı dosyalardır. Adlandırılmış bir bileşen yerine bir sınıra bağlanan bir özellik de tabloyu aynı şekilde okur.

Değer yine de dokunulmadan geçer — derleme durmaz, çünkü heterojen hedeflerdeki bileşenleri kapsayan bir sınırda belirli bir anahtar üzerinde işlem yapamayan bir işleme her zaman olacaktır ve bu bir hata değil, olağan bir Release’tir. Bir sınır ek açıklaması kademeli olarak aktarılır; bu nedenle yazılmış tek bir satır, onun üzerinde işlem yapamayan her işleme için bir uyarı üretir; çıktınızın hangi kısımlarının etkilendiğini bu şekilde görürsünüz. Uyarı unsupported-field sınıfına aittir ve o sınıfın bayrağıyla susturulur; ayrıntılar Warnings sayfasındadır. Bilinmesi gereken iki sınır vardır: yalnızca yalın aggrega.ai/ anahtarları denetlenir, çünkü alt önekli bir anahtar sizin kendi sözcük dağarcığınızdır; ve hiçbir destek beyanı bildirmeyen bir provider uyarı üretmez, çünkü yazdıklarınızın karşılaştırılacağı bir şey yoktur. Bu anahtarların hiçbirini okumadığını bildiren bir provider bu şekilde sessiz kalmaz: Plugin varlığındaki readsNoWellKnownAnnotations: true, hiçbir anahtarı kapsamayan bir beyandır; bu nedenle işlemelerinden birine ulaşan her yalın anahtar uyarıya yol açar. terraform provider’ı bunu bildirir.

Satıcıdan alınmış bir yapıt neden daha az anahtar uygular. Düğüm kapsamlı bir ek açıklama, provider’ın onun için bir işleme yuvasına sahip olduğu yerde uygulanır. Provider dağıtım birimini kendisi sentezlediğinde sonucun her alanına sahiptir; bu yüzden bir kayıt defteri öneki, bir çekme sırrı ve bir hizmet hesabının hepsinin yerleşeceği bir yer vardır. Satıcıdan alınmış bir yapıt — bir Helm chart’ı, bir compose dosyası, bir Terraform modülü — bunun yerine kendi yapılandırma arayüzünü taşır ve derleyici bu arayüzü okumaz; bu nedenle bir kayıt defteri önekinin veya bir hizmet hesabının yapıtın kendi anahtarlarından hangisine karşılık geleceğini bilemez. Çevreleyen işleme çağrısının denetlediği yerleşim yine uygulanır; aggrega.ai/namespace anahtarının kaynaktan işlenen bir chart’a uygulanmasının nedeni budur. Bir değerin başka birinin yapıtının içinde nereye ait olduğuna karar vermeyi gerektirecek yerleşim ise uygulanmaz ve yazar bunu o yapıtın kendi değerleri üzerinden sağlar. Sourced satırlarının seyrek, synthesized satırlarının dolu olmasının nedeni budur ve sonradan eklenecek her anahtar için de beklenmesi gereken biçim budur.

Derleme başına ve başvuru başına çözümlenen anahtarlar

Birlikte gelen anahtarlardan dördü düğüm kapsamlı değildir; bu nedenle yukarıdaki tabloya katılmak yerine onun dışında yer alırlar: girdi türü bunlar için anlamlı bir eksen değildir ve her birine girdi türü başına bir satır vermek tek bir hücreyi üç kez tekrarlar ve var olmayan bir ayrımı ima eder. Her biri sınır kapsamını bildirir ve aşağıdaki tablo bu bildirimlerden üretilir.

AnnotationUygulayanAmaçVarsayılan
aggrega.ai/chart-namehelm-chartBirleştirilen şemsiye Helm chart’ının adı.Aggregate adı ve şemsiye chart’ın derleme yolu — dist/ altındaki çıktı dizini, örneğin boundaries/data/helm-chart — kullanılır; her biri kodlanır ve birleştirilir.
aggrega.ai/aws-accountcloudformationYığının (sınırın) dağıtıldığı AWS hesabı. Sınırlar arası bir başvuru, eş yığının aynı hesapta olup olmadığına karar vermek için bunu okur.Eş, aynı hesapta kabul edilir ve yığınlar arası bir başvuru, hesaplar arası bir yığın çıktısı okuması yerine aynı hesaptaki bir yığın dışa aktarımı içe aktarımıyla çözümlenir.
aggrega.ai/aws-regioncloudformationYığının (sınırın) dağıtıldığı AWS bölgesi. Sınırlar arası bir başvuru, eş yığının aynı bölgede olup olmadığına karar vermek için bunu okur.Eş, aynı bölgede kabul edilir ve yığınlar arası bir başvuru, aynı bölgedeki bir yığın dışa aktarımı içe aktarımıyla çözümlenir.
aggrega.ai/aws-assume-role-arncloudformationHesaplar arası bir yığın okumasının, eş yığının dışa aktarılan değerlerine ulaşmak için üstlendiği IAM rolü ARN’si.Hiçbir rol sağlanmaz ve hesaplar arası bir başvuru hiçbir assume-role taşımaz.

Her birinin ne zaman çözümlendiği; bunu bildirimin kendisi taşımaz. aggrega.ai/chart-name, sınır ek açıklama kademesinden, şemsiye chart derlemesi başına bir kez çözümlenir; bir derlemeye katkıda bulunan herkes onu aynı değere çözümlemelidir ve uyuşmazlık, sınırları adlandırarak derlemeyi durdurur. Üç aggrega.ai/aws-* anahtarı, bileşenin sınıra önceliği altında sınırlar arası başvuru başına çözümlenir; böylece bileşen değeri sınır değerine üstün gelir. Her birinin şekillendirdiği başvuruyu yukarıdaki Kategori 6 açıklar.

Hiçbir sağlayıcının okumadığı ayrılmış adlar

Yukarıdaki matristeki on bir anahtar ayrılmış; hiçbir sağlayıcı okumaz olarak işaretlenmiştir: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name ve aggrega.ai/tf-backend.

Bunlardan birini bir Release üzerinde ya da bir Aggregate’te ayarlamanın işlenen çıktı üzerinde hiçbir etkisi yoktur. Hiçbir sağlayıcı bunları okumaz ve onlar adına hiçbir varsayılan uygulanmaz; özellikle aggrega.ai/cluster-domain için hiçbir DNS soneki uygulanmaz, bu nedenle küme alan adına ihtiyaç duyan bir Recipe bu ek açıklamaya güvenmek yerine onu sıradan bir değer olarak sağlamalıdır. Bu davranışlardan birine ihtiyaç duyan bir Recipe yazarı bunu bir Recipe değeri veya bir bileşen infra alanı olarak ifade eder.

Bu on bir anahtarı hiçbir sağlayıcı bildirmez. Bir sağlayıcının wellKnownAnnotations alanı yalnızca okuduklarını listeler, bu yüzden on birden hiçbiri orada görünmez; helm, helm-chart, compose veya cloudformation Plugin’ini açan bir okuyucu çalışan anahtarları görür, başka hiçbir şeyi görmez. Dar bildirimin amacı budur: bildirilen bir anahtar çalışan bir anahtardır ve yanındaki kapsam hangi yolda çalıştığını söyler.

Ayrılmış adlardan ikisi canlı anahtarlara yakındır ve onlarla birbirinin yerine kullanılamaz. aggrega.ai/region ve aggrega.ai/account-id, yerleşim kapsamında bir bölge ve bir hesap adlandırır ve hiçbir sağlayıcıya ulaşmaz; cloudformation sağlayıcısının okuduğu anahtarlar Kategori 6’daki bulut ad alanlı aggrega.ai/aws-region ve aggrega.ai/aws-account anahtarlarıdır. CloudFormation yığınlar arası yerleşim bağlamını kastettiğinizde aws- biçimini yazın; öneksiz çift çakışmaya karşı ayrılmıştır, hiçbir şeye bağlı değildir. İki ayrılmış ad daha bir ek açıklama yerine başka yüzeylerce karşılanır: aggrega.ai/stack-name ayrılmıştır, bir cloudformation sınırının işlendiği yığın adı ise sürüm ve sınır kimliğinden deterministik olarak türetilir; bir iş yükünün bulut kimlik rolü de aggrega.ai/iam-role aracılığıyla değil, bağlamayı üreten Feature üzerinde operatörün ayarladığı sıradan bir alan olarak sağlanır.

Adlar ayrılmış kalır ve burada listelenmeye devam eder, çünkü aggrega.ai/ öneki ayrılmıştır: bir kurumsal katalog bu anahtarlardan birini kendi anlamı için yeniden kullanmamalıdır, çünkü platform anahtarı kendine ait bir anlam için tutar. Bu matris ve yayımlama lint’inin denetlediği ayrılmış önek kümesi birlikte ayırma kaydını oluşturur ve ikisi, her ikisini okuyan ve ayrıştıklarında başarısız olan bir denetimle aynı ad kümesine bağlı tutulur. Bu nedenle on birden birini yazmak ne doğrulamayı başarısız kılar ne de “öneksiz aggrega.ai/ önekini kullanmayın” kuralını tetikler; yalnızca hiçbir etkisi olmaz.

Bir helm-chart sınırının ürettiği şemsiye chart sürümü her zaman 0.1.0 olur; bu bir aggrega.ai/chart-version varsayılanı değil, sabit bir değerdir.

Not: aggrega.ai/ önekini kullanan Manifest features.annotations bağlamaları yükleme sırasında reddedilir; önek yalnızca bu bölümde belgelenen sağlayıcı iyi bilinen ek açıklamalarına ayrılmıştır. Ek açıklama güdümlü Feature bağlamalarının yazarları standart kitaplık kısayolları için feature.aggrega.ai/, kurumsal kısayollar için özel bir alan adı kullanır.

Not: bir Release ek açıklamasındaki açık null, devralınan bağlamayı geçersiz kılan sınırdan veya bileşenden kaldırır (ek açıklama güdümlü Feature devre dışı bırakma). Aynı sınırda devre dışı bırakmayan kardeş bileşenler devralınan bağlamayı korur; bulunmayan anahtarlar her zamanki gibi üst kademeden devralmaya devam eder.

Derleyicinin okuduğu, katalogda yazılan ek açıklamalar

Yukarıdaki her şey bir provider ek açıklamasıdır: Release üzerinde yazılır ya da Aggregate’te bildirilir, derleyici tarafından opak bir dize olarak iletilir ve bir provider tarafından okunur. İkinci ve çok daha küçük bir sözcük dağarcığı ters yönde işler: Architect tarafından bir katalog varlığının kendi metadata.annotations alanında yazılır, derleyici tarafından okunur ve hiçbir provider tarafından görülmez. Yukarıdaki 1. değişmez provider sözcük dağarcığıyla ilgilidir ve bunları kapsamaz; derleyici tam olarak burada listelenen anahtarları okur, başkalarını okumaz.

Bu anahtarlar yalın aggrega.ai/ önekinin değil, bir <scope>.aggrega.ai/ alt önekinin altında yer alır; bu nedenle yukarıdaki matrisin taşıdığı ayırma kaydının ve yayımlama lint denetiminin yalın önekli anahtarlara uyguladığı ayrılmış önek kuralının dışındadır.

AnnotationYazıldığı yerOkuyanAmaç
features.aggrega.ai/requiredType.<label>Component metadata.annotationsson hâline getirilmiş grafik üzerinde derleyiciBir varlık zorunluluğu bildirir: bu Component’in her örneği, türü ek açıklamanın değerine eşit olan en az bir eklenti taşımalıdır. <label>, tanılamada gereksinimi adlandıran, yazarın seçtiği bir sonektir; bir yuva adı değildir ve hiçbir şey ona başvurmaz. Birden çok zorunluluk bildirmek için anahtarı farklı etiketlerle yineleyin.

Zorunluluk, herhangi bir kapsamdaki bir eklentiyle karşılanır (bileşen düzeyinde veya alt sistem düzeyinde bir features: bloğu, Release’in sınır düzeyinde veya bileşen düzeyinde bir bloğu ya da ek açıklama güdümlü genişletme), çünkü her eklentinin nereden geldiğini değil, örneğin son eklenti kümesini sınar. Karşılanmayan bir zorunluluk, etiketi ve gerekli türü adlandırarak derlemeyi durdurur; Feature türü URI’si olmayan bir değer ya da önekten sonra etiketi olmayan bir anahtar, ayrı bir hatalı bildirim tanılamasıyla durdurur. Yazımın tam açıklaması ve bir zorunluluğun bir featuresSchema yuvasından nasıl ayrıldığı entities/component.md “Presence mandates” bölümündedir.

Provider’ların ürettiği köken etiketleri

Yukarıdaki açıklamalar derlemeye doğru akar: Release ya da Aggregate onları yazar, provider’lar onları tüketir. Provider’lar ayrıca derlemenin dışına doğru paralel bir etiket kümesi üretir ve bunları işlenmiş çıktıya ekler; böylece aşağı akıştaki araçlar çalışma zamanı kaynaklarını onları üreten katalog içeriğine geri bağlayabilir. Bu köken etiketleri Release üzerinde yazılmaz; derlemenin kendi durumundan (Recipe kimliği, sınır yolu, aggregate adı, ortam, senkronizasyon dalgası, derleyici sürümü) türetilir ve işleme anında provider tarafından üretilir.

Sağlayıcıların ürettiği küme; helm sağlayıcısının işlediği her Kubernetes manifestine, helm-chart sağlayıcısının bir alt chart’a eklediği $import: ile yüklenen her yapıta ve compose’un ürettiği her servise eklenir — bir helm-chart alt chart’ının kendi şablonları yazarının yazdığı gibi kopyalanır, bu nedenle o yazarın yazdığı her şeyi taşır:

EtiketKaynakÜretim
app.kubernetes.io/nameDüğüm kimliği (ya da bir FeatureRecipe’in ürettiği bir kaynak için o eklenti için türetilen tanımlayıcı — aşağıya bakın)Yalnızca helm ve helm-chart — Kubernetes standardı etiket, compose servislerinde üretilmez
aggrega.ai/component-idDüğüm kimliği (ya da bir FeatureRecipe’in ürettiği bir kaynak için o eklenti için türetilen tanımlayıcı — aşağıya bakın)Üç provider’ın tümü
aggrega.ai/recipe-uriÜreten Recipe’in (ya da FR tarafından üretilen kaynaklar için üreten FeatureRecipe’in) <recipe-name>:<recipe-version> değeriÜç provider’ın tümü, üreten varlıkta hem ad hem sürüm ayarlı olduğunda; helm ve helm-chart’ta bir ek açıklama
aggrega.ai/boundary-pathBileşenin yönlendirildiği sınır yoluÜç provider’ın tümü, sınır yolu boş olmadığında; helm ve helm-chart’ta bir ek açıklama
aggrega.ai/aggregate-nameAggregate metadata.nameÜç provider’ın tümü, ayarlı olduğunda
aggrega.ai/compiler-versionDerleme anında damgalanan derleyici sürümüÜç provider’ın tümü, ayarlı olduğunda
aggrega.ai/providerKaynağı işleyen sağlayıcıÜç provider’ın tümü
aggrega.ai/provider-versionO sağlayıcının sürümüÜç provider’ın tümü
aggrega.ai/environmentRelease metadata.environmentÜç provider’ın tümü — her Release bunu bildirir
aggrega.ai/sync-waveSınır başına syncWave tamsayısıÜç provider’ın tümü, sıfırdan farklı olduğunda; helm ve helm-chart’ta bir ek açıklama

aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider ve aggrega.ai/provider-version değerleri, derlemenin Kubernetes etiket değeri kurallarına uymaya zorlamadığı dizelerden gelir — imported/flow adlı bir Aggregate, eu/prod adlı bir ortam, bir geliştirme derlemesinin (devel) sürümü gibi. helm ve helm-chart üzerinde, değer zaten geçerli bir etiket değeriyse bu etiketlerin her biri değerini yazıldığı gibi taşır: harfler, rakamlar, -, _ ve ., her iki uçta bir harf ya da rakam, en fazla 63 karakter. Aksi takdirde etiket, bu biçime yeniden yazılmış değeri taşır — diğer her karakter - olur, ardışık - dizileri teke indirilir, uçlar bir harfe ya da rakama kadar kırpılır ve sonuç en fazla 63 karaktere kesilir — ve değerin birebir hâli aynı anahtar altında bir ek açıklama olarak eklenir. Bu nedenle imported/flow adlı bir Aggregate, aggrega.ai/aggregate-name: imported-flow etiketini ve aggrega.ai/aggregate-name: imported/flow ek açıklamasını alır; bir etiketin koruduğu hiçbir karakteri içermeyen bir değer yalnızca ek açıklama tarafından taşınır. Bir seçici, etiket değerini işlenmiş çıktıda göründüğü hâliyle eşleştirir ve tam adı gereken araçlar, varsa ek açıklamayı okur. Etiket değerleri kısıtlanmamış olan Compose, değerin birebir hâlini etiket olarak taşır.

Provider başına üretim notları

  • helm — etiketler işlenen her Kubernetes kaynağında (Deployment, Service, PVC vb.) metadata.labels içine, bir etiket değerinin taşıyamadığı anahtarlar — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave ve yukarıda açıklandığı gibi yeniden yazılan her etiketin birebir değeri — ise metadata.annotations içine yerleşir. Kaynaklı mod (işleme sonrası etiket enjeksiyonuyla Helm SDK işlemesi), sentezlenmiş mod (workload sentezi) ve artifacts: yolları aynı kümeyi üretir.
  • helm-chart — aynı etiketler ve ek açıklamalar, sağlayıcının bir alt chart’ın templates/ dizinine eklediği $import: ile yüklenen her yapıta yerleşir. Kaynak chart’ın kendi şablonları ve alt chart kökünde yer alan satır içi içerikli bir yapıt bunların hiçbirini taşımaz — bkz. helm-chart.md.
  • compose — etiketler üretilen her compose servisinde services.<name>.labels içine yerleşir. Kaynaklı mod (birleştirilmiş temel + valuesMapping belgesine birleştirme sonrası etiket enjeksiyonu) ve sentezlenmiş mod (servisin etiket bloğunu doğrudan ayarlayan workload sentezi) aynı kümeyi üretir. Kubernetes’e özgü app.kubernetes.io/name, compose çıktısından çıkarılır.

Bir FeatureRecipe’in ürettiği kaynaklar için aggrega.ai/component-id değeri, ana bileşenin adından değil eklentiden oluşturulur — bir FeatureRecipe’in bu kaynakları teslim edebileceği her yol için; böylece bir eklentinin kaynakları etiket bakımından ana bileşenin kendi kaynaklarından asla ayırt edilemez hâle gelmez. Bu kimliğin aynı zamanda o kaynakların adlandırılmasına da temel olup olmadığı teslim biçimine bağlıdır: Aggrega’nın sentezlediği bir workload kimliğe göre adlandırılırken, eklentinin yazarının sağladığı bir chart veya parça ana bileşenin Helm release adını ve çıktı dosyası önekini korur, çünkü yazarın kendi şablonları bu ada göre işlenir. Değerin nasıl oluşturulduğu — iki başlangıç, parçalar ve bunların -- ile birleştirilmesi, bir etiketin taşıyamadığı bir karakterin nasıl yazıldığı, hedefi için fazla uzun bir değerin nasıl kısaltıldığı ve hangi adlara temel olup hangilerine olmadığı — provider’dan bağımsızdır; bu nedenle burada tekrarlanmak yerine bir kez vocabulary/labels-and-annotations.md “Provenance labels emitted on rendered output” bölümünde belirtilir. Bu sayfa diğer yarıdan sorumludur: etiketlerin her provider’ın işlenmiş çıktısında nereye yerleştiği.

aggrega.ai/recipe-uri, tüketen Recipe’in kimliğine değil FeatureRecipe’in kendi name:version değerine çözümlenir — üreten varlığı belirlemek için etiketi okuyan aşağı akış araçları, hem bileşenin ürettiği hem de FR’nin ürettiği çıktı için doğru kökeni elde eder.

Sync-wave ek açıklamaları

Yukarıdaki aggrega.ai/sync-wave anahtarı, aşağı akış araçlarının uyguladıklarını sıralamak için okuduğu bir sync-wave ek açıklamasıyla eşlenir. compose’da anahtar bir etikettir ve dalga değerini seçici sorguları için sunar; helm ve helm-chart’ta ise bir ek açıklamadır ve eşlenen ek açıklama değeri her aracın uzlaşım gereği okuduğu yerde ortaya koyar.

AnnotationÜretimKullanan
argocd.argoproj.io/sync-wavehelm, işlediği her Kubernetes kaynağında, ve helm-chart, $import: ile yüklenen her yapıtta — katkıda bulunan sınırda syncWave sıfırdan farklı olduğundaArgoCD’nin sync-wave sıralaması
helm.sh/hook-weightYalnızca helm; syncWave sıfırdan farklı olduğunda, zaten bir helm.sh/hook ek açıklaması taşıyan chart şablonlu manifestlerdeHelm’in bir hook aşaması içindeki hook-weight sıralaması

helm.sh/hook-weight üretimi yola bağlıdır

Chart yazarları için belirtilmeye değer bir incelik: helm.sh/hook-weight yalnızca chart şablonlama yolu üzerinden, yani chart’ın templates/ dizininin Helm SDK aracılığıyla işlenmesiyle üretilen manifestlere yazılır. Artifacts yolu üzerinden üretilen Manifests — helm sağlayıcısında Recipe’nin artifacts: bloğunun her girdisi, satır içi içerik ya da $import: ile yüklenmiş, helm-chart’ta ise $import: ile yüklenmiş bir girdi — argocd.argoproj.io/sync-wave ek açıklamasını ve köken etiketlerinin tam kümesini taşır, ancak helm.sh/hook-weight almaz; yapıt bir helm.sh/hook ek açıklaması taşısa bile.

Bu ayrım yapısaldır: helm.sh/hook ve helm.sh/hook-weight, chart şablonlu hook kaynaklarına uygulanan Helm çalışma zamanı sıralama temel öğeleridir. Recipe yazarının artifact’leri, Recipe katmanında bildirilen ek kaynaklardır; varsayılan olarak Helm’in hook yaşam döngüsüne katılmazlar.

Bir hook kaynağında Helm hook-weight sıralamasına ihtiyacınız varsa, kaynağı bir artifacts: girdisi olarak değil, helm sağlayıcısının işlediği bir Recipe’nin source: dizini altında bir chart şablonu olarak yazın; bir helm-chart alt chart’ının şablonları yazıldığı gibi kopyalanır ve iki ek açıklamadan hiçbirini almaz. Chart şablonu, katkıda bulunan sınırın syncWave değeriyle eşleşen hem argocd.argoproj.io/sync-wave hem de helm.sh/hook-weight alır.

Yazım örnekleri

Sınır düzeyinde yerleşim ve kayıt defteri yapılandırması:

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
aggrega.ai/image-registry: registry.corp.com
aggrega.ai/image-pull-secret: corp-registry-creds
components:
api: {}
worker: {}

Bileşen başına geçersiz kılma (aynı ek açıklama anahtarında bileşen, sınıra üstün gelir):

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
components:
api: {}
legacy-thing:
annotations:
aggrega.ai/namespace: legacy-east # override — this component deploys elsewhere

Aggregate tarafı ek açıklama basamaklaması

Ek açıklamalar Aggregate yazım yüzeyinde de bulunur: alt sistem kapsamında (spec.subsystems.<name>.annotations) ve bileşen örneği kapsamında (spec.subsystems.<name>.components.<name>.annotations ya da üst düzey bileşenler için spec.components.<name>.annotations). Aggregate tarafı basamaklama, geliştiricinin yazdığı ek açıklamaları alt sistem ağacı boyunca içerilen bileşenlere taşır.

Basamaklama kuralı

Alt sistem düzeyindeki bir ek açıklama, alt sistemin alt ağacındaki her iç içe alt sisteme ve içerilen her bileşene yayılır. Daha yakın düzeydeki ek açıklamalar, dış düzeydeki ek açıklamaları anahtar başına ayrıntı düzeyinde geçersiz kılar: bileşen düzeyindeki bir ek açıklama, aynı anahtar için devralınan her alt sistem düzeyi ek açıklamayı, kardeş anahtarları veya kardeş bileşenleri etkilemeden geçersiz kılar.

Bir kapsamdaki ek açıklama anahtarı üç durumdan birindedir:

  • Bulunmayan anahtar — kapsam bu ek açıklama için hiçbir değer bildirmez. İç içe alt sistemler ve içerilen bileşenler, bir üst kapsamdaki her bağlamayı devralır.
  • Bir dize değeri — kapsam bir değer bildirir. İç içe alt sistemler ve içerilen bileşenler, kendi değerlerini bildirmedikçe veya devre dışı kalmayı seçmedikçe bu değeri devralır.
  • Açık YAML null — kapsam, bu anahtar için devralınan her bağlamayı kendi alt ağacından kaldırır. Kardeş bileşenler ve kardeş alt sistemler bağımsız devralmalarını korur; bağlamayı yalnızca devre dışı kalmayı seçen kapsamın alt ağacı kaybeder.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Aggregate’te bildirilen Provider ek açıklamaları

Yukarıdaki matristeki anahtarlar Aggregate boyunca da kademeli olarak aktarılır ve sağlayıcı, kademenin her bileşen üzerinde bıraktığını uygular. Bir alt sistemin aggrega.ai/namespace değeri altındaki her bileşeni yerleştirir; bir bileşen örneğinin kendi değeri ise bunun yerine o bileşeni yerleştirir. Aggregate’in içe aktardığı bir modül kendi kademesini taşır: alt sistemleri ve bileşen örnekleri modülün kendi bileşenlerine ulaşır ve içe aktaran Aggregate’in bildirdiği hiçbir şey bir modülün içine ulaşmaz.

Release her anahtarda Aggregate’in üzerinde yer alır. Release bir bileşen için bir anahtar ayarladığında — sınırında ya da bileşenin kendi girdisinde — Release’in değeri uygulanır; hiçbirini ayarlamadığında Aggregate’inki uygulanır. İki taraf anahtar anahtar katmanlanır; bu nedenle yalnızca aggrega.ai/namespace ayarlayan bir Release, Aggregate’in bildirdiği bir aggrega.ai/image-registry değerini geçerli bırakır.

Release’teki açık bir null yalnızca Release’in kendi değerini geri çeker. aggrega.ai/namespace: null yazan bir bileşen girdisi, Release sınırının ona vereceği ad alanını kaldırır ve bileşen bu durumda kendi Aggregate’inin bildirdiği değeri alır — Aggregate de bir değer bildirmiyorsa hiçbir değer almaz. Bir Release, Aggregate’in bildirdiği bir değeri kaldıramaz; yalnızca onun üzerine kendi değerini ayarlayabilir.

# Aggregate
spec:
subsystems:
billing:
annotations:
aggrega.ai/namespace: billing # api and worker render into billing
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0
annotations:
aggrega.ai/namespace: billing-batch # worker renders into billing-batch
# Release
spec:
boundaries:
production:
components:
api:
annotations:
aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing
worker: {}

aggrega.ai/chart-name bu erimin dışındaki tek anahtardır: birkaç bileşenden derlenen bir şemsiye chart’ı adlandırır; bu nedenle hiçbir zaman bir bileşenin ek açıklamalarından değil, o chart’a katkıda bulunan Release sınırlarından okunur.

Bir Recipe ya da FeatureRecipe şablonu ek açıklama kovalarını adlarıyla okur — .context.annotations.aggregate, .context.annotations.release ve .context.annotations.catalog her biri o tarafın yazdığını tutar — bu nedenle bir yerleşim anahtarını tek bir kovadan okuyan şablon yalnızca o tarafın değerini görür.

Taraf ve sütun ayrımı

Aggregate-as-Authoring-Surface değişmezi, Aggregate tarafı ek açıklamaları values sütunuyla sınırlar. Bir Manifest ek açıklama bağlaması, yönlendirme yollarını ya maps.infra (Release tarafı yönlendirme) ya da maps.values (Aggregate tarafı yönlendirme) altında bildirir; bağlaması yalnızca maps.infra yolları bildiren Aggregate tarafı bir ek açıklama, derlemeyi ek açıklama anahtarını, yönlendirilen sütunu ve yazım tarafını adlandıran açık bir tanılamayla durdurur. Simetrik kural Release tarafı için geçerlidir: Release tarafı ek açıklamalar yalnızca maps.infra üzerinden yönlendirilebilir; yalnızca values içeren bir bağlamaya karşı Release tarafı bir ek açıklama, paralel hatayı tetikler. Her tanılama, ek açıklama değerinin yazıldığı belgenin alanı altında kaydedilir — Aggregate’ten [DEVELOPER_ERROR], Release’ten [OPS_ERROR] — böylece başlık, açılacak yüzeyi adlandırır.

Her iki sütunda yol bildiren bağlamalar, her geçişte tarafla uyumlu alt kümeyi yönlendirir: Aggregate tarafı bir ek açıklama yalnızca values sütunu yollarını, Release tarafı bir ek açıklama ise yalnızca infra sütunu yollarını tetikler. Taraflar arası birleştirme — Aggregate’ten values, Release’ten infra — her (Component, Feature) çifti için her iki sütunu da doldurulmuş ve her yaprağa hangi tarafın katkıda bulunduğunu yaprak başına köken bilgisiyle kaydeden tek bir Feature eklemesi üretir.

Yazım örneği — alt sistem ek açıklaması values’a yönlendirilir

# Manifest binding
spec:
mappings:
features:
type:
core/db-pool: db-pool-helm:1.0.0
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- pool # routes to values.pool
# Aggregate
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool"
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0

Ek açıklama genişletmesinden sonra hem api hem de worker, values.pool alanı "shared-pool" olan sentetik bir feature.myco/db-pool Feature eklemesi taşır. Derleme grafiği (aggrega validate --release <release> --ir-graph) her yaprağı origin: annotation, side: aggregate ve annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool ile kaydeder.

Yapılandırılmış ek açıklama değerleri

Yapılandırılabilir birden çok alanı olan bir Feature, bunların birkaçı için aynı anda değer taşıyan tek bir ek açıklama anahtarını akla getirir. Yapılandırılmış ek açıklama biçimi, tek bir anahtarın tek bir bildirimde birden çok bağlama yoluna yönlendirilmesini sağlar:

# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)
boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100

Manifest bağlaması, dört alt anahtarın tümünün yönlendirmesini sütunlara göre gruplanmış maps: listelerinde bildirir:

# Manifest
spec:
mappings:
features:
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- db_name
- read_replicas
infra:
- pool_size
- max_connections

Ek açıklama değerinin biçimi üç biçimden biridir:

  • Skaler dize — tek bir değer. Bağlama toplamda tam olarak bir yol bildirmelidir; skaler değer o yola yönlendirilir.
  • Yapılandırılmış nesne — alt anahtardan alt değere bir eşlem. Her alt anahtarın yolu, bağlamanın maps.infra veya maps.values listesinde yer almalıdır; alt değer, bildirilen sütundaki adı verilen Feature şema alanına yönlendirilir.
  • Açık YAML null — bu basamaklama kapsamı için devralınan bağlamadan bütünüyle çıkar.

Yapılandırılmış bir değerdeki her alt anahtar, bağlamanın maps listesine karşı bağımsız olarak çözümlenir. Hem maps.infra hem de maps.values içinde bulunmayan bir alt anahtar, sorunlu alt anahtarı ve bildirilen yolları adlandıran açık bir hatayla derlemeyi durdurur.

Yapılandırılmış değerler için basamaklı birleştirme

Yapılandırılmış ek açıklamalar, alt anahtar başına derin birleştirmeyle basamaklanır. Bir alt basamaklama kapsamının ek açıklaması, üst kapsamın ek açıklamasıyla alt anahtar başına birleşir; daha yakın düzey, alt anahtar ayrıntı düzeyinde üst düzeyi geçersiz kılar:

subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "data-default"
read_replicas: 3
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-override" # overrides parent at this subkey only
# read_replicas not listed → inherits 3 from parent
analytics:
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out: removes inherited subkey
# db_name not listed → inherits "data-default" from parent

Basamaklamadan sonraki geçerli ek açıklamalar:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas bu kapsamda devre dışı bırakıldı

Değeri skaler olan (yapılandırılmış bir üst düzeye karşı) bir alt basamaklama düzeyi, birleştirmek yerine bütünüyle değiştirir. Basamaklama düzeyleri arasındaki biçim uyuşmazlıkları daha yakın düzeydeki değer lehine çözümlenir; derleyici biçim uyuşmazlığında uyarı vermez.

Tüm değer için null ile alt anahtar başına null

Basamaklama, farklı ayrıntı düzeylerinde iki devre dışı bırakma mekanizması taşır:

# Whole-value null — opts out wholesale at this scope
components:
api:
annotations:
feature.myco/db-pool: null

Ek açıklama bağlamasının tamamı bu bileşende bastırılır; bu kapsamda bu ek açıklama anahtarından hiçbir sentetik Feature eki sentezlenmez. Kardeş bileşenler devraldıkları bağlamayı korur.

# Per-subkey null — opts out just one subkey
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-db"
read_replicas: null

Ek açıklama bu kapsamda katkı sağlamaya devam eder, ancak read_replicas alt anahtarı bastırılır. Diğer alt anahtarlar (bu kapsamda bildirilen veya üst basamaklama düzeylerinden devralınan) geçerliliğini korur.

Yazım rehberi: bir kapsamda ek açıklamaya dayalı bir Feature ekini devre dışı bırakmak için tüm değer için null kullanın. Bir ek açıklamanın katkısının büyük bölümünü korumak, ancak bir veya daha fazla belirli alanı bastırmak istediğinizde alt anahtar başına null kullanın.

Alt anahtar başına taraf-sütun ayrımı

Aggregate-as-Authoring-Surface değişmezi, bir ek açıklama değeri yapılandırılmış olduğunda alt anahtar başına uygulanır. Her alt anahtarın sütunu (bağlamanın maps bildirimine göre) yazım tarafıyla uyumlu olmalıdır:

  • Aggregate tarafındaki ek açıklama yalnızca maps.values’a yönlenen alt anahtarlar taşıyabilir.
  • Release tarafındaki ek açıklama yalnızca maps.infra’ya yönlenen alt anahtarlar taşıyabilir.

Uyumsuz bir sütuna yönlenen bir alt anahtar, ilgili alt anahtarı ve sütunu belirten açık bir hatayla derlemeyi durdurur. Hata zinciri, durmadan önce ek açıklama başına tüm uyumsuz alt anahtarları toplar; böylece operatörler düzelt-yeniden derle döngüsüne girmek yerine her derleme döngüsünde tüm sorunları görür.

Alt anahtar başına tür doğrulaması

Her alt anahtarın çalışma zamanı değeri, yönlendirilen sütunda hedef Feature’ın spec.schema içinde bildirilen türe karşı doğrulanır. Desteklenen bildirilmiş türler string, integer, number, boolean, object, array, null’dır. YAML türü şemanın bildirilen türüyle eşleşmeyen bir alt değer, alt anahtarı, gerçek türü ve bildirilen türü adlandıran açık bir hatayla derlemeyi durdurur.

Tür eşleştirmesi katıdır — tür zorlaması yapılmaz. Tamsayı türündeki bir şema alanına karşı "20" dizesi derlemeyi durdurur; yazarlar türleri Feature şemasında doğru bildirir ya da dize olarak aktarılan skaler ek açıklamalar kullanır.

Katı doğrulama için yazım kaldıracı. Feature’ın spec.schema alanında bildirilmiş bir type bulunmayan özellikler, iç içe eşlemler dahil her çalışma zamanı değer biçimini kabul eder. Şema bir kısıt bildirmediğinde derleme kendisi bir kısıt uydurmaz. Alt anahtar başına katı tür doğrulaması isteyen yazarlar, spec.schema içindeki her özellikte type bildirir. Aşağı akıştaki FeatureRecipe işleme katmanı, ek açıklama katkısı hangi biçimi taşırsa onu işler.

Taraflar arası birleştirme

Hem Aggregate tarafındaki bir ek açıklama (values alt anahtarları) hem de Release tarafındaki bir ek açıklama (infra alt anahtarları) aynı Component üzerindeki aynı Feature ekini hedeflediğinde, derleme katkıları her iki sütunu da doldurulmuş tek bir Feature ekinde birleştirir. Yaprak başına köken bilgisi her alt anahtarın kaynağını kaydeder — sentezlenen ek, Aggregate yazım konumuna atfedilen values.db_name’i ve Release yazım konumuna atfedilen infra.pool_size’ı taşır.

Taraflar arası birleştirme deseni, geliştirici niyeti ve operatör boyutlandırması alanlarını bir arada içeren Features için standart yazım biçimidir: Aggregate bilişsel seçimleri (hangi veritabanı, uygulama düzeyinde kaç replika) bildirir; Release fiziksel boyutlandırmayı (havuzun ne kadar büyük olduğu, altyapı düzeyinde kaç bağlantı) bildirir. Tek bir Manifest bağlaması, tek bir maps bildirimleri kümesiyle bunları birbirine bağlar.