Feature
Koncepcyjna rola encji Feature (modularnej cechy operacyjnej w Domenie 2) jest opisana w architecture/04-entity-taxonomy.md. Rozróżnienie między operacyjnymi encjami Features a encjami Features poświadczeń (oznaczonymi etykietą feature.aggrega.ai/kind: secret) opisano w architecture/08-credential-model.md. Słownik etykiet semantycznych używany przez selektory encji Feature znajduje się w entities/component. Ta strona omawia powierzchnię tworzenia katalogu encji Feature.
Położenie w katalogu
W przeciwieństwie do encji Components (które używają trzysegmentowych URI z podkatalogami kategorii) encje Features mają strukturę płaską: jeden katalog na każdą encję Feature w obrębie jej wydawcy, zawierający po jednym katalogu na każdą wersję.
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 └── ...URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (np. hub.aggrega.ai/feature/core/data-masking:1.0.0).
Kontrakt tworzenia
Encje Features deklarują:
metadata.labels: etykietafeature.aggrega.ai/kind: secretoznacza encję Feature jako Feature poświadczeń. Etykieta jest opisowymi metadanymi dla autora, dla strony katalogu i dla selektorów etykiet; żadna gałąź kompilatora jej nie odczytuje, a o tym, co daje dołączenie, decyduje encja FeatureRecipe, na którą Manifest mapuje jej typ, a nie etykieta. Feature poświadczeń i zwykły Feature dołącza się w ten sam sposób, na tej samej powierzchni dołączania, w dowolnym zakresie. Rodzina poświadczeń biblioteki standardowej dzieli się według wyniku:core/secret-valuedostarcza wartość do potoku wstrzykiwania;core/referenced-secretwskazuje zasób sekretu, do którego można się odwołać (Secret w Kubernetes, sekret AWS Secrets Manager, wpis w Vault), tworzony przez wynik jego encji FeatureRecipe lub już istniejący, i deklaruje kontrakt wyjściowyschema.provides—name(neutralny wobec dostawcy lokalizator zasobu) orazkey(pole danych w nim) — który konsument odczytuje jako.features.<slot>.provides.<key>, aby odwołać się do zasobu bez ponownego wyprowadzania jego nazwy;core/referenced-secret-setmaterializuje jeden zasób zawierający podany przez wywołującego zestaw kluczy danych i publikuje sam lokalizator, dla konsumenta, którego cel zna już nazwy odczytywanych kluczy;core/secret-providedudostępnia wartość istniejącego wcześniej sekretu;core/generated-secretnie produkuje niczego, ponieważ docelowy silnik sam generuje poświadczenie i nim zarządza, więc nie deklaruje anivalues, aniprovides, a jego encje FeatureRecipes są czystym okablowaniem, które nie renderuje żadnych bajtów. Członków rodziny rozróżniają dwie osie: kto dostarcza materiał — autor go wpisuje lub wskazuje, skąd go pobrać, albo docelowy silnik w pełni go posiada, jak w przypadkucore/generated-secret— oraz co daje dołączenie: wstrzykniętą wartość, zasób, do którego można się odwołać, albo nic wyrenderowanego. Każdy członek jest równorzędny wobec pozostałych na tej samej powierzchni dołączania, więc slot poświadczeń jest zawsze powiązany, a między encjami Releases różni się to, co go wiąże. Feature poświadczeń deklarujący kontraktschema.provideszobowiązuje każdą implementującą go encję FeatureRecipe do opublikowania tych kluczy — w przeciwnym razie kompilacja się zatrzymuje — aselectorslotufeaturesSchemawskazuje potrzebnego członka rodziny.usesSchema(opcjonalne): deklaruje gniazda topologiczne, które Feature może konsumować (np. gniazdopath/keyencji Feature poświadczeń wskazujące na sejf). Opis mechanizmu Split Schema znajduje się w architecture/13-catalog-and-registry.md §2.schema: waliduje blokivaluesiinfradołączenia encji Feature — intencję poznawczą, którą Developer konfiguruje przy każdym dołączeniu w encji Aggregate (valuesnależą do domeny Developera, a schemat encji Release zabraniavalues:w dołączeniach Feature), oraz pojemność, o której Operator decyduje dla każdego środowiska w encji Release (infra). Pole deklarującedefault:jest zarówno walidowane, jak i wpisywane do renderowanego filaru, gdy nikt go nie ustawia; zob. Zakres encji Feature i kształt tworzenia. Przyjmuje JSON Schema 2020-12 wyrażony w skróconej notacji YAML w formie kompaktowej (domyślnie; zob.vocabulary/compact-form-authoring.md) lub w pełnym YAML JSON Schema, z międzydokumentowymi odwołaniami$ref:do wpisów SchemaLibrary dla współdzielonych kształtów (zob.vocabulary/cross-document-ref.md). Liść przenoszący materiał sekretny deklarujesensitive: true— encje Features poświadczeń w bibliotece standardowej oznaczają liść przechowujący materiał i celowo pozostawiają publikowane lokalizatory nieoznaczone, ponieważ nazwa zasobu i klucz danych są publiczne. Słowo kluczowe oraz granica tego, co daje jego zadeklarowanie, są opisane wvocabulary/compact-form-authoring.md„Declaring a leaf sensitive”.featuresSchema(opcjonalne): deklaruje sloty dołączania, których Feature potrzebuje do własnego działania — Feature deklaruje sloty dokładnie tak samo jak Component, więc Feature, który sam potrzebuje poświadczenia (na przykład klucza API encji Feature sidecara Datadog), wskazuje punkt wiązania zamiast sięgać po sloty encji Component, na której jest osadzony. Encja Feature deklarująca własny slot i encja FeatureRecipe odczytująca to, co go wypełnia, są pokazane w sekcji Własne poświadczenie encji Feature. Każdy slot przyjmuje te same pola co slotfeaturesSchemaencji Component, z tą samą semantyką — w tym opcjonalnyselector(selektor etykiet w stylu Kubernetes ograniczający, który Feature może wypełnić slot, odpowiednik selektora gniazdausesSchemadla slotu; wypełnienie, którego etykiety go nie spełniają, zatrzymuje kompilację, a selektor jest oceniany wyłącznie względem etykiet dołączonej encji Feature), opcjonalnesensitive(deklarujące, że cokolwiek wiąże slot, obsługuje materiał sekretny — stwierdzenie dotyczące punktu wiązania, a nie konkretnego wypełnienia) oraz tę samą otwartość: zadeklarowanie slotu nigdy nie zabrania dołączenia pod nazwą, której nie deklaruje żaden slot. Pełna tabela pól, deklaracja wrażliwości na poziomie slotu i jej różnica względem deklaracji liścia schematu oraz dwa kształty, w jakich wdrażana jest jedna encja deklarująca sloty, są opisane w entities/component.md „Attachment Slots”.appliesTo/appliesToAnyOf: selektory etykiet określające, do których encji Components Feature może zostać dołączony. Oceniane przez natywny silnik dopasowywania etykiet kompilatora na etapie analizy statycznej. Opis składni selektorów znajduje się w sekcji Dołączanie na podstawie etykiet poniżej oraz w architecture/13-catalog-and-registry.md §2 „Kubernetes-Style Selectors”.interoperability(opcjonalny): zagnieżdżony blok zawierającyconflictsWith— Features, z którymi ten Feature nie może trafić do tego samego komponentu. Kompilacja zatrzymuje się przed renderowaniem, gdy jeden komponent otrzyma oba, niezależnie od tego, w jakim zakresie każdy z nich został dołączony. Pełne omówienie zawiera sekcja blokinteroperabilityponiżej.
Renderowanie strukturalne encji Feature jest powiązane z odpowiadającą jej encją FeatureRecipe, która mapuje interfejs encji Feature na konkretną implementację infrastruktury.
Dołączanie na podstawie etykiet
Dwa selektory „applies” w schemacie encji Feature określają, do których encji Components dana encja Feature jest dołączana; są one ewaluowane przez natywny mechanizm dopasowywania etykiet kompilatora na etapie analizy statycznej:
appliesTo— ciąg selektora etykiet w stylu Kubernetes; powierzchnia kompozycji AND. Wszystkie wymagania rozdzielone przecinkami muszą być spełnione, z pełnym słownikiem operatorów:key=value,key!=value,key in (v1, v2),key notin (v1, v2), samkey(etykieta obecna),!key(etykieta nieobecna). Encja Feature deklarującaappliesTo: "datastore.aggrega.ai/engine=vector"jest dołączana tylko do encji Components oznaczonych dokładnie tą parą klucz-wartość;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"wyraża „dowolny serwer lub worker, który nie przechowuje danych zastrzeżonych” w jednym ciągu selektora.appliesToAnyOf— powierzchnia kompozycji OR. Lista elementów selektora, w której wystarczy dopasowanie dowolnego pojedynczego elementu. Każdy element jest albo selektorem w postaci ciągu (ta sama gramatyka coappliesTo; wymagania wewnątrz ciągu łączą się przez AND), albo płaską mapą klucz-wartość do dopasowania wyłącznie na równość. Stosowany, gdy encja Feature pasuje do wielu niepowiązanych kształtów komponentów — na przykład encja Feature obserwowalności, która dotyczy albo{ component.aggrega.ai/type: worker }, ALBO{ component.aggrega.ai/type: task }, bez wtłaczania obu w jeden ciąg selektora.
Bez formy any-of architekci musieliby powielać ten sam YAML encji Feature dla każdego niepowiązanego kształtu komponentu, do którego ta encja Feature pasuje. Obie formy się składają: encja Feature może zadeklarować obie, a wyniki łączą się przez AND między formami — ciąg appliesTo musi być spełniony i co najmniej jeden element appliesToAnyOf musi pasować. Pominięty lub pusty selektor nie deklaruje żadnego ograniczenia i pasuje do każdego zbioru etykiet.
Ciąg selektora jest odczytywany względem sześciu form za każdym razem, gdy ewaluowane jest dołączenie encji Feature, a wymaganie spoza nich zatrzymuje budowanie, zamiast zostać odczytane jako inny selektor: puste wymaganie (przecinek na początku, na końcu lub podwojony albo ciąg złożony wyłącznie z separatorów), klucz zawierający biały znak lub którykolwiek z =, !, (, ) oraz przecinek, a także niezamknięty zbiór in ( lub notin (. To właśnie wychwytuje błędy, które w przeciwnym razie po cichu wybrałyby odwrotność zamierzonego: appliesTo: "!tier=frontend", napisane, aby trzymać encję Feature z dala od frontendów, zostaje odrzucone, ponieważ ! wskazuje klucz etykiety i nic więcej — wartość wyklucza się przez tier!=frontend — a tier in frontend zostaje odrzucone na rzecz tier in (frontend). Wartością jest tekst po operatorze, niezależnie od zawartych w nim znaków, więc tier==frontend żąda etykiety o wartości =frontend. Komunikat zatrzymania podaje encję Feature, jej selektor oraz wymaganie, którego nie udało się odczytać. Encja Feature, której nic nie dołącza, nigdy nie jest ewaluowana, więc błędny selektor w niej nie zostanie zgłoszony, dopóki nie wskaże jej jakieś dołączenie.
Opis składni selektorów znajduje się w architecture/13-catalog-and-registry.md §2 „Selektory w stylu Kubernetes” — gramatyka akceptowana przez selektor encji Feature jest tą samą gramatyką, którą akceptują selektory gniazd usesSchema, czyli postacią ciągu znaną użytkownikom Kubernetes z kubectl get -l.
Blok interoperability
Schemat encji Feature deklaruje opcjonalny blok spec.interoperability zawierający jedną kontrolę: z którymi innymi Features ta encja Feature może współistnieć na komponencie.
interoperability.conflictsWith — lista Features wzajemnie wykluczających się z definiowaną encją Feature, z których każda jest zapisana tak, jak pole type dołączenia nazywa encję Feature. Zapobiega generowaniu niezgodnych konfiguracji — na przykład dołączeniu do tego samego komponentu zarówno siatki obsługującej tylko TCP, jak i proxy rozumiejącego HTTP.
Kompilacja zatrzymuje się przed wyrenderowaniem czegokolwiek, gdy jeden komponent ostatecznie przenosi tę encję Feature oraz encję Feature wymienioną na jej liście. Liczy się zasięg: dołączenie sięga komponentu, na którym jest zapisane, oraz każdego komponentu wewnątrz podsystemu lub granicy, na których jest zapisane, łącznie z granicami zagnieżdżonymi; dołączenie zapisane we wpisie komponentu encji Release lub wytworzone przez rozwinięcie sterowane adnotacjami sięga swojego komponentu w ten sam sposób. Zadeklarowany konflikt zatrzymuje więc kompilację, gdy obie Features są dołączone do tego samego komponentu, gdy jedna jest na granicy, a druga na komponencie wewnątrz niej, gdy jedna jest na granicy zewnętrznej, a druga na zagnieżdżonej w niej granicy zawierającej komponent, oraz gdy jedna jest na podsystemie, a druga na komponencie w tym podsystemie. Dwie Features dołączone do sąsiednich granic, które nie mają wspólnego komponentu, nigdy się nie spotykają, a granica niezawierająca komponentu nie sięga niczego — żaden z tych przypadków nie zatrzymuje kompilacji.
- Wystarczy jedna deklaracja. Kompilacja zatrzymuje się, gdy lista którejkolwiek encji Feature wymienia drugą; druga encja Feature nie musi z powrotem wymieniać pierwszej.
- Nazwy, niezależnie od wersji. Każdy wpis i typ każdego dołączenia są porównywane po usunięciu wersji, więc wpis
core/fixed-replica-controllerpasuje do dołączeniacore/fixed-replica-controller:2.0.0, a wpis zawierający wersję pasuje do każdej wersji wskazanej encji Feature. - Odczytywane są wyłącznie nazwy. Kompilator porównuje nazwy zadeklarowane przez autora encji Feature z Features, które przenosi komponent — to ten sam rodzaj ewaluacji co
appliesTo, na danych zapisanych przez autora. To, czy dwie Features są niezgodne, jest oceną autora, a lista jest miejscem, w którym ta ocena zostaje zapisana.
Komunikat zatrzymania wskazuje encję Feature, której lista wymienia drugą, każde miejsce, w którym każda z nich została dołączona — na komponencie w encji Aggregate, na podsystemie, na granicy encji Release wraz z jej ścieżką, we wpisie komponentu encji Release lub przez rozwinięcie sterowane nazwaną adnotacją — oraz komponent, na którym się spotykają. Para spotykająca się na kilku komponentach jest zgłaszana raz dla każdego z nich. Treść komunikatu opisano w errors/fatal-halts.md.
Przykład:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: 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-controllerTa encja Feature dołącza się tylko do Components typu server i deklaruje niezgodność z inną encją Feature sterującą replikami: kompilacja, w której dowolny komponent ostatecznie przenosi obie, zatrzymuje się przed renderowaniem. Encja FeatureRecipe, która potrzebuje nazwy komponentu, do którego jest dołączona — na przykład aby skierować autoskaler na jego cel — odczytuje ją z kontekstu swojego szablonu i zapisuje wszędzie tam, gdzie wymaga tego jej wynik: .context.instance_id to tożsamość komponentu, a .context.rendered_name to nazwa, którą dostawca komponentu nadaje zasobom renderowanym dla niego, i to według niej należy wskazywać zasób — w przypadku helm jest to nazwa obiektu Deployment emitowanego przez syntetyzowane obciążenie oraz nazwa wydania, z której chart buduje własne nazwy.
Dziedziczenie przez extends
Encja Feature może zadeklarować spec.extends: <feature-name>, wskazując bazową encję Feature, której powierzchnię autorską dziedziczy. Odwołanie wskazuje bazę przez jej metadata.name, a nie przez współrzędną rejestru, pod którą Feature jest publikowana, i przyjmuje te same trzy formy wersji co każde odwołanie katalogowe: samą nazwę (core/queue) dla najwyższej dostępnej wersji, wersję dokładną (core/queue:1.0.0) albo zakres z daszkiem (core/queue:^1.0.0). Kompilator przechodzi łańcuch rodziców podczas ładowania katalogu, sprawdza, czy łańcuch jest acykliczny, a następnie scala specyfikacje rodziców z dzieckiem, tworząc jedną rozwiązaną encję Feature. Pola zapisane przez autora dziecka mają pierwszeństwo przy kolizji kluczy; metadata.labels i metadata.annotations rodzica, selektory appliesTo / appliesToAnyOf, blok interoperability, usesSchema, featuresSchema oraz deklaracje JSON Schema 2020-12 w schema są automatycznie scalane w dół. Każde inne pole metadata pochodzi dosłownie z dziecka, więc tożsamość i pochodzenie nigdy nie są dziedziczone.
Co dziedziczy metadata: encji Feature. labels i annotations są scalane według klucza wzdłuż łańcucha, począwszy od bazy, przy czym przy wspólnym kluczu wygrywa wartość rozszerzającej encji Feature — tę samą regułę stosują encje Components. Reszta metadata: nie jest przenoszona: name, version, description, maintainers, license, repository, home i keywords należą do rozszerzającej encji Feature, dokładnie tak, jak je zapisano.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: 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 variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Scalona core/kafka-queue dziedziczy appliesTo od rodzica, dziedziczy właściwości values.qos i infra.partition_count oraz dodaje do nich values.compression_codec. Dziecko jawnie deklarujące appliesTo zastępuje w całości selektor rodzica (scalanie selektorów etykiet nie jest głębokie — selektor dziecka zastępuje selektor rodzica). schema.values.qos dziecka zastępuje deklarację rodzica dla tej właściwości.
Jak dziedziczy każda część powierzchni dołączania. Obie formy selektora dziedziczą niezależnie od siebie, ponieważ się składają, a nie zastępują: każda obecna forma musi być spełniona — ciąg appliesTo musi pasować i co najmniej jeden element appliesToAnyOf musi pasować — a forma nieobecna niczego nie ogranicza. Encja Feature może więc przejąć selektor AND swojej bazy, deklarując jednocześnie własny zbiór OR. Blok interoperability dziedziczy pole po polu — dziecko, które deklaruje blok bez listy conflictsWith, nadal ma listę zadeklarowaną przez bazę, natomiast dziecko deklarujące własną conflictsWith zastępuje listę bazy, zamiast ją uzupełniać. Encja Feature, która nie deklaruje żadnego z tych trzech elementów, dołącza się dokładnie tam, gdzie jej baza.
Dziedziczenie to scalanie schematów, a nie wiązanie interfejsów. Łańcuch extends: encji Feature tworzy jedną rozwiązaną encję Feature, a nie polimorficzną rodzinę. Pole feature: wiązania w encji Manifest nie odwołuje się do URI bazowej encji Feature z łańcucha — encje Manifests wiążą się przez URI liściowej encji Feature, a rozwiązany schemat zawiera odziedziczone właściwości. Kontrakt Feature, który encja FeatureRecipe deklaruje w implements:, to również URI liścia; encje FeatureRecipes nie przechodzą łańcucha dziedziczenia.
aggrega pull pobiera bazę. Bazowa encja Feature jest zależnością każdej encji Release, która dołącza encję Feature rozszerzającą tę bazę, niezależnie od tego, czy cokolwiek innego ją wskazuje. aggrega pull podąża za każdym extends: do końca łańcucha, pobiera z rejestru bazę, której nie zawiera żaden katalog encji, i zapisuje każdą bazę w pliku blokady encji Release, z odwołaniem ze spec.extends encji Feature, która ją wskazuje; kompilacja odczytuje bazę stamtąd.
Tryby błędów. Cykliczny łańcuch extends: oraz rodzic, którego nie dostarcza żadna encja katalogu, zatrzymują kompilację, wskazując encję Feature, od której zaczęło się rozwiązywanie, encję Feature, której wiersz extends: należy otworzyć, oraz zadeklarowane przez nią odwołanie. Komunikaty opisano w Cyclic extends on Components or Features (Cykliczne extends w encjach Component lub Feature) i An extends: chain cannot be assembled (Nie można złożyć łańcucha).
Szersze słownictwo dotyczące dziedziczenia i interfejsów w encjach Components, Features i Features poświadczeń opisuje vocabulary/inheritance-and-interface.md.
Kompozycyjność: umowa społeczna czystości
Konwencja biblioteki standardowej to jedna encja Feature, jedna funkcja wewnętrzna — sidecar obserwowalności jest encją Feature obserwowalności; sidecar proxy sieciowego jest encją Feature proxy sieciowego; nie łączą się one w jedną złożoną całość o dwóch niepowiązanych zadaniach. Ta konwencja sprawia, że poszczególne encje Features pozostają kompozycyjne, niezależnie wersjonowane i niezależnie dołączalne.
Rdzeniowy kompilator Go nie egzekwuje tej konwencji. Definicje Feature o mieszanych zadaniach są składniowo poprawne i kompilują się bez błędów. Egzekwowanie jest opcjonalne:
- Przedsiębiorstwa tworzące wewnętrzne katalogi mogą napisać własny plugin lintera, który sprawdza definicje Feature w CI/CD i ostrzega, gdy etykiety
appliesTopojedynczej encji Feature obejmują niepowiązane domeny funkcjonalne. - Autor encji Feature, który zapisze w
interoperability.conflictsWith, że dwie encje Features nakładałyby się na siebie, włącza sprawdzanie w czasie budowania: kompilator przerywa działanie wszędzie tam, gdzie obie trafiają do jednego komponentu. Porównuje on wyłącznie zadeklarowane nazwy, więc egzekwuje deklarację zapisaną przez autora, a nie samą konwencję czystości.
Encje Features otwartoźródłowej biblioteki standardowej przestrzegają konwencji czystości dzięki dyscyplinie autorskiej; katalogi przedsiębiorstw mogą od niej odstąpić, gdy ściśle powiązana złożona całość rzeczywiście pasuje do modelu wdrożenia.
Co zasługuje na Feature, a gdzie należy własne pokrętło produktu
Feature to dołączenie: wnosi coś, co programista lub operator dołącza świadomie — zasoby, krok potoku, okablowanie — a konwencja biblioteki standardowej mówi, że powinno dać się je respektować w co najmniej dwóch niezależnych produktach. Ta druga połowa jest testem, który należy zastosować przed jego utworzeniem, ponieważ przenośność jest tym, co obiecuje słowo dołączenie. Dołączenie oznacza, że możliwość daje się przenosić: można ją dołączyć do jednego komponentu, dołączyć do innego, a realizacja w każdym produkcie respektuje ją na jego własnych warunkach.
Możliwość, którą ma tylko jeden produkt w tej dziedzinie, jest własnym pokrętłem tego produktu, a nie encją Feature. Jej miejsce to wartość tworzona na własnej powierzchni tego produktu, którą autor podejmujący decyzję ustawia w swoim filarze i czyta obok wszystkiego innego, co konfiguruje ten sam produkt. Opublikowanie jej zamiast tego jako Feature oferuje przenośność, której żaden inny produkt nie zapewni: dołączenie z samej konstrukcji wskazuje jeden produkt, więc autor, który dołączy je do kolejnego wybranego produktu, napotka build zatrzymujący się z podaniem typu, a Feature nauczy możliwości, której nigdy nie miało.
Test liczy produkty w dziedzinie, a nie komponenty w tym katalogu, każdy odczytany z jego własnej aktualnej dokumentacji konfiguracji. Dwa niezależne produkty implementujące daną możliwość czynią ją przenośną niezależnie od tego, ile z nich jest tu dostarczanych, więc Feature można zadeklarować, zanim cokolwiek w katalogu je zrealizuje — jego dołączenie zatrzymuje wtedy build z podaniem typu — a każda dostarczona realizacja to FeatureRecipe dla jednego produktu, respektująca dołączenie w taki sposób, w jaki ten produkt je konfiguruje.
Przypinanie certyfikatów upstreamu to przykład praktyczny. Przypięcie (pin) to kontrola nad tym, jaki klucz może przedstawić upstream: akceptowany jest tylko certyfikat, którego klucz publiczny pasuje do klucza dostarczonego przez Release. To inne stwierdzenie niż wymaganie, by certyfikat upstreamu prowadził łańcuchem do kotwicy zaufania dostarczonej przez Release, i jeszcze inne niż stwierdzanie, co mówi podmiot certyfikatu — oba te stwierdzenia określają, co certyfikat musi mówić, podczas gdy przypięcie określa, jakim kluczem musi być. Kilka tutejszych bram potrafi weryfikować względem kotwicy, dlatego dataplane.aggrega.ai/upstream-tls: trust-anchor jest wartością, do której może pasować selektor. Przypinanie to odrębna możliwość i co najmniej dwa niezależne produkty implementują ją dla połączeń, które otwierają do upstreamu: Tyk przyjmuje klucz publiczny upstreamu w formacie PEM, a Envoy przyjmuje jego skrót. Jest to więc Feature, core/upstream-key-pinning, którego selektor wskazuje dataplane.aggrega.ai/upstream-pinning: public-key, a to, co realizuje ten katalog, rozstrzyga się produkt po produkcie: core/gateway/tyk ma tę wartość i FeatureRecipe dla każdego ze swoich celów, natomiast tutejsze bramy osadzające Envoy udostępniają jego ustawienie przypięcia tylko dla certyfikatów przedstawianych przez klientów albo wcale, więc nie mają tej wartości, a dołączenie do nich zatrzymuje się na selektorze. Przypięcie zawęża to, co upstream może przedstawić; jest kontrolą, a nie gwarancją, że połączenie jest poza tym poprawne.
Dwa ograniczenia testu, przy czym drugie jest tą połową, którą najłatwiej pominąć:
- To dyscyplina autorska, a nie sprawdzenie kompilatora. Feature deklarujące opcje, których nie implementuje żaden produkt, przechodzi zarówno walidację schematu, linter publikacji, jak i renderowanie — kompilator nie interpretuje tego, co Feature obiecuje. Ocena należy do autora katalogu.
- Niezdolność jednego produktu do respektowania opcji nie jest powodem do jej usunięcia. Gdy dwa lub więcej produktów dostarcza możliwość pod nazwami, które dają się zgrupować, możliwość jest przenośna i Feature ją zachowuje; produkt, który nie może jej respektować, odrzuca ją. Feature okrojone do tego, co obsługuje każdy produkt, nie ma prawie nic do powiedzenia.
Zakres encji Feature i kształt jej definiowania
Pole spec.schema encji Feature definiuje własne kształty encji Feature values: i infra: — intencję poznawczą, którą Developer konfiguruje dla każdego dołączenia encji Feature w encji Aggregate (values), odrębną od liczb pojemności, o których Operator decyduje dla każdego środowiska (infra). Filary encji Feature żyją we własnych przestrzeniach nazw i są walidowane niezależnie od filarów encji Component, która ją hostuje. Gdy Developer dołącza encję Feature autoscaler do encji Component web-server w encji Aggregate, encja Aggregate zawiera values: encji Component (kształt hosta) oraz values: encji Feature (kształt intencji skalowania — która metryka steruje skalowaniem); liczby pojemności przeznaczone dla operatora (min_replicas / max_replicas) przepływają przez blok infra: encji Release przy dołączeniu encji Feature.
# 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: 10Pole schema: encji Feature waliduje własne bloki values: i infra: dołączenia encji Feature. Pole schema: encji Component waliduje własne bloki encji Component. Oba są oceniane niezależnie na etapie analizy statycznej; filar dołączenia niezgodny z schema: encji Feature zatrzymuje kompilację błędem przypisanym do miejsca dołączenia encji Feature, a nie do hostującej encji Component. Walidowana jest efektywna konfiguracja dołączenia — wynik złożenia wszystkich zakresów, które ją konfigurowały — więc wartość doprowadzona do zgodności w jednym zakresie, a następnie nadpisana czymś niedozwolonym w węższym, zostanie wychwycona.
Zadeklarowane wartości domyślne materializują się w renderowanych filarach dołączenia. Poza walidacją default: zadeklarowane w polu values lub infra encji Feature jest w czasie kompilacji wpisywane do renderowanego filaru tego dołączenia dla każdego klucza, którego nikt nie zdefiniował — dzięki temu szablon encji FeatureRecipe odczytujący {{ .infra.tier }} otrzymuje wartość zadeklarowaną w schemacie zamiast pustej. Wartości podane przez autora zawsze wygrywają, a wartość domyślna uzupełnia tylko pominięte przez nie klucze: dołączenie, które definiuje jeden klucz schematu encji Feature, nadal otrzymuje zadeklarowane wartości domyślne dla pozostałych kluczy tego schematu, a częściowo zdefiniowany obiekt zagnieżdżony zachowuje to, co zapisano, i zyskuje niezapisane elementy sąsiednie.
Podczas definiowania warto znać trzy właściwości tego uzupełniania:
- Wartość domyślna nigdy nie wypiera wartości podanej w jakimkolwiek zakresie. Gdy encja Feature jest dołączona w więcej niż jednym zakresie — na przykład na granicy encji Release i w jednym z jej komponentów — obowiązuje wartość węższego zakresu, a wartość domyślna uzupełnia tylko to, czego nie zapisał żaden zakres.
- Wartość domyślna uzupełnia dołączenie; nigdy go nie tworzy. Deklarowanie wartości domyślnych w encji Feature, której nic nie dołącza, nie wnosi niczego do wyniku, więc schemat encji Feature nie może dodać konfiguracji, o którą nie prosił żaden autor.
- Dołączenie zadeklarowane na granicy encji Release, a nie w pojedynczym komponencie, uzupełnia tylko
infra, ponieważ ta powierzchnia nie ma blokuvalues:do uzupełnienia.
Ponieważ materializacja korzysta z tego samego rozwiązywania schematu co walidacja, wartość domyślna zadeklarowana w nadrzędnej encji Feature dociera do dołączeń potomka extends:, a wartości domyślne osiągane przez międzydokumentowe $ref: do encji SchemaLibrary również się materializują. Wartości domyślne zadeklarowane wyłącznie w lokalnym odwołaniu wewnątrzdokumentowym #/$defs/ lub w gałęzi allOf / oneOf / anyOf nie są materializowane.
Jedną konsekwencję warto wyraźnie zaznaczyć, ponieważ sama walidacja jej nie ujawni: pole required:, które ma również default:, jest spełnione przez tę wartość domyślną, więc jego pominięcie jest dozwolone — a wartość, na podstawie której sprawdzenie przeszło, jest wartością zawartą w renderowanym wyniku.
Kontekst szablonów kompilatora udostępnia stan instancji encji Feature powiązanej encji FeatureRecipe przez pole .features.<alias> (zawierające .type, .resolved_version, .labels, .values, .infra i .provides dla każdego dołączenia). Szablony wewnątrz encji FeatureRecipe odczytują własne values: encji Feature przez .values.<field> we własnym zakresie szablonów encji FeatureRecipe; values: hostującej encji Component nie są bezpośrednio widoczne dla szablonów encji FeatureRecipe, chyba że encja Feature jawnie zadeklaruje gniazdo uses: do hostującej encji Component.
To rozdzielenie zakresów sprawia, że Features są składalne: encja Feature autoscaler nie zależy od tego, do której encji Component jest dołączona; jej schema: opisuje intencję autoskalowania niezależnie od hosta. values: hostującej encji Component są sprawą hosta; values: encji Feature są sprawą encji Feature; oba filary składają się bez przenikania nazw pól przez granicę.
Cele powiązań adnotacji
Feature nie deklaruje powiązań adnotacji samodzielnie; przenosi je mapa mappings.features.annotations w encji Manifest. Feature uczestniczy w relacji powiązania pośrednio, jako cel routingu: każde powiązanie wskazuje typ encji Feature za pomocą pola feature:, a listy maps.infra i maps.values powiązania deklarują ścieżki kropkowe do właściwości spec.schema.infra.<path> i spec.schema.values.<path> wskazanej encji Feature.
Podczas ładowania katalogu kompilator sprawdza, czy każda ścieżka kropkowa na listach maps powiązania odpowiada właściwości, którą spec.schema docelowej encji Feature faktycznie deklaruje we wskazanym filarze. Powiązanie kierujące do ścieżki, której schemat encji Feature nie deklaruje, zatrzymuje ładowanie katalogu z czytelnym błędem OPS_ERROR, wskazującym powiązanie, docelową encję Feature oraz filar i ścieżkę, przez które nastąpiło kierowanie — powiązanie jest zapisane w encji Manifest, która jest dokumentem operatora. Autorzy schematów wiedzą zatem, że każda właściwość zadeklarowana pod spec.schema.values.<path> lub spec.schema.infra.<path> jest osiągalna jako cel powiązania; i odwrotnie, każda właściwość, przez którą kieruje powiązanie w encji Manifest, musi istnieć w schemacie docelowej encji Feature.
Gdy adnotacja po stronie encji Aggregate lub Release pasuje do powiązania, kompilator syntetyzuje dołączenie encji Feature, którego ładunki filarów kierują wartość adnotacji do wskazanych ścieżek. Zsyntetyzowane dołączenie jest strukturalnie nieodróżnialne od jawnego dołączenia encji Feature zadeklarowanego przez autora w tym samym miejscu; dalsze renderowanie, walidacja i kontekst szablonu FeatureRecipe obsługują oba kształty jednakowo. Kształt powiązania, podział na strony i filary oraz zasadę pierwszeństwa jawnego dołączenia opisuje entities/manifest.md §„Annotation-Driven Feature Bindings”. Regułę kaskady po stronie encji Aggregate i przykład tworzenia opisuje providers/well-known-annotations.md §„Aggregate-side annotation cascade”.
Blok assertions:
Feature.spec.assertions: to opcjonalna mapa nazwanych reguł wyrażających niezmienniki architektoniczne kontraktu encji Feature — reguły międzypolowe dotyczące pola values: encji Feature oraz rozwiązanego stanu dołączonej encji Component. Każdy klucz jest identyfikatorem reguły, który pojawia się w komunikacie o błędzie; każda wartość jest treścią szablonu Go. Kompilator ewaluuje je po walidacji schematu, a przed renderowaniem powiązanej encji FeatureRecipe, w kolejności, w jakiej zostały zapisane, a pierwsza niespełniona reguła zatrzymuje kompilację z własnym komunikatem o błędzie tej reguły.
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 -}}Podobnie jak asercje encji Component, asercje encji Feature wyrażają niezmienniki na poziomie kontraktu — właściwości, które dołączenie encji Feature musi spełniać niezależnie od tego, która encja FeatureRecipe realizuje renderowanie. W przypadku reguł międzypolowych zależnych od konkretnej implementacji (wymaganie pluginu Wasm, osobliwość chartu) należy zamiast tego użyć pola assertions: encji FeatureRecipe. Pełna gramatyka tworzenia, kontekst szablonu oraz podział odpowiedzialności między asercjami encji Feature i FeatureRecipe są opisane w templates/assertions-block.md.