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

Feature

Feature varlığının kavramsal rolü (Alan 2’deki modüler operasyonel özellik) architecture/04-entity-taxonomy.md sayfasında yer alır. Operasyonel Features ile kimlik bilgisi Features (feature.aggrega.ai/kind: secret etiketini taşıyanlar) arasındaki ayrım architecture/08-credential-model.md sayfasında açıklanır. Feature seçicilerinin kullandığı anlamsal etiket sözcük dağarcığı entities/component sayfasında yer alır. Bu sayfa, Feature kataloğunun yazım yüzeyini ele alır.

Katalog konumu

Components’ın (kategori alt dizinleriyle üç bölümlü URI’ler kullanan) aksine, Features düz bir yapıda düzenlenir: yayıncısının altında her Feature için bir dizin bulunur ve bu dizin her sürüm için bir dizin içerir.

aggrega-catalog/
└── feature/
└── {publisher}/ # e.g., `core`, `acme`
├── secret-value/
│ └── 1.0.0/
│ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature)
├── data-masking/
│ └── 1.0.0/
│ └── feature.yaml
└── ...

OCI URI’si: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (ör. hub.aggrega.ai/feature/core/data-masking:1.0.0).

Yazım sözleşmesi

Features şunları bildirir:

  • metadata.labels: Bir Feature’ı kimlik bilgisi Feature’ı olarak işaretlemek için feature.aggrega.ai/kind: secret kullanın. Etiket; yazar, katalog sitesi ve etiket seçicileri için tanımlayıcı meta veridir; hiçbir derleyici dalı onu okumaz ve bir eklemenin ne ürettiğine etiket değil, Manifest’in onun türünü eşlediği FeatureRecipe karar verir. Bir kimlik bilgisi Feature’ı ile sıradan bir Feature aynı şekilde, aynı ekleme yüzeyinde, herhangi bir kapsamda eklenir. Standart kütüphanenin kimlik bilgisi ailesi sonuca göre ayrılır: core/secret-value inject hattına bir değer iletir; core/referenced-secret başvurulabilir bir gizli kaynağı (bir Kubernetes Secret, bir AWS Secrets Manager gizlisi, bir Vault girdisi) adlandırır; bu kaynak ya FeatureRecipe’inin çıktısının oluşturduğu ya da zaten var olan bir kaynaktır; ayrıca bir tüketicinin, kaynağın adını yeniden türetmeden ona başvurmak için .features.<slot>.provides.<key> olarak okuduğu bir schema.provides çıktı sözleşmesi bildirir: name (kaynağın sağlayıcıdan bağımsız konumlayıcısı) ve key (içindeki veri alanı); core/referenced-secret-set, çağıranın sağladığı bir veri anahtarları kümesini taşıyan tek bir kaynak oluşturur ve yalnızca konumlayıcıyı yayımlar; bu, hedefi okuduğu anahtar adlarını zaten bilen bir tüketici içindir; core/secret-provided önceden var olan bir gizlinin değerini sunar; core/generated-secret hiçbir şey üretmez, çünkü kimlik bilgisini hedef motorun kendisi üretir ve yönetir; bu nedenle ne values ne de provides bildirir ve FeatureRecipes’i hiçbir bayt işlemeyen salt bağlantılardır. Üyeleri iki eksen ayırır: malzemeyi kimin sağladığı (bir yazar onu yazar ya da nereden alınacağını adlandırır veya core/generated-secret örneğindeki gibi hedef motor ona tamamen sahip olur) ve eklemenin ne verdiği: enjekte edilen bir değer, başvurulabilir bir kaynak ya da hiç işlenmiş bir şey olmaması. Her üye, aynı ekleme yüzeyinde diğerlerinin eşidir; bu yüzden bir kimlik bilgisi yuvası her zaman bağlanır ve Releases arasında değişen, onu neyin bağladığıdır. Bir schema.provides sözleşmesi bildiren kimlik bilgisi Feature’ı, onu uygulayan her FeatureRecipe’i bu anahtarları yayımlamakla yükümlü kılar (aksi halde derleme durur) ve bir featuresSchema yuvasının selector alanı ihtiyaç duyduğu aile üyesini hedefler.
  • usesSchema (isteğe bağlı): Feature’ın tüketebileceği topolojik soketleri bildirir (ör. bir kimlik bilgisi Feature’ının bir vault’u hedefleyen path / key soketi). Split Schema mekanizması için architecture/13-catalog-and-registry.md §2 bölümüne bakın.
  • schema: Feature eklemesinin values ve infra bloklarını doğrular: Developer’ın Aggregate’teki her eklemede yapılandırdığı bilişsel niyet (values Developer’ın alanıdır ve Release şeması Feature eklemelerinde values: kullanımını yasaklar) ve Operator’ün Release’te ortam başına belirlediği kapasite (infra). default: bildiren bir alan hem buna göre doğrulanır hem de hiçbir şey onu yazmadığında işlenen sütuna doldurulur; bkz. Feature kapsamı ve yazım biçimi. Kompakt biçimli YAML kısaltmasıyla (varsayılan; bkz. vocabulary/compact-form-authoring.md) ya da tam JSON Schema YAML ile ifade edilen JSON Schema 2020-12’yi kabul eder; paylaşılan biçimler için SchemaLibrary girdilerine belgeler arası $ref: kullanılabilir (bkz. vocabulary/cross-document-ref.md). Gizli malzeme taşıyan bir yaprak sensitive: true bildirir; standart kütüphanedeki kimlik bilgisi Features, malzemeyi tutan yaprağı işaretler ve yayımlanan konumlayıcılarını bilerek işaretsiz bırakır, çünkü bir kaynak adı da bir veri anahtarı da herkese açıktır. Anahtar sözcük ve onu bildirmenin neler sağlayabileceğinin sınırı, vocabulary/compact-form-authoring.md içindeki “Declaring a leaf sensitive” bölümündedir.
  • featuresSchema (isteğe bağlı): Feature’ın kendi işleyişi için ihtiyaç duyduğu ekleme yuvalarını bildirir. Bir Feature yuvaları tam olarak bir Component gibi bildirir; böylece kendisi bir kimlik bilgisine ihtiyaç duyan bir Feature (örneğin bir Datadog sidecar Feature’ının API anahtarı), ana Component’in yuvalarına uzanmak yerine bağlama noktasını adlandırır. Kendi yuvasını bildiren bir Feature ve onu dolduranı okuyan bir FeatureRecipe için Bir Feature’ın kendi kimlik bilgisi bölümüne bakın. Her yuva, bir Component’in featuresSchema yuvasının kabul ettiği alanların aynısını aynı anlamlarla kabul eder: isteğe bağlı bir selector (yuvayı hangi Feature’ın doldurabileceğini kısıtlayan Kubernetes tarzı bir etiket seçicisi, bir usesSchema soket seçicisinin yuva karşılığı; etiketleri onu karşılamayan bir doldurma derlemeyi durdurur ve seçici yalnızca eklenen Feature’ın etiketlerine göre değerlendirilir), isteğe bağlı bir sensitive (yuvayı neyin bağladığından bağımsız olarak gizli malzeme işlediğini bildirir; belirli bir doldurma hakkında değil, bağlama noktası hakkında bir ifadedir) ve aynı açıklık: bir yuva bildirmek, hiçbir yuvanın bildirmediği bir ad altında eklemeyi asla yasaklamaz. Tam alan tablosu, yuva düzeyindeki hassasiyet bildirimi ve bunun bir şema yaprağınınkinden farkı ve yuva bildiren tek bir varlığın dağıtıldığı iki biçim entities/component.md “Attachment Slots” bölümündedir.
  • appliesTo / appliesToAnyOf: Feature’ın hangi Components’e eklenebileceğini denetleyen etiket seçicileri. Statik analiz aşamasında derleyicinin yerel etiket eşleştirme motoru tarafından değerlendirilir. Seçici sözdizimi başvurusu için aşağıdaki Etiket tabanlı ekleme bölümüne ve architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” bölümüne bakın.
  • interoperability (isteğe bağlı): conflictsWith taşıyan iç içe bir blok; bu Feature’ın bir bileşene birlikte ulaşamayacağı Features. Her biri hangi kapsamda eklenmiş olursa olsun, bir bileşen sonunda ikisini birden taşıdığında derleme işlemeden önce durur. Ayrıntılı anlatım için aşağıdaki interoperability bloğu bölümüne bakın.

Bir Feature’ın yapısal işlenmesi, Feature arayüzünü somut bir altyapı uygulamasına eşleyen ilgili FeatureRecipe’ine bağlıdır.

Etiket tabanlı bağlama

Feature şemasındaki iki applies seçicisi, Feature’ın hangi Components’a bağlanacağını denetler ve derleyicinin yerel etiket eşleştirme motoru tarafından statik analiz aşamasında değerlendirilir:

  • appliesTo — Kubernetes tarzı bir etiket seçici dizesi; VE bileşimi yüzeyi. Virgülle ayrılmış gereksinimlerin tümü sağlanmalıdır ve operatör sözcük dağarcığının tamamı kullanılabilir: key=value, key!=value, key in (v1, v2), key notin (v1, v2), yalın key (etiket mevcut), !key (etiket yok). appliesTo: "datastore.aggrega.ai/engine=vector" bildiren bir Feature yalnızca tam olarak bu anahtar-değer çiftiyle etiketlenmiş Components’a bağlanır; appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)" ise “kısıtlı veri tutmayan herhangi bir server veya worker” anlamını tek bir seçici dizesiyle ifade eder.
  • appliesToAnyOf — VEYA bileşimi yüzeyi. Herhangi tek bir öğenin eşleşmesinin yeterli olduğu seçici öğelerinden oluşan bir listedir. Her öğe ya dize biçiminde bir seçicidir (appliesTo ile aynı dil bilgisi; dizenin içindeki gereksinimler VE ile birleşir) ya da yalnızca eşitlik eşleştirmesi için düz bir anahtar-değer eşlemesidir. Bir Feature birbiriyle ilgisiz birden çok bileşen biçimine uyduğunda kullanılır — örneğin ikisini tek bir seçici dizesine zorlamadan { component.aggrega.ai/type: worker } VEYA { component.aggrega.ai/type: task } için geçerli olan bir gözlemlenebilirlik Feature’ı.

any-of biçimi olmasaydı, mimarların aynı Feature YAML’ını Feature’ın uyduğu her ilgisiz bileşen biçimi için çoğaltması gerekirdi. İki biçim birlikte kullanılabilir: bir Feature ikisini de bildirebilir ve sonuçlar biçimler arasında VE ile birleşir — appliesTo dizesi sağlanmalı ve en az bir appliesToAnyOf öğesi eşleşmelidir. Atlanmış veya boş bir seçici hiçbir kısıt bildirmez ve her etiket kümesiyle eşleşir.

Bir seçici dizesi, Feature’ın her bağlanışı değerlendirildiğinde altı biçime göre okunur ve bunların dışında kalan bir gereksinim başka bir seçici olarak okunmak yerine derlemeyi durdurur: boş bir gereksinim (baştaki, sondaki veya ikilenmiş bir virgül ya da yalnızca ayırıcılardan oluşan bir dize), boşluk ya da =, !, (, ) ve virgülden herhangi birini taşıyan bir anahtar ve kapatılmamış bir in ( veya notin ( kümesi. Aksi hâlde sessizce kastedilenin tersini seçecek hatalar böyle yakalanır: bir Feature’ı ön yüzlerden uzak tutmak için yazılan appliesTo: "!tier=frontend" reddedilir, çünkü ! yalnızca bir etiket anahtarını adlandırır — bir değer tier!=frontend ile dışlanır — ve tier in frontend, tier in (frontend) lehine reddedilir. Bir değer, hangi karakterleri taşırsa taşısın operatöründen sonraki metindir; dolayısıyla tier==frontend, değeri =frontend olan bir etiket ister. Durma iletisi Feature’ı, seçicisini ve okunamayan gereksinimi adlandırır. Hiçbir şeyin bağlamadığı bir Feature hiç değerlendirilmez; bu yüzden üzerindeki hatalı biçimlendirilmiş bir seçici, bir bağlama onu adlandırana kadar bildirilmez.

Seçici söz dizimi başvurusu için architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” bölümüne bakın — bir Feature seçicisinin kabul ettiği dil bilgisi, usesSchema soket seçicilerinin kabul ettiği dil bilgisiyle aynıdır; Kubernetes kullanıcılarının kubectl get -l komutundan bildiği dize biçimidir.

interoperability bloğu

Feature şeması, tek bir denetim taşıyan isteğe bağlı bir spec.interoperability bloğu tanımlar: bu Feature’ın bir bileşen üzerinde başka hangi Features ile bir arada bulunabileceği.

interoperability.conflictsWith — tanımlanan Feature ile karşılıklı olarak birbirini dışlayan Features listesi; her biri, bir eklemenin type alanının bir Feature’ı adlandırdığı biçimde yazılır. Uyumsuz yapılandırmaların üretilmesini önler; örneğin aynı bileşene hem yalnızca TCP destekleyen bir mesh hem de HTTP farkındalıklı bir proxy eklenmesini.

Bir bileşen hem bu Feature’ı hem de listesinde adı geçen bir Feature’ı taşır duruma geldiğinde derleme, hiçbir şey işlenmeden önce durur. Belirleyici olan erişimdir: bir ekleme, üzerine yazıldığı bileşene ve üzerine yazıldığı alt sistem ya da sınır içindeki, iç içe sınırlar dahil, her bileşene erişir; bir Release bileşen girdisine yazılan ya da açıklama güdümlü genişletmeyle üretilen bir ekleme de bileşenine aynı şekilde erişir. Dolayısıyla tanımlanmış bir çakışma şu durumlarda derlemeyi durdurur: iki Feature aynı bileşene eklendiğinde, biri bir sınırda ve diğeri onun içindeki bir bileşende olduğunda, biri bir dış sınırda ve diğeri onun içinde iç içe geçmiş, bir bileşen barındıran bir sınırda olduğunda ve biri bir alt sistemde, diğeri o alt sistemdeki bir bileşende olduğunda. Ortak bileşeni olmayan kardeş sınırlara eklenen iki Feature hiçbir zaman karşılaşmaz ve bileşen barındırmayan bir sınır hiçbir şeye erişmez; ikisi de derlemeyi durdurmaz.

  • Tek bir tanım yeterlidir. Feature’lardan birinin listesi diğerini adlandırdığında derleme durur; ikinci Feature’ın da karşılık olarak birinciyi listelemesi gerekmez.
  • Sürümlerden bağımsız olarak adlar. Her girdi ve her eklemenin türü, sürüm kaldırılarak karşılaştırılır; bu nedenle core/fixed-replica-controller girdisi core/fixed-replica-controller:2.0.0 eklemesiyle eşleşir ve sürüm taşıyan bir girdi, adlandırdığı Feature’ın her sürümüyle eşleşir.
  • Okuduğu yalnızca adlardır. Derleyici, Feature’ın yazarının tanımladığı adları bir bileşenin taşıdığı Features ile karşılaştırır; bu, yazarın yazdığı veriler üzerinde appliesTo ile aynı türden bir değerlendirmedir. İki Feature’ın uyumsuz olup olmadığı yazarın kararıdır ve bu karar listede kaydedilir.

Hata durdurması; listesi diğerini adlandıran Feature’ı, ikisinin de eklendiği her yeri (Aggregate’teki bileşende, bir alt sistemde, yoluyla birlikte bir Release sınırında, bir Release bileşen girdisinde ya da adı verilen bir açıklamanın açıklama güdümlü genişletmesiyle) ve karşılaştıkları bileşeni adlandırır. Birkaç bileşende karşılaşan bir çift, her biri için bir kez raporlanır. İleti için errors/fatal-halts.md sayfasına bakın.

Örnek:

apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/autoscaler
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=server"
schema:
values:
metric_target: { type: string, enum: [cpu, memory, custom], required: true }
infra:
min_replicas: { type: integer, min: 1, required: true }
max_replicas: { type: integer, min: 1, required: true }
interoperability:
conflictsWith:
- core/fixed-replica-controller

Bu Feature yalnızca server türündeki Components’e eklenir ve replika denetleyen başka bir Feature ile uyumsuzluk tanımlar: herhangi bir bileşenin ikisini birden taşır duruma geldiği bir derleme, işleme yapılmadan önce durur. Eklendiği bileşenin adına ihtiyaç duyan bir FeatureRecipe (örneğin bir otomatik ölçekleyiciyi hedefine yönlendirmek için) bu adı şablon bağlamından okur ve çıktısının gerektirdiği her yere yazar: .context.instance_id bileşenin kimliğidir; .context.rendered_name ise bileşenin kendi sağlayıcısının onun için işlediği kaynaklara verdiği addır ve bir kaynağı hedeflemek için kullanılması gereken de budur; helm altında bu, sentezlenmiş bir iş yükünün ürettiği Deployment’ın adı ve bir chart’ın kendi adlarını türettiği release adıdır.

extends ile kalıtım

Bir Feature, yazım yüzeyini devraldığı temel bir Feature’ı gösteren spec.extends: <feature-name> bildirebilir. Başvuru, temeli Feature’ın altında yayımlandığı kayıt defteri koordinatıyla değil, metadata.name değeriyle adlandırır ve her katalog başvurusunun aldığı üç sürüm biçimini alır: mevcut en yüksek sürüm için yalın (core/queue), tam (core/queue:1.0.0) veya şapka aralığı (core/queue:^1.0.0). Derleyici, katalog yüklenirken üst zinciri dolaşır, zincirin döngüsüz olduğunu doğrular, ardından tek bir çözümlenmiş Feature üretmek için üst spec’leri alta birleştirir. Anahtar çakışmasında altın yazılmış alanları önceliklidir; üstün metadata.labels ve metadata.annotations alanları, appliesTo / appliesToAnyOf seçicileri, interoperability bloğu, usesSchema, featuresSchema ve schema üzerindeki JSON Schema 2020-12 bildirimleri otomatik olarak aşağıya birleştirilir. Diğer her metadata alanı olduğu gibi altınkidir; bu nedenle kimlik ve köken hiçbir zaman devralınmaz.

Bir Feature’ın metadata: bölümünün devraldıkları. labels ve annotations, zincir boyunca anahtar başına, önce temel olmak üzere birleşir ve ortak bir anahtarda genişleten Feature’ın değeri kazanır; bu, Components’ın izlediği kuralın aynısıdır. metadata: bölümünün geri kalanı aktarılmaz: name, version, description, maintainers, license, repository, home ve keywords, tam olarak yazıldığı haliyle genişleten Feature’ın kendisine aittir.

# Base Feature — generic message queue intent
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/queue
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=worker"
schema:
values:
qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true }
infra:
partition_count: { type: integer, min: 1 }
---
# Child Feature — Kafka-specialized variant
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/kafka-queue
version: 1.0.0
spec:
extends: core/queue:1.0.0
schema:
values:
compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }

Birleştirilmiş core/kafka-queue, appliesTo seçicisini üstten devralır, values.qos ve infra.partition_count özelliklerini devralır ve üzerine values.compression_codec ekler. appliesTo bildirimini açıkça yapan bir alt, üstün seçicisini bütünüyle geçersiz kılar (etiket seçici birleştirmesi derin değildir; altın seçicisi üstünkinin yerini alır). Bir altın schema.values.qos bildirimi, o özellik için üstün bildirimini geçersiz kılar.

Ekleme yüzeyinin her bir parçasının nasıl devralındığı. İki seçici biçimi birbirinden bağımsız olarak devralınır, çünkü birbirinin yerini almak yerine birleşirler: mevcut olan her biçim sağlanmalıdır; appliesTo dizesi eşleşmeli ve en az bir appliesToAnyOf öğesi eşleşmelidir; bulunmayan bir biçim ise hiçbir şeyi kısıtlamaz. Böylece bir Feature, kendi OR kümesini bildirirken temelinin AND seçicisini alabilir. interoperability bloğu alan alan devralınır: bloğu bir conflictsWith listesi olmadan bildiren bir alt, temelinin bildirdiği listeyi yine taşır; kendi conflictsWith listesini bildiren bir alt ise temelin listesine ekleme yapmak yerine onun yerini alır. Bu üçünden hiçbirini bildirmeyen bir Feature, tam olarak temelinin eklendiği yere eklenir.

Kalıtım, arayüz bağlama değil şema birleştirmedir. Bir Feature extends: zinciri, çok biçimli bir aile değil, tek bir çözümlenmiş Feature üretir. Zincirdeki temel Feature URI’si, bir Manifest bağlamasının feature: alanının başvurduğu şey değildir; Manifests, yaprak Feature’ın URI’siyle bağlar ve çözümlenmiş şema devralınan özellikleri içerir. Bir FeatureRecipe’in implements: ile uyguladığı Feature sözleşmesi de benzer şekilde yaprak URI’dir; FeatureRecipes kalıtım zincirinde gezinmez.

aggrega pull tabanı getirir. Bir taban Feature, onu genişleten bir Feature’ı ekleyen her Release’in bağımlılığıdır; başka bir şeyin onu adlandırıp adlandırmaması fark etmez. aggrega pull her extends: öğesini zincirin sonuna kadar izler, hiçbir katalog dizininin içermediği bir tabanı registry’den getirir ve her tabanı, onu adlandıran Feature’ın spec.extends alanından başvurulacak biçimde Release’in lockfile’ına kaydeder; bir build tabanı oradan okur.

Hata durumları. Döngüsel bir extends: zinciri ve hiçbir katalog varlığının sağlamadığı bir üst öğe, çözümlemenin başladığı Feature’ı, extends: satırı açılması gereken Feature’ı ve bildirdiği başvuruyu adlandırarak derlemeyi durdurur. İletiler Cyclic extends on Components or Features (Component’lerde veya Feature’larda döngüsel extends) ve An extends: chain cannot be assembled (Zincir oluşturulamıyor) bölümlerindedir.

Components, Features ve kimlik bilgisi Features genelindeki daha geniş kalıtım / arayüz terimleri için vocabulary/inheritance-and-interface.md sayfasına bakın.

Birleştirilebilirlik: saflık toplumsal sözleşmesi

Standart kütüphanenin uzlaşımı bir Feature, bir iç işlev şeklindedir: bir gözlemlenebilirlik sidecar’ı bir gözlemlenebilirlik Feature’ıdır; bir ağ proxy sidecar’ı bir ağ proxy Feature’ıdır; bunlar birbiriyle ilgisiz iki kaygıyı taşıyan tek bir bileşik yapıda birleşmez. Bu uzlaşım, tek tek Features’ın birleştirilebilir, bağımsız olarak sürümlenebilir ve bağımsız olarak eklenebilir kalmasını sağlar.

Çekirdek Go derleyicisi bu uzlaşımı zorunlu kılmaz. Karışık kaygılar içeren Feature tanımları sözdizimsel olarak geçerlidir ve sorunsuz derlenir. Denetim isteğe bağlıdır:

  • İç kataloglar hazırlayan kuruluşlar, CI/CD’de Feature tanımlarını inceleyen ve tek bir Feature’ın appliesTo etiketleri birbiriyle ilgisiz yetenek alanlarına yayıldığında uyarı veren özel bir linter eklentisi yazabilir.
  • İki Features’ın çakışacağını interoperability.conflictsWith içine kaydeden bir Feature yazarı, derleme zamanı denetimini seçmiş olur: ikisinin tek bir bileşene ulaştığı her yerde derleyici durur. Derleyici yalnızca bildirilen adları karşılaştırır, başka bir şey yapmaz; dolayısıyla saflık uzlaşımının kendisini değil, yazarın yazdığı bildirimi uygular.

Açık kaynaklı standart kütüphane Features’ı saflık uzlaşımına yazım disiplini yoluyla uyar; kurumsal kataloglar ise sıkı bağlı bir bileşik yapı dağıtım modeline gerçekten uyduğunda bundan ayrılmakta serbesttir.

Neyin bir Feature olmayı hak ettiği ve bir ürünün kendi ayarının nereye ait olduğu

Bir Feature bir eklemedir: geliştiricinin veya operatörün bilinçli olarak eklediği bir şey getirir (kaynaklar, bir işlem hattı adımı, bağlantılar) ve standart kütüphane uzlaşımı, bunun en az iki bağımsız ürün tarafından karşılanabilir olmasıdır. Bu ikinci yarı, bir Feature yazmadan önce uygulanacak testtir, çünkü ekleme sözcüğünün vaat ettiği şey taşınabilirliktir. Bir ekleme, yeteneğin taşınabildiğini söyler: onu bir bileşene ekleyin, başka birine ekleyin; her ürünün gerçekleştirimi onu kendi koşullarıyla karşılar.

Alanda yalnızca tek bir üründe bulunan bir yetenek, bir Feature değil, o ürünün kendi ayarıdır. Bu yetenek, o ürünün kendi yüzeyinde yazılmış bir değer olarak yer alır; bu değeri, ona karar veren yazar kendi sütununda ayarlar ve aynı ürünü yapılandıran diğer her şeyin yanında okur. Bunu bunun yerine bir Feature olarak yayımlamak, başka hiçbir ürünün sağlayamayacağı bir taşınabilirlik sunar: ekleme yapısı gereği tek bir ürünü adlandırır, bu nedenle onu kullanmak istediği bir sonraki ürüne ekleyen yazar, türü adlandırarak duran bir derlemeyle karşılaşır ve Feature, hiçbir zaman sahip olmadığı bir yeteneği öğretmiş olur.

Test, bu katalogdaki bileşenleri değil, alandaki ürünleri sayar; her biri kendi güncel yapılandırma başvurusundan okunur. Bir yeteneği uygulayan iki bağımsız ürün, burada bunlardan kaçı sunulursa sunulsun o yeteneği taşınabilir kılar; bu nedenle bir Feature, katalogdaki hiçbir şey onu gerçekleştirmeden önce bildirilebilir (o durumda onu eklemek, derlemeyi türü adlandırarak durdurur) ve sunulan her gerçekleştirim, eklemeyi o ürünün yapılandırdığı şekilde karşılayan, tek bir ürün için bir FeatureRecipe’tir.

Üst akış sertifika sabitleme, işlenmiş örnektir. Bir sabitleme, bir üst akışın hangi anahtarı sunabileceği üzerinde bir denetimdir: yalnızca açık anahtarı Release’in sağladığı anahtarlardan biriyle eşleşen bir sertifikayı kabul et. Bu, bir üst akışın sertifikasının Release’in sağladığı bir güven çapasına zincirlenmesini gerektirmekten farklı bir iddiadır ve bir sertifikanın öznesinin ne söylediğini ileri sürmekten de yine farklıdır: bu ikisi bir sertifikanın ne söylemesi gerektiğini belirtirken, bir sabitleme onun hangi anahtar olması gerektiğini belirtir. Buradaki birkaç ağ geçidi bir çapaya karşı doğrulama yapabilir; dataplane.aggrega.ai/upstream-tls: trust-anchor değerinin bir seçicinin eşleştirebileceği bir değer olmasının nedeni budur. Sabitleme ayrı bir yetenektir ve en az iki bağımsız ürün bunu bir üst akışa açtıkları bağlantılar için uygular: Tyk üst akışın açık anahtarını PEM biçiminde alır, Envoy ise onun bir özetini alır. Dolayısıyla bu bir Feature’dır, core/upstream-key-pinning; seçicisi dataplane.aggrega.ai/upstream-pinning: public-key değerini adlandırır ve bu kataloğun neyi gerçekleştirdiği ürün ürün yanıtlanır: core/gateway/tyk değeri ve hedeflerinin her biri için bir FeatureRecipe taşır; Envoy’u gömen buradaki ağ geçitleri ise sabitleme ayarını yalnızca istemcilerin sunduğu sertifikalar için sunar ya da hiç sunmaz, bu nedenle değer taşımazlar ve onlara yapılan bir ekleme seçicide durur. Bir sabitleme, bir üst akışın sunabileceği şeyi daraltır; bu bir denetimdir, bağlantının başka açılardan sağlam olduğuna dair bir güvence değildir.

Testin iki sınırı vardır ve ikincisi en kolay gözden kaçan yarıdır:

  • Bu bir yazım disiplinidir, derleyici denetimi değildir. Hiçbir ürünün uygulamadığı seçenekleri bildiren bir Feature şema doğrulamasından, yayımlama linter’ından ve bir işlemeden aynı şekilde geçer; derleyici bir Feature’ın neyi vaat ettiğini yorumlamaz. Karar katalog yazarına kalır.
  • Bir ürünün bir seçeneği karşılayamaması, o seçeneği kaldırmak için gerekçe değildir. İki veya daha fazla ürünün bir yeteneği gruplanabilen adlar altında sunduğu durumda yetenek taşınabilirdir ve Feature onu korur; onu karşılayamayan ürün onu reddeder. Her ürünün desteklediği şeye indirgenmiş bir Feature’ın söyleyecek neredeyse hiçbir şeyi kalmaz.

Feature kapsamı ve yazım biçimi

Bir Feature’ın spec.schema alanı, Feature’ın kendi values: ve infra: biçimlerini tanımlar: Developer’ın Aggregate içinde her Feature eklemesi için yapılandırdığı bilişsel niyet (values), Operator’ün her ortam için belirlediği kapasite sayılarından (infra) ayrıdır. Feature’ın sütunları kendi ad alanlarında bulunur ve barındıran Component’in sütunlarından bağımsız olarak doğrulanır. Developer, Aggregate içinde bir autoscaler Feature’ını bir web-server Component’ine eklediğinde Aggregate, Component’in values: bloğunu (barındıran biçimi) ve Feature’ın values: bloğunu (ölçekleme niyeti biçimi: ölçeklemeyi hangi metriğin yönlendirdiği) taşır; operatöre yönelik kapasite sayıları (min_replicas / max_replicas) ise Feature eklemesi üzerindeki Release’in infra: bloğundan akar.

# Aggregate fragment — Feature attachment with its own values:
components:
web-server:
type: core/web-server
values:
log_level: "info" # the Component's own values
tls_enabled: true
features:
autoscaler:
type: core/autoscaler
values:
metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)
# Release fragment — Feature attachment's infra block (operator-side capacity):
boundaries:
prod:
components:
web-server:
features:
autoscaler:
infra:
min_replicas: 2
max_replicas: 10

Feature’ın schema: alanı, Feature eklemesinin kendi values: ve infra: bloklarını doğrular. Component’in schema: alanı ise Component’in kendi bloklarını doğrular. İkisi statik analiz aşamasında bağımsız olarak değerlendirilir; Feature’ın schema: alanıyla eşleşmeyen bir ekleme sütunu, derlemeyi barındıran Component’e değil Feature ekleme noktasına kapsamlanmış bir hatayla durdurur. Doğrulanan, eklemenin etkin yapılandırmasıdır, yani onu yapılandıran tüm kapsamların birleştirilmesinin sonucudur; bu nedenle bir kapsamda uygun hâle getirilip daha dar bir kapsamda geçersiz bir değerle geçersiz kılınan bir değer yakalanır.

Bildirilen varsayılanlar, eklemenin işlenmiş sütunlarına somutlaşır. Doğrulamanın ötesinde, bir Feature’ın values veya infra alanında bildirilen bir default:, derleme zamanında hiçbir şeyin yazmadığı her anahtar için o eklemenin işlenmiş sütununa doldurulur; böylece {{ .infra.tier }} okuyan bir FeatureRecipe şablonu boş bir değer yerine şemada bildirilen değeri alır. Yazarın sağladığı değerler her zaman önceliklidir ve bir varsayılan yalnızca onların atladığı anahtarları doldurur: Feature şemasının bir anahtarını yazan bir ekleme, o şemanın diğer anahtarları için bildirilen varsayılanları yine de alır; kısmen yazılmış iç içe bir nesne de yazılanı korur ve yazılmayan kardeş anahtarları kazanır.

Yazım sırasında doldurmanın üç özelliğini bilmekte yarar vardır:

  • Bir varsayılan, herhangi bir kapsamın sağladığı bir değerin yerini asla almaz. Bir Feature birden fazla kapsamda eklendiğinde (örneğin bir Release sınırında ve onun bileşenlerinden birinde), daha dar kapsamın değeri geçerli kalır ve varsayılan yalnızca hiçbir kapsamın yazmadığı şeyleri doldurur.
  • Bir varsayılan bir eklemeyi doldurur; asla yeni bir ekleme oluşturmaz. Hiçbir şeyin eklemediği bir Feature üzerinde varsayılan bildirmek çıktıya hiçbir şey katmaz; bu nedenle bir Feature’ın şeması hiçbir yazarın istemediği yapılandırmayı ekleyemez.
  • Tek bir bileşen yerine bir Release sınırında bildirilen bir ekleme yalnızca infra alanını doldurur, çünkü o yüzey doldurulacak bir values: bloğu taşımaz.

Somutlaştırma, doğrulamayla aynı şema çözümlemesini kullandığından, üst Feature üzerinde bildirilen bir varsayılan bir extends: alt öğesinin eklemelerine ulaşır ve belgeler arası bir $ref: ile bir SchemaLibrary içinden ulaşılan varsayılanlar da somutlaşır. Yalnızca belge içi yerel bir #/$defs/ başvurusunun içinde ya da bir allOf / oneOf / anyOf dalı altında bildirilen varsayılanlar somutlaştırılmaz.

Doğrulama tek başına ortaya çıkarmayacağı için bir sonucu açıkça belirtmekte yarar vardır: aynı zamanda bir default: taşıyan bir required: alanı o varsayılanla karşılanır, dolayısıyla onu atlamak geçerlidir; ve denetimin kabul ettiği değer, işlenmiş çıktının taşıdığı değerdir.

Derleyicinin şablon bağlamı, Feature’ın örnek durumunu bağlı FeatureRecipe’e .features.<alias> alanı aracılığıyla sunar (her bağlama için .type, .resolved_version, .labels, .values, .infra ve .provides içerir). FeatureRecipe içindeki şablonlar, Feature’ın kendi values: değerlerini FeatureRecipe’in kendi şablon kapsamında .values.<field> ile okur; Feature, barındıran Component’e açıkça bir uses: soketi bildirmedikçe barındıran Component’in values: değerleri FeatureRecipe’in şablonlarına doğrudan görünmez.

Bu kapsam ayrımı Features’ı birleştirilebilir kılar: bir autoscaler Feature’ı hangi Component’e bağlandığına bağlı değildir; schema: alanı, barındırandan bağımsız olarak otomatik ölçekleme niyetini tanımlar. Barındıran Component’in values: değerleri barındıranı ilgilendirir; Feature’ın values: değerleri ise Feature’ı ilgilendirir; iki sütun, alan adlarını sınırın ötesine sızdırmadan birleşir.

Ek açıklama bağlama hedefleri

Bir Feature, ek açıklama bağlamalarını kendisi bildirmez; bunları Manifest’in mappings.features.annotations eşlemesi taşır. Bir Feature, bağlama ilişkisine yönlendirme hedefi olarak dolaylı biçimde katılır: her bağlama, feature: alanı aracılığıyla bir Feature türünü adlandırır ve bağlamanın maps.infra ve maps.values listeleri, adlandırılan Feature’ın spec.schema.infra.<path> ve spec.schema.values.<path> özelliklerine giden noktalı yollar bildirir.

Katalog yüklenirken derleyici, bir bağlamanın maps listelerindeki her noktalı yolun, hedef Feature’ın spec.schema alanının adlandırılan sütunda gerçekten bildirdiği bir özelliğe karşılık geldiğini doğrular. Feature şemasının bildirmediği bir yola yönlendiren bir bağlama, katalog yüklemesini açık bir OPS_ERROR ile durdurur; bu hata bağlamayı, hedef Feature’ı ve bağlamanın üzerinden yönlendirdiği sütunu ve yolu adlandırır; çünkü bağlama, operatörün belgesi olan Manifest’te yazılmıştır. Bu nedenle şema yazarları, spec.schema.values.<path> veya spec.schema.infra.<path> altında bildirdikleri her özelliğin bir bağlama hedefi olarak erişilebilir olduğunu bilir; tersine, bir Manifest bağlamasının üzerinden yönlendirdiği her özellik, hedef Feature’ın şemasında bulunmalıdır.

Aggregate tarafındaki veya Release tarafındaki bir ek açıklama bir bağlamayla eşleştiğinde derleyici, sütun yükleri ek açıklama değerini adlandırılan yollara yönlendiren bir Feature eklemesi sentezler. Sentezlenen ekleme, aynı konumda yazarın açıkça bildirdiği bir Feature eklemesinden yapısal olarak ayırt edilemez; aşağı akıştaki oluşturma, doğrulama ve FeatureRecipe şablon bağlamı her iki biçimi de aynı şekilde tüketir. Bağlama biçimi, taraf-sütun ayrımı ve açık eklemenin kazanması disiplini için bkz. entities/manifest.md §“Annotation-Driven Feature Bindings”. Aggregate tarafı basamaklama kuralı ve yazım örneği için bkz. providers/well-known-annotations.md §“Aggregate-side annotation cascade”.

assertions: bloğu

Feature.spec.assertions:, Feature sözleşmesinin mimari değişmezlerini ifade eden adlandırılmış kurallardan oluşan isteğe bağlı bir eşlemedir: Feature’ın values: alanı ve bağlı Component’in çözümlenmiş durumu üzerinde alanlar arası kurallar. Her anahtar, hata iletisinde görünen bir kural tanımlayıcısıdır; her değer bir Go şablonu gövdesidir. Derleyici bunları şema doğrulamasından sonra ve bağlı FeatureRecipe işlenmeden önce, yazıldıkları sırayla değerlendirir; başarısız olan ilk kural, derlemeyi o kuralın kendi hata iletisiyle durdurur.

spec:
appliesTo: "component.aggrega.ai/type=server"
assertions:
active-active-needs-two-replicas: |
{{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}}
{{- fail "mode=active-active requires replicas >= 2" -}}
{{- end -}}

Component assertion’ları gibi Feature assertion’ları da sözleşme düzeyindeki değişmezleri ifade eder: işlemeyi hangi FeatureRecipe uygularsa uygulasın Feature ekinin karşılaması gereken özellikler. Belirli bir uygulamaya bağlı alanlar arası kurallar için (bir Wasm plugin gereksinimi, bir chart’a özgü tuhaflık) bunun yerine FeatureRecipe’in assertions: alanını kullanın. Yazım dilbilgisinin tamamı, şablon bağlamı ve Feature ile FeatureRecipe assertion’ları arasındaki sorumluluk paylaşımı için templates/assertions-block.md sayfasına bakın.