Etiketler ve ek açıklamalar
Aggrega varlıkları yapısal olarak benzer iki meta veri mekanizması taşır — metadata.labels ve metadata.annotations — ve bunlara ek olarak sınır boyunca basamaklanan ve feature eklemeye ait yüzeylere dağılmış, ek açıklama taşıyan alanlar bulunur. Altı ayrı yüzey ek açıklama/etiket içeriği tanımlar veya taşır; her birinin basamaklanma kuralları, tüketicileri ve önek uzlaşımları farklıdır. Bu sayfa bu yüzeyleri tek bir yerde belgeler, çalışma zamanı şablon bağlamının sunduğu üç anlamsal kovayı tanımlar, yazarların izlemesi gereken önek disiplinini adlandırır ve beş Feature ekleme yüzeyini, daha geniş etiketler/ek açıklamalar sözcük dağarcığıyla birlikte görülebilmeleri için yan yana belgeler.
Açıklama ve etiket taşıyan altı yüzey
Yazarlar etiketler ve açıklamalarla altı ayrı yüzeyde karşılaşır. Her birinin kapsamı, basamaklanma kuralı ve tüketicisi farklıdır.
| # | Yüzey | Kapsam | Basamaklanma kuralı | Birincil tüketici |
|---|---|---|---|---|
| 1 | Katalog varlığının metadata.labels alanı | Varlık başına kimlik (Component, Feature, Aggregate) | Örneklere basamaklanmaz; katalog varlığının kendisinde taşınır | Components ve Features için aggrega search -l; bir Aggregate’in etiketleri belgesinde taşınır ve bunları okuyan bir komut yoktur |
| 2 | Component metadata.labels (içsel) | Component örneği başına özellikler (component.aggrega.ai/type vb.) | label-transform değişikliklerinden sonra IR’de düğüm başına .context.labels alanına basamaklanır | Seçici eşleştirme (sentezlenen JSON Schema’da x-aggrega-selector: olarak taşınan usesSchema selector: bildirimleri), Recipe şablon mantığı |
| 3 | Component metadata.annotations | Mimar tarafından yazılan, Component örneği başına nitelikler | IR’de düğüm başına .context.annotations.catalog kovasına basamaklanır | yönetişim karar rolleri (içsel nitelik politikaları), Recipe şablon mantığı |
| 4 | Aggregate / Subsystem annotations: | Aggregate tarafındaki bilişsel meta veriler | IR’de düğüm başına .context.annotations.aggregate kovasına basamaklanır | Bilişsel yönlendirme için Recipe valuesMapping: |
| 5 | Release sınırı annotations: | aggrega.ai/* iyi bilinen açıklamaları dahil, Ops tarafındaki fiziksel meta veriler | IR’de düğüm başına .context.annotations.release kovasına basamaklanır | Providers (helm aggrega.ai/namespace anahtarını okur; compose ağ adını aynı anahtardan türetir); sınırlar arası yönlendirme için FeatureRecipe injectMapping: |
| 6 | Manifest features.annotations bağlamaları | Açıklama güdümlü Feature eklemesi için, sütunlara göre gruplanmış alt anahtar yönlendirmesiyle (maps.infra / maps.values) açıklama anahtarı → Feature türü bağlaması | Çözümlemenin açıklama genişletme alt aşaması Release sınırlarını (dıştan içe) ve Aggregate alt sistemlerini (dıştan içe) dolaşır; bileşen başına geçersiz kılma ve tüm değer / alt anahtar başına null ile devre dışı bırakma uygulanır; taraf-sütun denetimi, her yazım tarafı için hangi sütunun tetikleneceğini belirler | Açıklama güdümlü Feature genişletmesi (sentetik Feature eklemeleri, IR grafiğinde origin: annotation ile kaydedilir) |
- ve 5. yüzeyler aynı YAML biçimini paylaşır (basamaklanan sınırda bir
annotations:eşlemi), ancak farklı IR kovalarına basamaklanır; kova ayrımı, çalışma zamanının sunduğu taşıyıcı kuraldır. 6. yüzey yapısal olarak ayrıdır: Aggregate / Release içeriğinde değil Manifest varlığında bulunur ve tüketimi açıklama güdümlü genişletme geçişine bağlıdır.
Üç kovalı .context.annotations.* anlamı
Oluşturucu bir Recipe şablonunu değerlendirdiğinde, düğüm başına .context.annotations alanı adlandırılmış üç kova taşır. Her kova, ek açıklama adına göre anahtarlanmış düz bir string → string eşlemesidir; kova, ek açıklamayı kimin yazdığını ve amacının ne olduğunu belirler.
.context.annotations.release— Release sınırı ek açıklamaları (Yüzey 5). Fiziksel gerçeklikleri yönetmek için kullanılır; oluşturucular bunları uygun yerlerdeinfra:alanlarına yönlendirir.aggrega.ai/*iyi bilinen ek açıklamaları bu kovada bulunur..context.annotations.catalog— Component meta veri ek açıklamaları (Yüzey 3). Mimar tarafından yazılan değişmez içsel özelliklerdir; öncelikle Wasm politika eklentileri tarafından tüketilir..context.annotations.aggregate— Aggregate alt sistem ek açıklamaları (Yüzey 4). Bilişsel meta verilerdir; oluşturucular bunları uygun yerlerdevalues:yüklerine yönlendirir.
Üç kovalı ayrım bir toplumsal sözleşmedir
Derleyici kova sınırlarını zorunlu kılmaz. Üç kova da düz bir string → string biçimini paylaşır; bir Recipe’nin şablonu üçünü de okuyabilir ve hiçbir şey bir Release sınırı ek açıklamasının bilişsel bir meta veri alanı olarak yorumlanmasını ya da bir katalog ek açıklamasının infra: içine yönlendirilmesini engellemez. Ayrım bir derleyici güvencesi değil, yazım disiplinidir.
Disiplinin hedefi — kovaların ifade etmesi amaçlanan şey:
- release = “bu bileşenin nerede çalıştığı, Ops tarafından yönetilir”
- catalog = “bu bileşenin ne olduğu, Mimar tarafından yazılır”
- aggregate = “bu bileşenin ne yaptığı, Geliştirici tarafından yazılır”
Yazarlar ayrıma uyduğunda, sonraki araçlar doğru konu için doğru kovayı okuyabilir. Yazarlar ayrımı ihlal ettiğinde (örneğin Release dosyası elverişli olduğu için bilişsel meta verileri release ek açıklamalarına koyduklarında), çalışma zamanı yine çalışır ancak kovanın amacı bulanıklaşır.
Linter soketi — kovalar arası okumaları işaretleme
Bir linter eklentisi (bant dışı, tavsiye niteliğinde; yerleştirme ölçütü için plugins/plugin-contract.md sayfasına bakın), bir Recipe’nin şablonunun amacı yönlendirilen alanla eşleşmeyen bir kovadan veri çektiği kovalar arası okumaları işaretleyebilir. Ölçüt:
- Bir
values:alanını doldurmak için.context.annotations.releaseokumak — işaretlenir (bilişsel meta verileraggregatekovasından gelmelidir). - Bir
infra:alanını doldurmak için.context.annotations.aggregateokumak — işaretlenir (fiziksel meta verilerreleasekovasından gelmelidir). values:ya dainfra:alanını doldurmak için.context.annotations.catalogokumak — genellikle yalnızca tavsiye niteliğindedir (katalog ek açıklamaları içsel özelliklerdir; bunları sütunlara yönlendirmek olağan dışıdır ancak her zaman yanlış değildir).
Yayımlama linter’ı bu ölçüt için bir kural taşımaz ve derleme bunu denetlemez; kendi linter eklentiniz bunu, aggrega lint komutunun çalıştırdığı linter soketi aracılığıyla yapabilir. Bu disiplin, kova amacı uzlaşımını izleyen gözden geçirenler ve yazarlar tarafından korunur.
Önek disiplini
Annotation ve etiket anahtarları tek tip bir <namespace>/<name> biçimini izler. Aşağıdaki önek aileleri, her birinin altındaki anahtarları kimin yazdığını ve her birinin nasıl korunduğunu belirtir — bir önek ayrılmıştır ve bir Manifest bağlaması ya da bir Recipe çıktı etiketi onun içinde yeni bir anahtar talep ettiğinde derleme durur; geri kalanlar katalog uzlaşımıdır ve hiçbir anahtarı reddeden bir şey yoktur. İkisi arasındaki fark derlemenin durup durmadığıdır; bu nedenle diğerlerinden önce ortadaki sütunu okuyun.
| Önek | Buradaki anahtarları kim yazar | Nasıl korunur | Amaç | Örnekler |
|---|---|---|---|---|
aggrega.ai/ | Yalnızca Aggrega platformu | Ayrılmış ve zorunlu kılınmış. Buradaki anahtarları platform tanımlar ve siz platformun tanımladıklarını yazarsınız — örneğin bir Release sınırında aggrega.ai/namespace. Önekin içinde yeni bir anahtar talep etmek derlemeyi durdurur: yalın önek altındaki bir Manifest features.annotations bağlaması da, outputLabels: ya da outputComponentLabels: içinde bu önek altındaki bir Recipe çıktı etiketi anahtarı da. Bu önek altına yazılan ve platformun tanımlamadığı bir annotation reddedilmez: derleme onu taşır ve bir Release üzerinde bulunduğunda, onunla ilgili işlem yapmayan bir hedef bunu bir uyarıyla bildirir. Bkz. errors/fatal-halts.md “A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Bir Manifest annotation bağlaması ayrılmış öneki talep ediyor)” ve “An output-label key uses a reserved namespace (Bir çıktı etiketi anahtarı ayrılmış bir ad alanı kullanıyor)”. | Sağlayıcı tarafından doğrudan tüketilen platforma özgü annotation’lar | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | Resmî standart kitaplık | Uzlaşım. Burada hiçbir şey bir anahtarı reddetmez; söz dağarcığı bir denetimle değil, mutabakatla standart kitaplığa aittir. | Manifest features.annotations içinde bağlanan Feature annotation kısayolları | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | Resmî standart kitaplık | Uzlaşım. Burada hiçbir şey bir anahtarı reddetmez. | Component’e içkin özellik etiketleri (component.aggrega.ai/type seçici anahtarı burada bulunur) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | Resmî standart kitaplık | Uzlaşım. Burada hiçbir şey bir anahtarı reddetmez. | Aggregate modül düzeyi kimlik etiketleri | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | Resmî standart kitaplık ve kendi kataloglarındaki kurumlar | Uzlaşım. Burada hiçbir şey bir anahtarı reddetmez. | Yetenek etiketleri — bir usesSchema seçicisinin ya da bir Feature’ın appliesTo alanının ayrım yaptığı davranışsal boyutlar. <role>, boyutun ait olduğu ilgi alanını adlandırır: ya bir bileşen rolü ya da birden çok rolün paylaştığı kesişen bir ilgi alanı. | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | Kurum / topluluk | Açık. Denetiminizdeki bir alan adı altında yazın. | Özel annotation’lar ve etiketler | acme.com/billing-tier, corp/cost-center |
Özel annotation yazan yazarlar denetimlerindeki bir alan adını kullanır (genellikle ters DNS biçiminde). Doğrudan aggrega.ai/ altında (alt önek olmadan) yazmak platforma ayrılmıştır; Manifest’in features.annotations bağlamaları da anahtarları doğrudan aggrega.ai/ altına bağlayamaz — bkz. entities/manifest.md “aggrega.ai/ önek ayırması”.
Bir yetenek önekini adlandırma
Bir yetenek anahtarı <role>.aggrega.ai/<dimension> biçimindedir ve <role> muhakeme gerektiren kısımdır.
Onu üç kural yönetir ve birincisi en sık ters
anlaşılanıdır.
- Onu ilk taşıyan bileşen türünü değil, ilgi alanını adlandırın.
Bir boyut birden çok bileşen türünün paylaştığı bir şeyi tanımladığında, önek
paylaşılan ilgi alanını adlandırır; böylece onu edinen bir sonraki tür paralel bir söz dağarcığı
icat etmek yerine mevcut olanı yeniden kullanır.
component.aggrega.ai/hostingbir ilgi alanıdır — alttaki kaynağı kimin işlettiği — ve bir veritabanını ve bir model API’sini aynı sözcüklerle tanımlar;dataplane.aggrega.ai/*trafik yolundaki bir konumu adlandırır, böylece bir proxy, bir ingress ağ geçidi ve bir service mesh kendilerini aynı biçimde tanımlar. Gerçekten tek bir role özgü bir boyut,model.aggrega.ai/capabilityörneğinde olduğu gibi o rolün adını alır. - Önekte tek bir küçük harfli sözcük, kısa çizgi yok. Kısa çizgi,
bileşik bir sözcüğün doğal okunduğu
<dimension>yarısına aittir (request-mirroring,data-class,upstream-licensing). - Bir boyut, bir seçici ona ihtiyaç duyduğunda eklenir ve bildirdiği her değeri taşıyan bir bileşen vardır. Buradaki her sözcük bir katalog yazarının öğrenmesi ve bir Feature yazarının karşılaşabileceği bir sözcüktür; bu nedenle bir boyut, bir
usesSchemaya da birappliesToalanının gerçekten sorduğu bir şeyi ayırt ederek yerini hak eder. Hiçbir bileşenin taşımadığı bir değer, hiç olmayan bir değerden daha kötüdür: onu adlandıran bir seçici ayrıştırılır, hiçbir şeyle eşleşmez ve hiçbir şey bildirmez — bu yüzden katalogun gösteremediği bir değer, bir bileşen onu taşıyana kadar söz dağarcığının dışında bırakılır. Değeri, ürünün bir özelliği değil de bir ortamın kendi bileşenlerini nasıl kullandığına ilişkin beyanı olan bir anahtar istisnadır vecompliance.aggrega.ai/data-classbu durumdur: bir bileşenin verisinin hangi sınıfta olduğu, ortamın bileşeni nasıl kullandığına bağlıdır; bu yüzden hiçbir standart kitaplık Component’i onun değerlerinden hiçbirini taşımaz ve hiçbir standart kitaplık soketi ya da Feature’ı bunlar üzerinden seçim yapmaz. Anahtar ve değerleri, bir ortamın kendi Components’ı ile bağladığı politikalar tek bir yazımı paylaşsın diye bildirilir; bir değeri adlandıran bir seçici ya da politika yalnızca Components’ı onu taşıyan bir katalogda eşleşir. policy-data-class-route böyle bir Component’i ve onu okuyan politikayı gösterir.
Bir ayırma ile platform tanımlı bir anahtar aynı şey değildir
Ayırma yalın aggrega.ai/ kökü üzerindedir. Altındaki her <scope>.aggrega.ai/ ad alanı, platformun sahip olmadığı kendi başına bir anahtar alanıdır ve katalogun söz dağarcığını genişletilebilir tutan da budur: bir kurum katalogu, derlemenin damgaladığı hiçbir şeyle çakışmadan acme.aggrega.ai/team yazabilir.
Bu açık ad alanlarının içindeki birkaç anahtar yine de platform tarafından tanımlanır ve derleme tarafından okunur; bu, ad alanlarını ayrılmış yapmaz:
component.aggrega.ai/typeher Component’inmetadata.labelsalanında zorunludur ve sabit bir değer kümesinden birini alır. Seçiciler onunla eşleşir; derleyici hangi değeri taşıdığına göre dallanmaz.- Bir Component’in
metadata.annotationsalanında yazılanfeatures.aggrega.ai/requiredType.<label>, adlandırılan türde bir Feature’ın bağlanması gerektiğini bildirir. Derleme, bu zorunluluğu her düğümün tamamlanmış bağlama kümesine karşı denetler ve hiçbir şey onu karşılamadığında durur — bkz.errors/fatal-halts.md“Required feature not attached (Gerekli feature bağlanmamış)”. Çoğula dikkat edin:features.aggrega.ai/kendi başına bir ad alanıdır ve yukarıdaki tablodaki, Manifest bağlama kısayollarını taşıyan tekilfeature.aggrega.ai/ad alanından farklıdır.
Farkı şöyle okuyun: ayrılmış bir önek, içinde tanımlamaya çalıştığınız bir anahtarı reddeder; platform tanımlı bir anahtar ise derlemenin bildiği, aksi hâlde serbestçe yazabileceğiniz bir ad alanında duran tek bir adlandırılmış anahtardır. component.aggrega.ai/, features.aggrega.ai/ ve diğerleri altındaki öteki her anahtar, derlemenin yorumlamadan taşıdığı meta veridir.
Bir Component’in metadata.annotations alanındaki böyle bir anahtar derleme tarafından değil, standart yayımlama linter’ı tarafından okunur: observability.aggrega.ai/metrics-credential, ürünün metriklerinin nasıl kimlik doğruladığını belirtir — none, kimlik bilgisi olmadan sunulurlar; target-key, Component’in her çağırandan istediği anahtarı alırlar; separate-token, kendilerine ait bir token alırlar. Derleme onu diğer her annotation gibi taşır. Linter onu, bir kazıma bağlantısının kimlik bilgisinin hedefin çağıran anahtarıyla karşılaştırılıp karşılaştırılmayacağına karar vermek için okur ve Component’in bildirdiği metrics_credential_required provides anahtarıyla uyumlu olmasını bekler — bkz. cli/aggrega-lint.md içindeki “Disiplin kuralları”.
İşlenmiş çıktıya yazılan köken etiketleri
Sağlayıcıların tükettiği gelen ek açıklamaların ötesinde Aggrega, helm sağlayıcısının işlediği her Kubernetes manifestine ve üretilen her compose hizmetine köken etiketleri de yazar; helm-chart sağlayıcısı da aynı kümeyi, helm sağlayıcısının yazdığı biçimde, $import: ile yüklediği her yapıta yazar. Bu etiket kümesi, aşağı akış araçlarının (maliyet panoları, gözlemlenebilirlik yığınları, GitOps denetleyicileri) çalışma zamanı kaynaklarını onları üreten katalog içeriğine geri bağlamasını sağlar. Bir helm-chart alt chart’ının kendi şablonları, yazarının yazdığı gibi kopyalanır; bu yüzden o yazarın yazdığı etiketler neyse onları taşır.
helm ve compose sağlayıcılarının ürettiği küme — helm’de, tabloda belirtildiği gibi anahtarlardan üçü etiket yerine ek açıklama olarak yazılır:
| Etiket | Kaynak | Her zaman yazılır mı? |
|---|---|---|
app.kubernetes.io/name | Component kimliği — yazdığınız ad; içe aktarılan bir Aggregate’in katkıda bulunduğu bir bileşen için, modül ayırıcısı açıkça yazılmış nitelikli adı (aşağıya bakın); ya da bir FeatureRecipe’in ürettiği bir kaynak için, o ekleme için türetilen tanımlayıcı | Kubernetes manifestlerinde evet; compose hizmetlerinde yazılmaz (standart etiket K8s’e özgüdür) |
aggrega.ai/component-id | Component kimliği — yazdığınız ad; içe aktarılan bir Aggregate’in katkıda bulunduğu bir bileşen için, modül ayırıcısı açıkça yazılmış nitelikli adı (aşağıya bakın); ya da bir FeatureRecipe’in ürettiği bir kaynak için, o ekleme için türetilen tanımlayıcı | Evet |
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 | Üreten varlıkta hem ad hem sürüm ayarlı olduğunda; helm’de bir ek açıklama |
aggrega.ai/boundary-path | Bileşenin yönlendirildiği sınır yolu | Sınır yolu boş olmadığında; helm’de bir ek açıklama |
aggrega.ai/aggregate-name | Aggregate metadata.name | Ayarlı olduğunda |
aggrega.ai/compiler-version | Derleme anında damgalanan derleyici sürümü | Ayarlı olduğunda |
aggrega.ai/provider | Kaynağı işleyen sağlayıcı (helm, helm-chart, compose) | Evet |
aggrega.ai/provider-version | O sağlayıcının sürümü | Evet |
aggrega.ai/environment | Release metadata.environment | Evet — her Release bunu bildirir |
aggrega.ai/sync-wave | Sınır başına syncWave tamsayısı; bir GitOps aracının kaynakları uyguladığı sıra | Sıfır olmadığında; helm’de argocd.argoproj.io/sync-wave yanında bir ek açıklama |
Agregat adı, ortam, derleyici sürümü ve sağlayıcının adı ile sürümü, sizin ya da derlemenin seçtiği dizelerdir ve hiçbiri yazıldığı yerde Kubernetes etiket değeri kurallarına tabi tutulmaz. helm üzerinde bu etiketlerin her biri, değer zaten geçerli bir etiket değeriyse — harfler, rakamlar, -, _ ve ., her iki uçta bir harf veya rakam, en fazla 63 karakter — değeri yazıldığı gibi taşır; aksi halde geçerli bir değere yeniden yazılmış değeri taşır ve özgün değer aynı anahtar altında bir ek açıklama olarak eklenir: 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. Zaten uyan bir değer ek açıklama eklemez. Compose özgün değeri etiket olarak taşır. Yeniden yazma kuralı providers/well-known-annotations.md “Sağlayıcıların ürettiği köken etiketleri” bölümünde belirtilmiştir.
Bir FeatureRecipe’in ürettiği kaynaklar için aggrega.ai/component-id değeri, barındıran bileşenin adından değil eklemeden oluşturulur — bir FeatureRecipe’in bu kaynakları teslim edebileceği her yol için: ister bir iş yükü sentezlesin, ister bağımsız bir yapıt kümesi üretsin, ister yazarının sağladığı bir chart’ı ya da parçayı işlesin. Böylece bir eklemenin kaynaklarını kimliğe göre seçen bir sorgu hepsini döndürür ve hiçbiri barındıran bileşenin kendi ürettiği bir kaynaktan ayırt edilemez değildir. Değerin nasıl oluşturulacağı Feature’ın nereye eklendiğine bağlıdır; her iki durumda da sonuç geçerli bir Kubernetes etiket dizesidir.
İçe aktarılan bir Aggregate’in katkıda bulunduğu bir bileşen için kimlik, o bileşenin nitelikli adıdır; modülü bileşene bağlayan ayırıcı açık yazılır — data-layer.main-db, data-layer-zdmain-db olarak damgalanır — çünkü nokta, bir kaynak adının ya da küme adresinin güvenle taşıyabileceği bir karakter değildir. Ayırıcı içermeyen, sizin yazdığınız bir ad bayt bayt aynen damgalanır.
Kimlik, bir kaynağın neye ait olduğunu söyler. Bu, bir kaynağın nasıl adlandırıldığından farklı bir sorudur ve bir teslim yolu için iki sorunun yanıtı farklıdır:
- Bir FeatureRecipe bir iş yükünü sentezlediğinde, bu kaynakları Aggrega kendisi oluşturur, dolayısıyla onları da kimliğe göre adlandırır: kimlik, etiketlerinin yanı sıra
metadata.namealanlarına, seçici etiketlerine ve üretilen dosya adlarına da ulaşır. Yalnızca bir etiket değil, küme içinde bir addır. - Bir FeatureRecipe yazarının yazdığı bir chart’ı ya da parçayı teslim ettiğinde, adlar onu yazana aittir. Bu şablonların karşısında işlendiği Helm release adı — ve bu işlemenin ürettiği dosyaların öneki — barındıran bileşenin olarak kalır. Chart’lar kaynaklarını genellikle release adına göre adlandırır; bu yüzden onu değiştirmek, chart’ın kendi bildirdiği kaynakları, zaten dağıtılmış oldukları bir kümede, chart’la hiçbir ilgisi olmayan bir nedenle yeniden adlandırırdı. Etiketler yine de eklemenin kendi kimliğini taşır ve eklemenin kaynaklarını bulunabilir tutan da budur.
- Feature bir sınıra eklendiğinde, adı yerine geçebilecek bir barındıran bileşen yoktur; bu nedenle orada oluşturulan kimlik, etiketin yanı sıra adlandırmanın da temelidir.
Her iki durumda da değer, yazdığınız parçalardan -- ile birleştirilerek, ikisinden hangisi olduğunu belirten sabit bir başlangıcın ardına oluşturulur. Kullanımda iki başlangıç vardır ve yazdığınız bir bileşen kimliği bunların hiçbiriyle başlayamaz — yazdığınız bir adın ve Aggrega’nın oluşturduğu bir adın birbirine asla karıştırılmamasını sağlayan da budur.
Feature bir bileşene eklendiğinde parçalar şunlardır: sabit bir cfr başlangıcı, Feature’ın eklendiği bileşenin kimliği ve eklendiği anahtar. api bileşenine mon altında eklenen bir Feature cfr--api--mon değerine ulaşır. Barındıran bileşen değerin bir parçasıdır, çünkü birkaç bileşene eklenen tek bir Feature adı her birinde ayrı bir kaynak kümesi üretir ve her kümenin kendine ait bir kimliğe ihtiyacı vardır: mon hem api hem worker bileşenine eklendiğinde, ikisi için tek bir değer yerine cfr--api--mon ve cfr--worker--mon değerlerine ulaşır. Aynı nedenle, tam olarak kendisini barındıran bileşenin adını taşıyan bir ekleme, o bileşenin kendi değerinden farklı bir değere ulaşır — mon bileşenine eklenen mon, cfr--mon--mon değerine ulaşır.
Feature bir sınıra eklendiğinde — compose-bridge ağ geçidi hizmeti tipik örnektir — parçalar sabit bir bfr başlangıcı, ardından en dıştakinden başlayarak sınır yolunun her bir kesimi, ardından Feature’ın eklendiği addır. bridge konumundaki bir sınırda gateway adlı bir Feature bfr--bridge--gateway değerine ulaşır; aynı Feature prod/eu konumundaki bir sınırda bfr--prod--eu--gateway değerine ulaşır.
Değerin taşıyamadığı bir karakter değiştirilmez, açık yazılır; değer hem bir etiket hem de küme içinde bir ad olduğundan, her tür Kubernetes kaynak adının kabul ettiği karakterlerle sınırlanır: küçük harfler, rakamlar ve kısa çizgi. Böylece yazdığınız bir kısa çizgi kısa çizgi olarak kalır, küçük bir harf ya da rakam olduğu gibi kalır ve geri kalan her şey — bir etiket değerinin kabul edip bir kaynak adının reddettiği büyük harf de dahil — kısa bir kaçış dizisine dönüşür: my_zone adlı bir ek my-zuzone katkısında bulunur ve worker ekine sahip myApi bileşeni cfr--my-zx000041pi--worker değerine ulaşır. Bu kaçışlı değer, ekin kaynaklarının her hedefte etiketlendiği ve seçildiği değer, ekin sentezlediği bir iş yükünün adlandırıldığı ve dosyalandığı değer ve bir sınır ekinin sürüm adının türetildiği değerdir. Büyük harf, kaynak adı kuralının tek başına bir etiketin açık yazacağı karakterlere eklediği tek karakterdir; bu yüzden parçaları büyük harf içermeyen birleşik bir değer — cfr--api--mon, bfr--prod--eu--gateway — tek başına bir etiketin taşıyacağı değerin aynısıdır. Bu nedenle ayırt edebildiğiniz iki ek — onları nasıl adlandırmış olursanız olun ve sınır ne kadar derinde olursa olsun — iki ayrı değere ulaşır; çünkü -- hiçbir yazılı parçanın içeremeyeceği bir dizidir, dolayısıyla parçalar arasındaki bölmeyi kaydırmak değerle çakışmak yerine değeri değiştirir.
Oluşturulan bir değerin ne kadar uzun olabileceği, Aggrega’nın tuttuğu bir sayı değil, hedefin yanıtıdır: kaynakların işlendiği hedefe sorulur ve değer, o hedef kabul edene kadar kısaltılır. Bir Kubernetes etiket değeri en fazla 63 karakter taşır ve aynı kimlikten türetilen bir Helm release adı daha da sıkı sınırlanır; bu yüzden aynı ekleme bir hedefte diğerinden daha kısa bir değere oturabilir. Sığan bir değer tam olarak oluşturulduğu gibi yazılır; olağan durum ve standart kitaplık kataloğundaki her ekleme için geçerli olan durum budur. Sığmayan bir değer kısaltılır: her parça başlangıcını korur ve tüm kimliğin on karakterlik bir özeti, yazabileceğiniz hiçbir adın üretmediği bir işaretin ardına eklenir — böylece kısaltılmış bir değer kısaltılmış olarak tanınabilir ve asla sığmış bir değer olarak okunamaz. Bu nedenle derin iç içe geçmiş bir gateway eklemesi bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e olarak işlenebilir. Kısaltılmış iki değerin çakışması çok düşük bir olasılıktır ve çakışırlarsa derleme, ikisinin bir adı paylaşmasına izin vermek yerine durur.
Hangi çiftlerin durdurduğu ve bunların nasıl ayrılacağı için errors/fatal-halts.md “The same name is derived more than once inside the output (Aynı ad çıktı içinde birden fazla kez türetiliyor)” bölümüne bakın.
FR tarafından üretilen bir kaynak için aggrega.ai/recipe-uri, tüketen Recipe’in kimliğine değil FeatureRecipe’in kendi name:version değerine çözümlenir — böylece üreten varlığı belirlemek için recipe-uri okuyan aşağı akış araçları, hem bileşen tarafından hem FR tarafından üretilen çıktı için doğru kökeni alır.
Sağlayıcıya özgü yazma ayrıntıları için (etiketlerin işlenen çıktıda nereye yerleştiği ve her sağlayıcının onları nasıl serileştirdiği), providers/well-known-annotations.md “Provenance labels emitted by providers” (Sağlayıcıların yazdığı köken etiketleri) bölümüne bakın.
Recipe tarafından bildirilen çıktı etiketleri
Derleyiciye ait köken kümesinin yanı sıra bir Recipe yazarı, Recipe.spec.outputLabels: aracılığıyla Recipe’in işlenmiş çıktısına damgalanacak kendi etiketlerini bildirebilir. Bunlar köken etiketleriyle aynı yayım hattını izler (aynı etiket kümesine birleştirilir ve kökenin düştüğü her yere düşerler), ancak derleyiciye değil yazara aittir. Amaçlanan kullanım bir gerçekleştirme özelliğidir: belirli bir Recipe’in bir bileşeni nasıl gerçekleştirdiğine ilişkin bir özellik (örneğin aynı bileşen türünün yönetilen hizmet Recipe’ine karşı kendi barındırılan chart Recipe’i için hosting: managed ile hosting: self-hosted); bu özellik, maliyet, politika ve envanter araçlarının sorgulayabilmesi için çıktıda yüzeye çıkarılır.
aggrega.ai/ ve app.kubernetes.io/ ad alanları köken kümesine ayrılmıştır; bu öneklerden herhangi birinin altındaki bir anahtar yükleme sırasında reddedilir: outputLabels: içinde ve bir bileşen etiket anahtarını adlandırıp bileşenin kendisinin bildirdiği değeri damgalayan eşlikçi blok olan outputComponentLabels: içinde. Bu nedenle doğrulanmış bir çıktı etiketi kümesi köken anahtarlarıyla her zaman ayrıktır ve ikisi birleştirilmiş çıktıda asla çakışmaz. Ölçüt yalın köktür: component.aggrega.ai/hosting gibi kapsamlı bir anahtar kendine ait bir ad alanındadır ve doğrudan yazılabilir ya da yükseltilebilir. Sağlayıcı başına yüzeye çıkarma (sentezde helm nesnesi ve pod şablonu; kaynak işleme ve yapıtlarda nesne; compose hizmet etiketleri; .tf.json yapıt gövdelerinde terraform kaynak başına etiketleri) köken yerleşimiyle eşleşir ve tümüyle Recipe varlık sayfasında “outputLabels: alanı” ve “outputComponentLabels: alanı” başlıkları altında belgelenmiştir.
Feature ekleme — beş yüzey
Features, Components’e beş ayrı yazım yüzeyi üzerinden eklenir; her birinin kapsamı, hedef kullanıcısı ve 5 Katmanlı Soğan Modeli içindeki sıralama önceliği farklıdır. Eklemenin tam sıralaması ve Soğan Modeli’nin kendisi architecture/10-compilation-pipeline.md sayfasında belgelenmiştir; aşağıdaki tablo beş yüzeyi yan yana listeler.
| Katman | Yüzey | Yazan | Kapsam | Basamaklanma kuralı |
|---|---|---|---|---|
| 1 | Aggregate bileşeni features: bloğu | Geliştirici | Bileşen örneği başına (ayrıntılı) | Yok — doğrudan yazar |
| 2 | Aggregate alt sistemi features: bloğu | Geliştirici | Alt sistem kapsamı (Aggregate içinde kesişen) | Alt sistemdeki her bileşene aktarılır |
| 3 | Release sınırı components.<id>.features | Operasyon | Bileşen örneği başına (ayrıntılı, operasyon tarafı) | Yok — doğrudan yazar |
| 4 | Release sınırı features: bloğu | Operasyon | Sınır kapsamı (sınır içinde kesişen) | Sınırdaki her bileşene aktarılır |
| 5 | Manifest features.annotations genişletmesi | Platform Operatörü | Ek açıklama güdümlü (sentetik ekleme) | Sınır ağacı (Release tarafı) veya alt sistem ağacı (Aggregate tarafı) boyunca aktarılır; bileşen başına geçersiz kılma ve alt anahtar başına null ile devre dışı bırakma uygulanır |
Beş yüzey birikimlidir; herhangi bir yüzeyde bulunan bir ekleme, Component’in çözümlenmiş özellik kümesine katkıda bulunur. Aynı Feature örnek adı birden fazla yüzeyde göründüğünde katkılar birbirinin yerini almak yerine tek bir eklemede birleşir ve aralarındaki bir tür uyuşmazlığı derlemeyi bir feature-merge-conflict hatasıyla durdurur.
Beş yüzey gereksiz değildir; mimarinin sorumluluk ayrımı gereği bilinçli olarak vardır — Geliştirici (katman 1-2), Operasyon (katman 3-4), Platform Operatörü (katman 5). Yazarlar, eklemenin sahibine ve kapsamına uyan yüzeyi seçer.
Bir Feature’ın uygulanıp uygulanmayacağına hangi etiketler karar verir
Bir Feature, nereye eklenebileceğini spec.appliesTo ve spec.appliesToAnyOf ile bildirir ve derleme bu bildirimi eklemenin düştüğü düğümün kesinleşmiş etiketlerine göre değerlendirir. Bir Feature’ı bu etiketlerin karşılamadığı bir düğüme eklemek derlemeyi durdurur; iki yüzeyden hiçbirini bildirmeyen bir Feature hiçbir gereksinim belirtmez ve her yerde uygulanır.
Kesinleşmiş etiket kümesi iki adımda oluşturulur ve bunların hiçbiri yazarların en sık varsaydığı adım değildir.
- Bir düğüm etiketlerini
type:alanının adlandırdığı Component katalog varlığından alır. Etiketler örneğin değil, bileşen türünün bir özelliğidir: Aggregate bir bileşen örneğini etiketleyemez, Release de etiketleyemez. Bir Aggregate’in kendimetadata.labelsalanı Aggregate’i yeniden kullanılabilir bir modül olarak tanımlar ve içindeki bileşenlere aktarılmaz. Dolayısıyla tek bir türün iki örneği aynı etiketleri taşır ve bir düğümün etiketlerini değiştirmek, işaret ettiği türü — ya da o türün varlığını — değiştirmek anlamına gelir. - Ardından bir
label-transformeklemesi bunları yeniden yazabilir. Çalışma alanı yapılandırmasılabel-transformrolünde bir yönetişim plugin’i eklediğinde, bu plugin topoloji oluşturma sırasında çalışır ve etiketlere göre herhangi bir değerlendirme yapılmadan önce düğüm etiketlerini ekleyebilir, değiştirebilir veya kaldırabilir. Başka hiçbir şeye dokunamaz; yani etiketler, bir düğümün değiştirebildiği tek parçasıdır — ve uygulanabilirliğin dayandığı parça tam olarak budur.
Bu nedenle tek bir belgenin bildirdiği etiketlere göre yapılan bir öneri bir tahmin değil, bir yaklaşıklıktır. Bir Component varlığının metadata.labels alanını okumak, o türdeki bir düğümün neyle başladığını size söyler; bu, yararlı olacak kadar sık doğru yanıttır ve iki belirli şekilde yanlıştır: bir düğümle yalnızca adı ortak olan bir belge, farklı etiketlere sahip farklı bir öznedir ve bir label-transform eklemesi kümeyi herhangi bir belgenin altından kaydırabilir. Yalnızca kaynaktan ekleme önerileri sunan araçlar bu yaklaşıklıkla çalışır; derlemenin yaptığı değerlendirme kesinleşmiş küme üzerindedir.
Ek önceliği
İki katkı aynı eklemenin aynı alanını sağladığında, işlenmiş çıktının hangisini taşıyacağına dört kural karar verir. Bunlar bu sırayla uygulanır ve sonucu öngörülebilir kılan da bu sıradır:
- Köken. Açıkça yazılmış bir katkı, hangi kapsamda bildirilmiş olursa olsun, ek açıklama güdümlü bir katkıya üstün gelir. Bir alanı bir
features:bloğuna yazmak, bir yazarın bir ek açıklamanın katkısını geçersiz kılma yoludur ve bir ek açıklama elle yazılmış bir şeyi hiçbir zaman sessizce yerinden etmez. Derleyici bastırılan ek açıklamayı kazanan değerin yanında kaydeder ve bir uyarı olarak bildirir; böylece geçersiz kılma gizemli değil, görünür olur. - Sütun sahipliği. Her alan kendi sütununu doldurur: Aggregate yüzeyleri
values, Release yüzeyleriinfrakatkısında bulunur. İki taraf hiçbir zaman aynı sütuna yazmadığından, bir geliştirici katkısı ile bir operatör katkısı aynı alan için çekişemez — yanıtlanacak bir geliştiriciye karşı operatör önceliği sorusu yoktur. - Bileşim yetkisi. Dağıttığınız Aggregate’teki bir bildirim, onun bileşimine kattığı bir Aggregate içindeki bildirime, bileşime katılan Aggregate daha dar kapsamda bildirmiş olsa bile üstün gelir. Bileşim yetkili kalır: bir modül, yalnızca daha dar bir kapsam seçerek onu kullanan Aggregate’i alt edemez.
- Özgüllük. Tek bir yazım düzeyi ve tek bir sütun içinde, daha dar kapsam daha geniş olanı alan alan iyileştirir. Bileşen kapsamlı bir ekleme, aynı örnek adına sahip alt sistem genelindeki veya sınır genelindeki bir eklemeyi geçersiz kılar — ama yalnızca gerçekten andığı alanlar için. Dar kapsamın dışarıda bıraktığı alanlar geniş kapsamın değerlerini korur; böylece paylaşılan bir ekleme ortak yapılandırmayı sağlarken tek bir bileşen onun bir alanını ayarlayabilir. Aynı kapsamdaki iki katkı yazım sırasına göre çözümlenir ve sonraki kazanır; iç alt sistemin dıştakini, daha derin bir sınırın daha sığ olanı iyileştirmesini sağlayan da budur.
Öncelik alan değerlerini belirler. Değerlendirmeyi yeniden sıralamaz: derleyicinin yüzeyleri katlama ve her eklemenin işleme öncesi injectMapping’ini yürütme sırası, architecture/10-compilation-pipeline.md sayfasında belgelenen sabit beş katmanlı sıradır. Bir eklemenin yazılmış inject bloğu yukarıdaki kapsam sıralamasını değil bu değerlendirme sırasını izler; böylece bir ekleme hiçbir zaman birbiriyle yarışan iki sıralama taşımaz.
Hangi türler metadata.labels ve metadata.annotations taşır
metadata.labels; Component, Feature, Aggregate ve dört kütüphane türünde bulunur; metadata.annotations ise Aggregate dışında aynı türlerde bulunur. Manifest, Release, Recipe, FeatureRecipe ve Plugin ikisini de taşımaz.
Kademeli aktarım özeti
Derleyicinin değerlendirdiği biçimiyle altı yüzeydeki kademeli aktarım kuralları:
- Katalog varlığı etiketleri (Yüzey 1) katalog varlığında kalır. Örneklere aktarılmazlar; tüketiciler bunları katalog içeriğini doğrudan inceleyerek okur.
- Component
metadata.labels(Yüzey 2), topoloji oluşturma sırasındaki isteğe bağlılabel-transformgeçişinden sonra düğüm başına.context.labelsiçine aktarılır. - Component
metadata.annotations(Yüzey 3), düğüm başına.context.annotations.catalogkovasına aktarılır. - Aggregate / Subsystem
annotations:(Yüzey 4), alt sistem hiyerarşisi boyunca dış alt sistemlerden içe doğru birikerek düğüm başına.context.annotations.aggregatekovasına kademeli olarak aktarılır. - Release sınırı
annotations:(Yüzey 5), sınır hiyerarşisi boyunca dış sınırlardan içe doğru düğüm başına.context.annotations.releasekovasına kademeli olarak aktarılır. - Manifest
features.annotations(Yüzey 6) düğüm başına IR verisine doğrudan kademeli olarak aktarılmaz; çözümlemenin ek açıklama güdümlü genişletme alt aşaması, bağlamaları tüketerek düğüm başına Feature eklemeleri sentezler ve IR grafiği (--ir-graph) bunlarıorigin: annotationile kaydeder. Sentetik eklemeler, çözümlemenin sonrasında bu köken dışında açık eklemelerden yapısal olarak ayırt edilemez — genişletmenin tam anlatımı içinproviders/well-known-annotations.mdbelgesine, katalog yükleme ve inceleme zamanı mekanizmaları içinarchitecture/13-catalog-and-registry.md§“Annotation-driven Feature expansion” bölümüne bakın.
Kanonik kademeli ek açıklama tasarımı için architecture/06-data-taxonomy-and-composition.md §2 (Akış 5) bölümüne bakın.
Çapraz başvurular
templates/template-context-contract.md—.context.labelsve üç.context.annotations.*kovasının çalışma zamanı görünümü.providers/well-known-annotations.md— sağlayıcı başına sınır annotation matrisi ve köken etiketi üretimindeki asimetri.entities/manifest.md— Manifest’infeatures.annotationsbağlama yüzeyi (Yüzey 6).vocabulary/publishing-surface.md— yayımlama tarafında etiketleri/annotation’ları tamamlayan tek tip metadata sözlüğü.plugins/plugin-contract.md— kovalar arası okumalara yönelik tavsiye niteliğindeki denetimler için linter soketinin yerleşim ölçütü.architecture/06-data-taxonomy-and-composition.md— kademeli annotation’ların temel tasarımı.architecture/10-compilation-pipeline.md— Feature eklemesini sıralayan 5 katmanlı soğan modeli.