Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Dobrze znane adnotacje

Encje Providers odczytują określone adnotacje, aby skonfigurować kontekst specyficzny dla platformy — ustawione na granicy encji Release lub we wpisie komponentu encji Release albo zadeklarowane w encji Aggregate na podsystemie lub instancji komponentu. Sam kompilator jest agnostyczny wobec wartości tych adnotacji — przekazuje je dalej jako nieprzezroczyste ciągi znaków. Każdy provider deklaruje, które adnotacje odczytuje, w jakim zakresie i jaka wartość domyślna obowiązuje, gdy adnotacji brak. Ta deklaracja znajduje się w polu spec.provider.wellKnownAnnotations encji Plugin renderującej przez providera i jest celowo wąska: provider wymienia klucz tylko tam, gdzie go odczytuje. Provider, który nie odczytuje żadnej z nich, deklaruje zamiast tego spec.provider.readsNoWellKnownAnnotations: true.

Macierz obsługi w tym rozdziale jest generowana z tych deklaracji, z taką szczegółowością, jaką niesie deklaracja — dla każdego dostawcy dla każdego rodzaju wejścia, ponieważ dostawca może odczytywać klucz, gdy syntetyzuje jednostkę wdrożeniową, i nie mieć możliwości odczytania go, gdy renderuje dostarczony artefakt. Należy tworzyć definicje w oparciu o tę macierz: komórka mówi, co dany dostawca odczytuje na danej ścieżce, ponieważ komórka nie może powiedzieć niczego, czego dostawca nie zadeklarował. Deklaracja wymieniająca rodzaj wejścia, którego własny kontrakt zachowania renderowania dostawcy nie renderuje, jest odrzucana przy odczycie encji Plugin, więc te dwa twierdzenia nie mogą być ze sobą sprzeczne.

Zarezerwowane słownictwo to szerszy zbiór i znajduje się zamiast tego w dwóch miejscach — w tym rozdziale, który wymienia każdy zarezerwowany klucz, w tym te, których żaden dostawca nie odczytuje, oraz w zbiorze zarezerwowanych prefiksów sprawdzanym przez lint publikacji.

Niezmienniki

  1. Kompilator nigdy nie interpretuje ani nie waliduje wartości dobrze znanej adnotacji providera: przenosi klucz i jego wartość przez kaskadę i ostrzega tam, gdzie cel nie działa na podstawie tego klucza.
  2. Każdy dostawca dokumentuje, które adnotacje odczytuje i jakie wartości domyślne stosuje.
  3. Adnotacje obowiązują jednolicie w obrębie granicy. Jeśli wartość różni się w zależności od komponentu, należy ją umieścić w adnotacjach na poziomie komponentu (nadpisujących adnotacje granicy) lub w infra komponentu.
  4. Dobrze znane adnotacje Provider nigdy nie powielają etykiet Component. Etykiety Component opisują, czym jest komponent. Adnotacje granicy opisują, gdzie komponent jest wdrażany.
  5. Encje Recipes nie obsługują dobrze znanych adnotacji dostawców. Dostawca stosuje kontekst rozmieszczenia (przestrzeń nazw, prefiks rejestru, konto usługi) automatycznie, po tym jak encja Recipe wytworzy swoją treść.
  6. Prefiks aggrega.ai/ jest zarezerwowany dla biblioteki standardowej. Własne adnotacje przedsiębiorstwa używają własnego prefiksu.
  7. Adnotacje na poziomie Component w encji Release nadpisują adnotacje na poziomie granicy (głębokie scalanie, wygrywa komponent). Tam, gdzie provider składa dane wyjściowe kilku granic w jeden artefakt, może wymagać, aby adnotacja rozwiązywała się jednakowo we wszystkich z nich — provider helm-chart pobiera nazwę chartu nadrzędnego z aggrega.ai/chart-name, a gdy więcej niż jedna granica współtworzy ten sam chart i rozwiązuje tę adnotację do różnych wartości, kompilacja zostaje zatrzymana z podaniem niezgodnych granic, ponieważ jeden chart nie może nosić dwóch nazw.
  8. Adnotacje deklarowane przez encję Aggregate trafiają do tych samych kluczy, z niższym priorytetem niż adnotacje encji Release. Klucz zadeklarowany na podsystemie lub na instancji komponentu — w samej encji Aggregate albo w module, który ona importuje, gdzie dociera do własnych komponentów modułu — obowiązuje dla komponentu wszędzie tam, gdzie encja Release nie ustawia wartości dla tego klucza; gdy encja Release ją ustawia, na granicy lub we wpisie komponentu, stosowana jest wartość encji Release. Własne adnotacje encji katalogu nigdy jej nie ustawiają. aggrega.ai/chart-name jest wyjątkiem od zasięgu encji Aggregate: nazywa złożenie, a nie komponent, i jest odczytywany z granic encji Release, które wnoszą do niego wkład.

Pełna macierz adnotacji

Jak czytać tę macierz

Sześć poniższych tabel kategorii wymienia każdą adnotację z zarezerwowanego słownika aggrega.ai/, to, czym steruje, oraz to, co robi provider, gdy jej brak. To, czy dany provider stosuje dany klucz, jest kwestią bardziej szczegółową, ponieważ provider renderuje więcej niż jeden rodzaj wejścia — dostarczony artefakt (sourced), encję Workload syntetyzowaną przez samego providera (synthesized) lub artifacts: encji Recipe jako całe wyjście węzła (artifacts-only) — a klucz może być odczytywany na jednej z tych ścieżek, będąc jednocześnie nieosiągalnym na innej. To, który provider renderuje który rodzaj wejścia, opisano w ../../architecture/16-recipe-input-composition.md; to, co każdy z nich stosuje, opisuje sekcja Obsługa według providera i rodzaju wejścia poniżej, która jest wiążącym opisem na tej stronie.

Każda komórka tej siatki ma jeden z trzech poziomów:

  • Stosowany — provider stosuje klucz dla tego rodzaju wejścia, a renderowane wyjście zmienia się w wyniku tego deterministycznie.
  • Stosowany warunkowo — kompilator emituje addytywne nadpisanie obok docelowego artefaktu zamiast edytować artefakt, więc to, czy wartość zadziała, zależy od tego, czy artefakt udostępnia własny pasujący klucz. W praktyce skuteczne, nigdy gwarantowane. Żaden provider nie implementuje komórki warunkowej, a powierzchnia deklaracji nie ma sposobu, by ją wyrazić, więc generowana poniżej siatka emituje tylko dwa pozostałe poziomy. Poziom ten jest nazwany, ponieważ taka ścieżka rzeczywiście istnieje dla dostarczonego artefaktu, a słownik dwupoziomowy zmusiłby macierz albo do deklarowania gwarancji, której nie może dać, albo do zaprzeczenia, że ścieżka w ogóle istnieje.
  • Niestosowany — żaden provider nie stosuje klucza na tej ścieżce: cel nie ma tam dla niego miejsca renderowania, więc mechanizm rozmieszczenia nie wnosi nic do tego, co jest renderowane, a kolumna Domyślnie tabeli kategorii mówi, co otrzymuje się w zamian. Wartość nadal przechodzi przez build jako nieprzezroczysty ciąg znaków, nienaruszona. Poziom jest nazwany od mechanizmu, a nie od losu wartości, ponieważ są to różne pytania i tylko na pierwsze komórka może odpowiedzieć: to, co provider stosuje, jest właściwością miejsc renderowania danego celu, a to właśnie stwierdza deklaracja stojąca za każdą komórką.

Istnieją dwa zakresy i tylko w jednym z nich rodzaj wejścia jest sensowną osią:

  • Zakres węzła — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account i aggrega.ai/kubernetes-version kształtują własne renderowane wyjście jednego komponentu, wytwarzane przez ścieżkę wybraną przez jego rodzaj wejścia. To są kolumny siatki.
  • Zakres złożenia i referencji — aggrega.ai/chart-name jest rozwiązywany raz, gdy składany jest chart parasolowy, a trzy klucze aggrega.ai/aws-* są rozwiązywane, gdy referencja przekracza granicę. Dla żadnego z nich rodzaj wejścia nie jest osią: wartość jest odczytywana przy złożeniu lub przy referencji, niezależnie od tego, jak wyrenderowano każdy współtworzący węzeł. Mają własną tabelę w sekcji Klucze rozwiązywane dla złożenia i dla referencji.

Kategoria 1 — Rozmieszczenie

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/namespacehelm (sourced, synthesized); compose (sourced, synthesized)Przestrzeń nazw Kubernetes (helm); nazwa sieci Docker (compose)Niewstrzykiwana w razie braku (helm); sieć nazwana od ścieżki pliku compose, współdzielona przez każdy węzeł tego pliku bez adnotacji (compose)
aggrega.ai/project-namezarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla nazwy projektu Docker Compose—
aggrega.ai/regionzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla regionu chmury w zakresie rozmieszczenia—
aggrega.ai/account-idzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla identyfikatora konta chmurowego w zakresie rozmieszczenia—
aggrega.ai/kubernetes-versionhelm (sourced)Wersja Kubernetes klastra, w którym wdrażany jest komponent, odczytywana przez chart renderowany ze źródła jako .Capabilities.KubeVersionWersja, dla której renderuje standardowe helm template tego samego wydania helm: wersja biblioteki klienckiej Kubernetes, z którą zbudowano providera

aggrega.ai/namespace jest z założenia dwuzadaniowa. Wyraża tę samą intencję logicznej izolacji — „zasoby tej granicy żyją we własnym adresowalnym zakresie” — w natywnej formie każdego celu: jako metadata.namespace Kubernetes dla helm i jako nazwę sieci Docker dla compose. Autorzy encji Recipe ustawiają jedną adnotację; każdy provider materializuje ją odpowiednio dla celu. W przypadku compose nazwa sieci jest rozwiązywana dla każdego węzła z adnotacji na tym węźle, a gdy węzeł nie ma adnotacji, używana jest ścieżka pliku compose — więc granice bez adnotacji, które współdzielą jeden plik compose, współdzielą jedną sieć, a rozdziela je właśnie aggrega.ai/namespace. Niezależnie od tego, które z nich dostarcza tożsamość, jest ona następnie zapisywana znakami akceptowanymi w nazwie sieci compose — każdy inny znak jest zapisywany jako sekwencja ucieczki, a nie zastępowany, więc dwie tożsamości różniące się czymkolwiek pozostają w dwóch sieciach, a wielkość liter tożsamości zostaje zachowana tak, jak ją zapisano. Dokumentacja providera compose opisuje wyprowadzanie w całości, w tym jak odczytać zakodowaną nazwę i ile kosztuje zmiana nazwy.

aggrega.ai/kubernetes-version określa właściwość klastra, w którym wdrażany jest komponent, a nie miejsce, w którym komponent w nim ląduje: szablony chartów wybierają wersję API, pole lub cały mechanizm według wersji, dla której są renderowane, a build nie ma klastra, którego mógłby zapytać. Provider helm odczytuje wartość tak, jak helm template --kube-version odczytuje swoją flagę, i zatrzymuje build przy wartości, która nie jest wersją; gdy żadnej nie podano, chart renderuje się dla wersji, dla której renderuje helm template tego samego wydania helm. Dokumentacja providera helm opisuje akceptowane formy i wartość domyślną.

Kategoria 2 — Rejestr

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/image-registryhelm, compose — tylko synthesizedPrefiks rejestru dla obrazów kontenerów, stosowany do każdej referencji do syntetyzowanego obrazu konteneraBrak prefiksu
aggrega.ai/image-pull-secrethelm — tylko synthesizedNazwa imagePullSecrets Kubernetes, łączona z istniejącymi wpisami syntetyzowanego podaBrak

Kategoria 3 — Sieć

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/cluster-domainzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla sufiksu DNS do wykrywania usług między przestrzeniami nazw—
aggrega.ai/ingress-classzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla IngressClass Kubernetes w zasobach Ingress—
aggrega.ai/service-meshzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla adnotacji wstrzykiwania sidecara siatki usług—

Kategoria 4 — Bezpieczeństwo

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/service-accounthelm — tylko synthesizedServiceAccount Kubernetes dla syntetyzowanych podów; nadpisuje workload.serviceAccount encji Recipe, gdy ustawiono obaworkload.serviceAccount encji Recipe lub brak ustawienia, gdy encja Recipe go nie deklaruje
aggrega.ai/pod-security-standardzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla poziomu Pod Security Standards—
aggrega.ai/iam-rolezarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla roli tożsamości chmurowej powiązanej z obciążeniem—

Kategoria 5 — Pakowanie

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/chart-namehelm-chart — dla złożeniaNazwa chartu parasolowegoNazwa encji Aggregate połączona ze ścieżką zestawienia wykresu parasolowego — zob. Rozwiązywanie nazwy wykresu
aggrega.ai/chart-versionzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla wersji chartu Helm—
aggrega.ai/stack-namezarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla jawnie nazwanego stosu—
aggrega.ai/tf-backendzarezerwowana; żaden provider jej nie odczytujeZarezerwowana dla identyfikatora backendu stanu Terraform—

Kategoria 6 — Docelowa chmura

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/aws-accountcloudformation — dla każdego odwołania przekraczającego granicęKonto AWS, w którym wdrażany jest stos (granica)To samo konto — odwołanie między stosami jest rozwiązywane przez import eksportu stosu w obrębie tego samego konta
aggrega.ai/aws-regioncloudformation — dla każdego odwołania przekraczającego granicęRegion AWS, w którym wdrażany jest stos (granica)Ten sam region — odwołanie między stosami jest rozwiązywane przez import eksportu stosu w obrębie tego samego regionu
aggrega.ai/aws-assume-role-arncloudformation — dla każdego odwołania przekraczającego granicęARN roli IAM przyjmowanej przez odczyt stosu między kontami w celu dotarcia do wartości eksportowanych przez stos równorzędnyPrzy odwołaniu między kontami nie jest dostarczana żadna rola

Każda granica CloudFormation jest renderowana do jednego stosu. Gdy krawędź uses przechodzi z jednej granicy do innej, provider cloudformation musi wiedzieć, gdzie znajduje się stos równorzędny, aby ukształtować odwołanie: dwa stosy w tym samym koncie i regionie wymieniają wartości przez eksport i import stosu; stos równorzędny w innym koncie lub regionie wymaga odczytu wyjść stosu między kontami, opcjonalnie z przyjęciem roli. Te adnotacje niosą ten kontekst rozmieszczenia. Każda z nich jest odczytywana w chwili, gdy provider kształtuje takie odwołanie, i rozwiązywana w tej chwili przez zwykłą kaskadę adnotacji — wartość ustawiona na komponencie ma pierwszeństwo przed wartością ustawioną na granicy, a wartość ustawiona przez encję Release ma pierwszeństwo przed wartością zadeklarowaną przez encję Aggregate. Wartość na poziomie granicy jest więc typowym sposobem ich wyrażenia, ale nie jedynym. Są to nieprzezroczyste skalarne ciągi wskaźnikowe — provider przekazuje je do budowanego odwołania i nigdy nie rozwiązuje ich względem bieżącego stanu AWS; konto, region i rolę dostarcza encja Release lub deklaruje encja Aggregate, a ostateczny fizyczny odczyt rozwiązuje środowisko uruchomieniowe. Gdy brak wszystkich adnotacji, provider traktuje stos równorzędny jako znajdujący się w tym samym koncie i regionie i nie dostarcza żadnej roli.

Obsługa według providera i rodzaju wejścia

Klucze o zasięgu węzła, dla każdego providera i każdego rodzaju wejścia. Nagłówki kolumn pomijają prefiks aggrega.ai/, który ma każdy klucz. applied i — oznaczają poziomy zdefiniowane powyżej, przy czym — to niestosowany; n/a oznacza, że provider w ogóle nie renderuje danego rodzaju wejścia, więc nie istnieje tam ścieżka, na której klucz mógłby zostać zastosowany lub pominięty.

ProviderRodzaj wejścianamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Każdy provider dystrybuowany z kompilatorem ma tu wiersze, także taki, który nie odczytuje żadnej adnotacji rozmieszczenia — pusty zestaw wierszy byłby nieodróżnialny od providera, którego nikt jeszcze nie opisał. Provider dostarczany osobno deklaruje to, co odczytuje, w ten sam sposób i nie jest tu wymieniony, ponieważ opublikowana strona nie może wyliczyć providerów, których nigdy nie widziała.

Encja Recipe może deklarować jednocześnie więcej niż jeden rodzaj wejścia — na przykład workload: wraz z artifacts:. Siatkę należy czytać dla każdego rodzaju osobno: syntetyzowane wyjście takiego węzła odpowiada wierszowi synthesized, a jego pliki artefaktów — przypadkowi artefaktów. Wiersz artifacts-only to rodzaj wejścia, w którym encja Recipe deklaruje artifacts: i nic więcej.

Nie trzeba sprawdzać siatki, aby się tego dowiedzieć. Ustawienie klucza, którego cel danego renderowania nie odczytuje na żadnym z rodzajów wejścia tego renderowania, powoduje ostrzeżenie wskazujące klucz, cel i każdy rodzaj wejścia deklarowany przez to renderowanie, więc komórka, w której znalazło się przypadkiem, ujawnia się w chwili budowania, zamiast czekać, aż ktoś pomyśli o zajrzeniu tutaj:

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

W przypadku renderowania deklarującego więcej niż jeden rodzaj wejścia ostrzeżenie dotyczy tego renderowania jako całości, a nie jednej z jego połówek. Ponieważ rodzaje składają się przez dodawanie, cel odczytujący klucz na którymkolwiek z nich faktycznie go stosuje, a wyjście tego renderowania zawiera wynik — więc ostrzeżenie nie jest zgłaszane. Ostrzeżenie pojawia się tylko wtedy, gdy klucz pomija każdy rodzaj deklarowany przez to renderowanie, i wymienia je wszystkie:

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

Zatem workload: obok source: wystarcza, aby aggrega.ai/service-account zadziałał na tym węźle, a budowanie nic o tym nie zgłasza — co jest rzetelnym raportem, ponieważ wartość dociera do syntetyzowanej połówki i pojawia się w emitowanych manifestach.

Siatkę należy czytać dla każdego renderowania, a nie dla każdego komponentu. Funkcja dołączona do węzła generuje swoje zasoby przez cel wskazany przez jej własną encję FeatureRecipe, w rodzajach wejścia deklarowanych przez tę encję FeatureRecipe — trafia więc do własnego wiersza tej siatki, który nie musi być wierszem komponentu-gospodarza. Komponent syntetyzujący swój Workload, podczas gdy dołączona funkcja dostarcza obok niego artifacts:, odczytuje wiersz synthesized dla własnych manifestów komponentu i wiersz artifacts-only dla plików dołączenia, a klucz stosowany w pierwszym może zostać pominięty w drugim. Ostrzeżenie podlega temu samemu podziałowi i informuje o każdym z nich osobno, ponieważ są to różne pliki. Funkcja dołączona do granicy, a nie do nazwanego komponentu, odczytuje siatkę w ten sam sposób.

Wartość nadal przechodzi nietknięta — budowanie nie zostaje przerwane, ponieważ granica obejmująca komponenty na heterogenicznych celach zawsze będzie miała jakieś renderowanie, które nie może obsłużyć danego klucza, a jest to zwykła encja Release, a nie błąd. Adnotacja granicy podlega kaskadzie, więc jedna napisana linia daje jedno ostrzeżenie na każde renderowanie, które nie może jej obsłużyć — dzięki temu widać, które części wyjścia są objęte. Należy ono do klasy unsupported-field i jest wyciszane flagą tej klasy; szczegóły zawiera strona Ostrzeżenia. Warto znać dwa ograniczenia: sprawdzane są tylko gołe klucze aggrega.ai/, ponieważ klucz z podprefiksem to własne słownictwo autora, a provider, który nie deklaruje żadnej obsługi, nie generuje ostrzeżeń, ponieważ nie ma z czym porównać tego, co napisano. Provider deklarujący, że nie odczytuje żadnego z tych kluczy, nie milczy w ten sposób: readsNoWellKnownAnnotations: true w jego encji Plugin to deklaracja nieobejmująca żadnego klucza, więc każdy goły klucz docierający do jednego z jego renderowań wywołuje ostrzeżenie. Deklaruje to provider terraform.

Dlaczego dostarczony artefakt stosuje mniej kluczy. Adnotacja o zasięgu węzła jest stosowana tam, gdzie provider ma dla niej miejsce w renderowaniu. Gdy provider sam syntetyzuje jednostkę wdrożenia, jest właścicielem każdego pola wyniku, więc prefiks rejestru, sekret pobierania i konto usługi mają gdzie trafić. Dostarczony artefakt — chart Helm, plik compose, moduł Terraform — ma natomiast własny interfejs konfiguracji, a kompilator tego interfejsu nie odczytuje, więc nie może wiedzieć, któremu z własnych kluczy artefaktu odpowiadałby prefiks rejestru lub konto usługi. Rozmieszczenie kontrolowane przez otaczające wywołanie renderowania nadal jest stosowane, dlatego aggrega.ai/namespace jest stosowany do chartu renderowanego ze źródła. Rozmieszczenie, które wymagałoby decydowania, gdzie wewnątrz cudzego artefaktu należy umieścić wartość, nie jest stosowane, a autor dostarcza je przez własne wartości tego artefaktu. Dlatego wiersze sourced są rzadkie tam, gdzie wiersze synthesized są pełne, i takiego kształtu należy oczekiwać od każdego klucza dodanego później.

Klucze rozstrzygane dla każdego złożenia i każdej referencji

Cztery z dostarczanych kluczy nie mają zakresu węzła, dlatego znajdują się poza powyższą siatką, a nie zostały do niej włączone: rodzaj wejścia nie jest dla nich znaczącą osią, a nadanie każdemu z nich wiersza dla każdego rodzaju wejścia powtórzyłoby jedną komórkę trzy razy i sugerowałoby rozróżnienie, które nie istnieje. Każdy z nich deklaruje zakres granicy, a poniższa tabela jest generowana z tych deklaracji.

AdnotacjaStosowana przezPrzeznaczenieDomyślnie
aggrega.ai/chart-namehelm-chartNazwa złożonego parasolowego chartu Helm.Używane są nazwa encji Aggregate oraz ścieżka składania chartu parasolowego — jego katalog wyjściowy w dist/, np. boundaries/data/helm-chart — każda zakodowana, a następnie połączone.
aggrega.ai/aws-accountcloudformationKonto AWS, na którym wdrażany jest stos (granica). Referencja przekraczająca granicę odczytuje je, aby ustalić, czy stos równorzędny znajduje się na tym samym koncie.Stos równorzędny jest traktowany jako znajdujący się na tym samym koncie, a referencja między stosami jest rozstrzygana przez import eksportu stosu w obrębie tego samego konta zamiast odczytu wyjścia stosu z innego konta.
aggrega.ai/aws-regioncloudformationRegion AWS, w którym wdrażany jest stos (granica). Referencja przekraczająca granicę odczytuje go, aby ustalić, czy stos równorzędny znajduje się w tym samym regionie.Stos równorzędny jest traktowany jako znajdujący się w tym samym regionie, a referencja między stosami jest rozstrzygana przez import eksportu stosu w obrębie tego samego regionu.
aggrega.ai/aws-assume-role-arncloudformationARN roli IAM, którą przyjmuje odczyt stosu z innego konta, aby uzyskać dostęp do wartości wyeksportowanych przez stos równorzędny.Nie jest podawana żadna rola, a referencja między kontami nie zawiera przyjęcia roli (assume-role).

Kiedy każdy z nich jest rozstrzygany – tej informacji sama deklaracja nie zawiera. aggrega.ai/chart-name jest rozstrzygany raz dla każdego złożenia chartu parasolowego, na podstawie kaskady adnotacji granicy; każdy współtwórca jednego złożenia musi rozstrzygnąć go do tej samej wartości, a rozbieżność zatrzymuje kompilację z podaniem nazw granic. Trzy klucze aggrega.ai/aws-* są rozstrzygane dla każdej referencji przekraczającej granicę z pierwszeństwem komponentu przed granicą, więc wartość komponentu wygrywa z wartością granicy; Kategoria 6 powyżej opisuje referencję, którą kształtuje każdy z nich.

Zarezerwowane nazwy, których żaden provider nie odczytuje

Jedenaście kluczy w powyższej macierzy jest oznaczonych jako zarezerwowane; żaden provider ich nie odczytuje: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name oraz aggrega.ai/tf-backend.

Ustawienie jednego z nich w encji Release lub w encji Aggregate nie ma żadnego wpływu na renderowane wyjście. Żaden provider ich nie odczytuje i nie jest w ich imieniu stosowana żadna wartość domyślna – w szczególności dla aggrega.ai/cluster-domain nie jest stosowany żaden sufiks DNS, więc encja Recipe, która potrzebuje domeny klastra, musi podać ją jako zwykłą wartość, zamiast polegać na tej adnotacji. Autor encji Recipe, który potrzebuje jednego z tych zachowań, wyraża je jako wartość encji Recipe lub pole infra komponentu.

Żaden provider nie deklaruje tych jedenastu. wellKnownAnnotations providera wymienia tylko to, co odczytuje, więc żaden z jedenastu się tam nie pojawia – czytelnik otwierający encję Plugin helm, helm-chart, compose lub cloudformation widzi klucze, które działają, i nic poza nimi. Na tym polega sens wąskiej deklaracji: zadeklarowany klucz jest działającym kluczem, a zakres obok niego mówi, na jakiej ścieżce.

Dwie z zarezerwowanych nazw są bliskie działającym kluczom i nie są z nimi wymienne. aggrega.ai/region i aggrega.ai/account-id nazywają region i konto w zakresie rozmieszczenia i nie docierają do żadnego providera; klucze odczytywane przez provider cloudformation to przestrzennie powiązane z chmurą aggrega.ai/aws-region i aggrega.ai/aws-account z Kategorii 6. Gdy chodzi o kontekst rozmieszczenia między stosami CloudFormation, należy użyć formy aws- – para bez prefiksu jest zarezerwowana przed kolizją, a nie do czegokolwiek podłączona. Dwie kolejne zarezerwowane nazwy są obsługiwane przez inne mechanizmy niż adnotacja: aggrega.ai/stack-name jest zarezerwowany, natomiast nazwa stosu, do którego renderuje się granica cloudformation, jest wyprowadzana deterministycznie z tożsamości wydania i granicy; a rola tożsamości chmurowej obciążenia jest podawana jako zwykłe pole ustawiane przez operatora w encji Feature, która emituje powiązanie, a nie przez aggrega.ai/iam-role.

Nazwy pozostają zarezerwowane i pozostają wymienione tutaj, ponieważ prefiks aggrega.ai/ jest zarezerwowany: katalog przedsiębiorstwa nie może ponownie użyć żadnego z tych kluczy we własnym znaczeniu, ponieważ platforma utrzymuje ten klucz dla własnego znaczenia. Ta macierz i zbiór zarezerwowanych prefiksów sprawdzany przez lint publikacji tworzą razem rejestr rezerwacji, a oba są utrzymywane przy tym samym zbiorze nazw przez kontrolę, która odczytuje oba i kończy się niepowodzeniem, gdy się rozchodzą. Użycie jednego z jedenastu nie powoduje więc ani niepowodzenia walidacji, ani naruszenia reguły „nie używaj samego prefiksu aggrega.ai/” – po prostu nie ma żadnego efektu.

Wersja chartu parasolowego emitowana przez granicę helm-chart wynosi zawsze 0.1.0; jest to stała wartość, a nie wartość domyślna aggrega.ai/chart-version.

Uwaga: powiązania features.annotations w encji Manifest używające prefiksu aggrega.ai/ są odrzucane podczas wczytywania; prefiks jest zarezerwowany wyłącznie dla dobrze znanych adnotacji providerów opisanych w tym rozdziale. Autorzy powiązań encji Feature sterowanych adnotacjami używają feature.aggrega.ai/ dla skrótów biblioteki standardowej lub własnej domeny dla skrótów przedsiębiorstwa.

Uwaga: jawne null w adnotacji encji Release usuwa odziedziczone powiązanie z nadpisującej granicy lub komponentu (rezygnacja z encji Feature sterowanej adnotacjami). Sąsiednie komponenty w tej samej granicy, które nie zrezygnowały, zachowują odziedziczone powiązanie; nieobecne klucze nadal dziedziczą z nadrzędnej kaskady w zwykły sposób.

Adnotacje tworzone w katalogu, które odczytuje kompilator

Wszystko powyżej to adnotacje dostawcy: tworzone w encji Release lub deklarowane w encji Aggregate, przekazywane przez kompilator jako nieprzezroczysty ciąg znaków i odczytywane przez dostawcę. Drugi, znacznie mniejszy słownik działa w przeciwnym kierunku — tworzy go architekt we własnych metadata.annotations encji katalogu, odczytuje go kompilator, a dostawca nigdy go nie widzi. Niezmiennik 1 powyżej dotyczy słownika dostawców i nie obejmuje tych kluczy; kompilator odczytuje dokładnie klucze wymienione tutaj i żadne inne.

Te klucze znajdują się pod podprefiksem <scope>.aggrega.ai/, a nie pod samym prefiksem aggrega.ai/, więc leżą poza rejestrem rezerwacji, który zawiera powyższa macierz, i poza regułą zarezerwowanego prefiksu, którą lint publikacji stosuje do kluczy z samym prefiksem.

AdnotacjaTworzona wOdczytywana przezPrzeznaczenie
features.aggrega.ai/requiredType.<label>metadata.annotations encji Componentkompilator, na sfinalizowanym grafieDeklaruje wymóg obecności: każda instancja tej encji Component musi mieć co najmniej jedno przyłączenie, którego typ jest równy wartości adnotacji. <label> to wybrany przez autora sufiks, który nazywa wymóg w komunikacie diagnostycznym; nie jest nazwą slotu i nic się do niego nie odwołuje. Aby zadeklarować kilka wymogów, należy powtórzyć klucz z różnymi etykietami.

Wymóg spełnia przyłączenie na dowolnym poziomie — blok features: na poziomie komponentu lub podsystemu, blok na poziomie granicy lub komponentu w encji Release albo rozwinięcie sterowane adnotacjami — ponieważ sprawdzany jest końcowy zbiór przyłączeń instancji, a nie miejsce pochodzenia każdego przyłączenia. Niespełniony wymóg zatrzymuje kompilację z podaniem etykiety i wymaganego typu; wartość, która nie jest URI typu Feature, lub klucz bez etykiety po prefiksie zatrzymują kompilację z osobnym komunikatem diagnostycznym o błędnej deklaracji. Pełny opis tworzenia oraz tego, czym wymóg różni się od slotu featuresSchema, znajduje się w entities/component.md, w części „Presence mandates”.

Etykiety pochodzenia emitowane przez dostawców

Powyższe adnotacje trafiają do kompilacji — definiuje je encja Release lub encja Aggregate, a konsumują dostawcy. Providers emitują również równoległy zestaw etykiet wychodzących z kompilacji, dołączając je do renderowanego wyniku, aby narzędzia w dalszej części łańcucha mogły przypisać zasoby środowiska uruchomieniowego do treści katalogu, która je wytworzyła. Te etykiety pochodzenia nie są definiowane w encji Release; są wyprowadzane z własnego stanu kompilacji (tożsamość encji Recipe, ścieżka granicy, nazwa agregatu, środowisko, fala synchronizacji, wersja kompilatora) i emitowane przez dostawcę w czasie renderowania.

Zestaw emitowany przez providery, dołączany do każdego manifestu Kubernetes renderowanego przez provider helm, do każdego artefaktu ładowanego przez $import:, który provider helm-chart dodaje do podchartu, oraz do każdej usługi emitowanej przez compose — własne szablony podchartu helm-chart są kopiowane tak, jak napisał je ich autor, więc niosą to, co ten autor w nich zapisał:

EtykietaŹródłoEmisja
app.kubernetes.io/nameIdentyfikator węzła (lub, dla zasobu emitowanego przez encję FeatureRecipe, identyfikator wyprowadzony dla tego dołączenia — zob. niżej)Tylko helm i helm-chart — standardowa etykieta Kubernetes, nieemitowana w usługach compose
aggrega.ai/component-idIdentyfikator węzła (lub, dla zasobu emitowanego przez encję FeatureRecipe, identyfikator wyprowadzony dla tego dołączenia — zob. niżej)Wszyscy trzej dostawcy
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> wytwarzającej encji Recipe (lub wytwarzającej encji FeatureRecipe dla zasobów emitowanych przez FR)Wszyscy trzej dostawcy, gdy wytwarzająca encja ma ustawioną zarówno nazwę, jak i wersję; w helm i helm-chart jako adnotacja
aggrega.ai/boundary-pathŚcieżka granicy, do której skierowano komponentWszyscy trzej dostawcy, gdy ścieżka granicy nie jest pusta; w helm i helm-chart jako adnotacja
aggrega.ai/aggregate-namemetadata.name encji AggregateWszyscy trzej dostawcy, gdy wartość jest ustawiona
aggrega.ai/compiler-versionWersja kompilatora utrwalona w czasie kompilacjiWszyscy trzej dostawcy, gdy wartość jest ustawiona
aggrega.ai/providerProvider, który wyrenderował zasóbWszyscy trzej dostawcy
aggrega.ai/provider-versionWersja tego provideraWszyscy trzej dostawcy
aggrega.ai/environmentmetadata.environment encji ReleaseWszyscy trzej dostawcy — każda encja Release ją deklaruje
aggrega.ai/sync-waveLiczba całkowita syncWave dla danej granicyWszyscy trzej dostawcy, gdy wartość jest niezerowa; w helm i helm-chart jako adnotacja

Wartości aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider i aggrega.ai/provider-version pochodzą z ciągów znaków, których kompilacja nie podporządkowuje regułom Kubernetes dotyczącym wartości etykiet — encja Aggregate o nazwie imported/flow, środowisko o nazwie eu/prod, wersja (devel) kompilacji deweloperskiej. W helm i helm-chart każda z tych etykiet niesie swoją wartość w zapisanej postaci, gdy wartość jest już prawidłową wartością etykiety: litery, cyfry, -, _ i ., litera lub cyfra na obu końcach, najwyżej 63 znaki. W przeciwnym razie etykieta niesie wartość przepisaną do tej postaci — każdy inny znak zamienia się w -, ciągi - są scalane w jeden, końce są przycinane do litery lub cyfry, a wynik jest skracany do najwyżej 63 znaków — a dosłowna wartość jest dodawana jako adnotacja pod tym samym kluczem. Encja Aggregate o nazwie imported/flow otrzymuje zatem etykietę aggrega.ai/aggregate-name: imported-flow i adnotację aggrega.ai/aggregate-name: imported/flow; wartość bez żadnego znaku, który etykieta zachowuje, jest przenoszona wyłącznie przez adnotację. Selektor dopasowuje wartość etykiety w postaci, w jakiej pojawia się ona w wyrenderowanym wyniku, a narzędzia potrzebujące dokładnej nazwy odczytują adnotację, jeśli jest obecna. Compose, którego wartości etykiet nie podlegają ograniczeniom, niesie dosłowną wartość jako etykietę.

Uwagi o emisji dla poszczególnych dostawców

  • helm — etykiety trafiają do metadata.labels w każdym wyrenderowanym zasobie Kubernetes (Deployment, Service, PVC itd.), a klucze, których wartość etykiety nie może zawierać — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave oraz dosłowna wartość każdej etykiety przepisanej w sposób opisany powyżej — do metadata.annotations. Ścieżki trybu źródłowego (renderowanie Helm SDK z wstrzykiwaniem etykiet po renderowaniu), trybu syntetyzowanego (synteza obciążenia) i artifacts: dają ten sam zestaw.
  • helm-chart — te same etykiety i adnotacje trafiają na każdy artefakt ładowany przez $import:, który provider dodaje do templates/ podchartu. Własne szablony chartu źródłowego oraz artefakt z treścią inline umieszczony w katalogu głównym podchartu nie niosą żadnej z nich — zob. helm-chart.md.
  • compose — etykiety trafiają do services.<name>.labels w każdej emitowanej usłudze compose. Tryb źródłowy (wstrzykiwanie etykiet po scaleniu w scalonym dokumencie bazy + valuesMapping) i tryb syntetyzowany (synteza obciążenia bezpośrednio ustawiająca blok etykiet usługi) dają ten sam zestaw. Specyficzna dla Kubernetes etykieta app.kubernetes.io/name jest pomijana w wyniku compose.

Dla zasobów emitowanych przez encję FeatureRecipe wartość aggrega.ai/component-id jest budowana z dołączenia, a nie z nazwy komponentu-hosta — dla każdego sposobu, w jaki encja FeatureRecipe może dostarczyć te zasoby, dzięki czemu zasoby dołączenia nigdy nie są nieodróżnialne po etykiecie od własnych zasobów komponentu-hosta. To, czy od tej tożsamości pochodzą również nazwy tych zasobów, zależy od sposobu dostarczenia: obciążenie syntetyzowane przez Aggrega otrzymuje nazwę od tożsamości, natomiast wykres lub fragment dostarczony przez autora dołączenia zachowuje nazwę wydania Helm i prefiks pliku wyjściowego komponentu-hosta, ponieważ własne szablony autora są renderowane względem tej nazwy. Sposób składania wartości — dwa warianty początku, części i ich łączenie przez --, zapis znaku, którego etykieta nie może zawierać, skracanie wartości zbyt długiej dla celu oraz to, dla których nazw jest, a dla których nie jest podstawą — nie zależy od dostawcy, dlatego opisano go raz w vocabulary/labels-and-annotations.md, „Provenance labels emitted on rendered output”, zamiast powtarzać tutaj. Ta strona odpowiada za drugą połowę: gdzie w wyrenderowanym wyniku każdego dostawcy trafiają etykiety.

aggrega.ai/recipe-uri wskazuje na własne name:version encji FeatureRecipe, a nie na tożsamość konsumującej encji Recipe — narzędzia odczytujące tę etykietę w celu identyfikacji wytwarzającej encji otrzymują poprawne pochodzenie zarówno dla wyniku emitowanego przez komponent, jak i przez FR.

Adnotacje sync-wave

Opisany wyżej klucz aggrega.ai/sync-wave występuje w parze z adnotacją sync-wave, którą narzędzia downstream odczytują, aby ustalić kolejność tego, co stosują. W compose klucz jest etykietą, która udostępnia wartość fali dla zapytań z selektorami; w helm i helm-chart jest adnotacją, a sparowana adnotacja umieszcza tę wartość tam, gdzie dane narzędzie zgodnie z konwencją ją odczytuje.

AdnotacjaEmisjaOdczytywana przez
argocd.argoproj.io/sync-wavehelm — na każdym renderowanym przez siebie zasobie Kubernetes, oraz helm-chart — na każdym artefakcie ładowanym przez $import: — gdy syncWave w granicy, z której pochodzi, jest niezeroweKolejność sync-wave w ArgoCD
helm.sh/hook-weighttylko helm, na manifestach generowanych z szablonów chartu, które mają już adnotację helm.sh/hook, gdy syncWave jest niezeroweKolejność hook-weight w Helm w obrębie fazy hooka

Emisja helm.sh/hook-weight zależy od ścieżki

Subtelność, na którą warto zwrócić uwagę autorów chartów: helm.sh/hook-weight jest emitowana wyłącznie na manifestach renderowanych ścieżką szablonowania chartu — z katalogu templates/ chartu renderowanego przez Helm SDK. Manifests wytworzone ścieżką artefaktów — w providerze helm każdy wpis bloku artifacts: encji Recipe, treść inline lub ładowana przez $import:, a w helm-chart wpis ładowany przez $import: — niosą adnotację argocd.argoproj.io/sync-wave i pełny zestaw etykiet pochodzenia, ale nie otrzymują helm.sh/hook-weight — nawet gdy artefakt ma adnotację helm.sh/hook.

To rozróżnienie wynika ze struktury: helm.sh/hook i helm.sh/hook-weight to prymitywy porządkowania środowiska uruchomieniowego Helm, stosowane do zasobów hooków generowanych z szablonów chartu. Artefakty autora encji Recipe to dodatkowe zasoby deklarowane na warstwie Recipe; domyślnie nie uczestniczą w cyklu życia hooków Helm.

Jeśli zasób hooka wymaga kolejności hook-weight w Helm, należy utworzyć go jako szablon chartu w katalogu source: encji Recipe renderowanej przez provider helm, a nie jako wpis artifacts:; szablony podchartu helm-chart są kopiowane tak, jak zostały napisane, i nie otrzymują żadnej z tych adnotacji. Szablon chartu otrzyma zarówno argocd.argoproj.io/sync-wave, jak i helm.sh/hook-weight zgodne z wartością syncWave granicy, z której pochodzi.

Przykłady tworzenia

Rozmieszczenie i konfiguracja rejestru na poziomie granicy:

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

Nadpisanie dla pojedynczego komponentu (przy tym samym kluczu adnotacji komponent ma pierwszeństwo przed granicą):

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

Kaskada adnotacji po stronie Aggregate

Adnotacje występują także na powierzchni autorskiej encji Aggregate — w zakresie podsystemu (spec.subsystems.<name>.annotations) oraz w zakresie instancji komponentu (spec.subsystems.<name>.components.<name>.annotations lub spec.components.<name>.annotations dla komponentów najwyższego poziomu). Kaskada po stronie Aggregate przenosi adnotacje napisane przez dewelopera w dół drzewa podsystemów do zawartych komponentów.

Reguła kaskady

Adnotacja na poziomie podsystemu propaguje się do każdego zagnieżdżonego podsystemu i każdego zawartego komponentu w poddrzewie podsystemu. Adnotacje z bliższego poziomu nadpisują adnotacje z poziomu zewnętrznego z granularnością pojedynczego klucza: adnotacja na poziomie komponentu nadpisuje każdą odziedziczoną adnotację na poziomie podsystemu dla tego samego klucza, nie wpływając na sąsiednie klucze ani sąsiednie komponenty.

Klucz adnotacji w danym zakresie jest w jednym z trzech stanów:

  • Brak klucza — zakres nie deklaruje wartości dla tej adnotacji. Zagnieżdżone podsystemy i zawarte komponenty dziedziczą powiązanie z zakresu nadrzędnego.
  • Wartość tekstowa — zakres deklaruje wartość. Zagnieżdżone podsystemy i zawarte komponenty dziedziczą tę wartość, chyba że zadeklarują własną wartość lub z niej zrezygnują.
  • Jawne null w YAML — zakres usuwa ze swojego poddrzewa każde odziedziczone powiązanie dla tego klucza. Sąsiednie komponenty i sąsiednie podsystemy zachowują niezależne dziedziczenie; powiązanie traci tylko poddrzewo zakresu, który zrezygnował.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Adnotacje encji Provider zadeklarowane w encji Aggregate

Klucze z powyższej macierzy przechodzą kaskadowo także przez encję Aggregate, a dostawca stosuje to, co kaskada pozostawia na każdym komponencie. aggrega.ai/namespace podsystemu umieszcza każdy komponent znajdujący się pod nim; własna wartość instancji komponentu umieszcza zamiast tego ten komponent. Moduł importowany przez encję Aggregate ma własną kaskadę: jego podsystemy i instancje komponentów sięgają do własnych komponentów modułu, a nic, co deklaruje importująca encja Aggregate, nie sięga do wnętrza modułu.

Encja Release stoi wyżej niż encja Aggregate w przypadku każdego klucza. Tam, gdzie encja Release ustawia klucz dla komponentu — na jego granicy lub we własnym wpisie komponentu — stosowana jest wartość z encji Release; tam, gdzie nie ustawia żadnej, stosowana jest wartość z encji Aggregate. Obie strony nakładają się klucz po kluczu, więc encja Release, która ustawia tylko aggrega.ai/namespace, pozostawia w mocy aggrega.ai/image-registry zadeklarowane przez encję Aggregate.

Jawne null w encji Release wycofuje tylko własną wartość encji Release. Wpis komponentu zapisujący aggrega.ai/namespace: null usuwa przestrzeń nazw, którą przekazałaby mu granica w jego encji Release, a komponent przyjmuje wtedy wartość deklarowaną przez jego encję Aggregate — albo nie przyjmuje żadnej, jeśli encja Aggregate również żadnej nie deklaruje. Encja Release nie może usunąć wartości deklarowanej przez encję Aggregate; może jedynie ustawić nad nią własną.

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

aggrega.ai/chart-name to jedyny klucz poza tym zasięgiem: nazywa on chart typu umbrella złożony z kilku komponentów, więc jest odczytywany z granic encji Release, które współtworzą ten chart, nigdy z adnotacji komponentu.

Szablon encji Recipe lub FeatureRecipe odczytuje kubły adnotacji po nazwie — .context.annotations.aggregate, .context.annotations.release i .context.annotations.catalog przechowują każdy to, co zapisała dana strona — więc szablon, który odczytuje klucz umiejscowienia z jednego kubła, widzi wyłącznie wartość tej strony.

Podział na strony i filary

Niezmiennik „Aggregate jako powierzchnia autorska” ogranicza adnotacje po stronie Aggregate do filaru values. Powiązanie adnotacji w encji Manifest deklaruje ścieżki routingu w maps.infra (routing po stronie Release) albo w maps.values (routing po stronie Aggregate); adnotacja po stronie Aggregate, której powiązanie deklaruje tylko ścieżki maps.infra, zatrzymuje kompilację z czytelnym komunikatem diagnostycznym podającym klucz adnotacji, filar routingu i stronę autorską. Symetryczna reguła dotyczy strony Release: adnotacje po stronie Release mogą być kierowane tylko przez maps.infra; adnotacja po stronie Release dla powiązania obejmującego tylko values zgłasza analogiczny błąd. Każdy komunikat diagnostyczny jest przypisany do domeny dokumentu, w którym napisano wartość adnotacji — [DEVELOPER_ERROR] dla encji Aggregate, [OPS_ERROR] dla encji Release — dzięki czemu nagłówek wskazuje powierzchnię, którą należy otworzyć.

Powiązania deklarujące ścieżki w obu filarach kierują w każdym przebiegu podzbiór zgodny ze stroną: adnotacja po stronie Aggregate uruchamia tylko ścieżki filaru values, a adnotacja po stronie Release — tylko ścieżki filaru infra. Kompozycja międzystronowa — values z encji Aggregate, infra z encji Release — tworzy jedno dołączenie encji Feature na parę (Component, Feature) z wypełnionymi oboma filarami i pochodzeniem na poziomie liści, rejestrującym, która strona dostarczyła każdy liść.

Przykład — adnotacja podsystemu kierowana do values

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

Po rozwinięciu adnotacji zarówno api, jak i worker mają syntetyczne dołączenie encji Feature feature.myco/db-pool, którego pole values.pool ma wartość "shared-pool". Graf budowania (aggrega validate --release <release> --ir-graph) rejestruje każdy liść z origin: annotation, side: aggregate i annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.

Ustrukturyzowane wartości adnotacji

Encja Feature z wieloma konfigurowalnymi polami skłania do użycia jednego klucza adnotacji, który niesie wartości dla kilku z nich naraz. Ustrukturyzowana forma adnotacji pozwala jednemu kluczowi kierować wartości do wielu ścieżek powiązania w jednej deklaracji:

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

Powiązanie w encji Manifest deklaruje routing wszystkich czterech podkluczy na listach maps: pogrupowanych według filarów:

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

Wartość adnotacji przyjmuje jedną z trzech postaci:

  • Skalarny ciąg znaków — pojedyncza wartość. Powiązanie musi deklarować łącznie dokładnie jedną ścieżkę; wartość skalarna trafia do tej ścieżki.
  • Obiekt ustrukturyzowany — mapa podkluczy na podwartości. Ścieżka każdego podklucza musi występować na liście maps.infra lub maps.values powiązania; podwartość trafia do wskazanego pola schematu encji Feature w zadeklarowanym filarze.
  • Jawne YAML null — w całości wyłącza dziedziczone powiązanie dla tego zakresu kaskady.

Każdy podklucz w wartości ustrukturyzowanej jest rozwiązywany względem listy maps powiązania niezależnie. Podklucz nieobecny zarówno w maps.infra, jak i w maps.values zatrzymuje kompilację z jasnym błędem wskazującym błędny podklucz i zadeklarowane ścieżki.

Scalanie kaskadowe wartości ustrukturyzowanych

Adnotacje ustrukturyzowane przechodzą kaskadowo z głębokim scalaniem na poziomie podkluczy. Adnotacja podrzędnego zakresu kaskady jest scalana z adnotacją nadrzędną dla każdego podklucza; poziom bliższy nadpisuje nadrzędny z dokładnością do podklucza:

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

Efektywne adnotacje po kaskadzie:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas wyłączony na tym poziomie zasięgu

Podrzędny poziom kaskady, którego wartość jest skalarna (wobec ustrukturyzowanej wartości nadrzędnej), zastępuje ją w całości zamiast scalać. Niezgodności kształtu między poziomami kaskady rozstrzygane są na korzyść wartości z bliższego poziomu; kompilator nie ostrzega o niezgodności kształtu.

Null dla całej wartości a null dla podklucza

Kaskada udostępnia dwa mechanizmy wyłączania o różnej szczegółowości:

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

Całe powiązanie adnotacji jest wyłączone w tym komponencie; w tym zakresie z tego klucza adnotacji nie powstaje żadne syntetyczne dołączenie encji Feature. Komponenty równorzędne zachowują odziedziczone powiązanie.

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

Adnotacja nadal ma udział w tym zakresie, ale podklucz read_replicas jest wyłączony. Pozostałe podklucze (zadeklarowane w tym zakresie lub odziedziczone z nadrzędnych poziomów kaskady) pozostają w mocy.

Wskazówka dla autorów: null dla całej wartości służy do wyłączenia sterowanego adnotacją dołączenia encji Feature w danym zakresie. Null dla podklucza należy stosować, gdy chce się zachować większość udziału adnotacji, ale wyłączyć jedno lub kilka konkretnych pól.

Podział strona–filar dla podkluczy

Niezmiennik Aggregate-as-Authoring-Surface obowiązuje dla każdego podklucza, gdy wartość adnotacji jest ustrukturyzowana. Filar każdego podklucza (według deklaracji maps powiązania) musi być zgodny ze stroną autorską:

  • Adnotacja po stronie encji Aggregate może zawierać tylko podklucze kierowane do maps.values.
  • Adnotacja po stronie encji Release może zawierać tylko podklucze kierowane do maps.infra.

Podklucz kierowany do niezgodnego filaru zatrzymuje kompilację z jasnym błędem wskazującym konkretny podklucz i filar. Łańcuch błędów zbiera wszystkie niezgodne podklucze danej adnotacji przed zatrzymaniem — operatorzy widzą każdy problem w jednym cyklu kompilacji zamiast powtarzać cykl poprawka–kompilacja.

Walidacja typów dla podkluczy

Wartość każdego podklucza w czasie wykonania jest walidowana względem typu zadeklarowanego w spec.schema docelowej encji Feature w filarze, do którego jest kierowana. Obsługiwane zadeklarowane typy to string, integer, number, boolean, object, array, null. Podwartość, której typ YAML nie odpowiada typowi zadeklarowanemu w schemacie, zatrzymuje kompilację z jasnym błędem wskazującym podklucz, rzeczywisty typ i typ zadeklarowany.

Dopasowanie typów jest ścisłe — bez koercji. Ciąg "20" wobec pola schematu typu integer zatrzymuje kompilację; autorzy deklarują poprawne typy w schemacie encji Feature lub używają adnotacji skalarnych, które są przekazywane jako ciągi znaków.

Dźwignia autorska dla ścisłej walidacji. Właściwości bez zadeklarowanego type w spec.schema encji Feature przyjmują wartość o dowolnym kształcie, w tym zagnieżdżone mapy. Gdy schemat nie deklaruje ograniczenia, budowanie go nie wymyśla. Autorzy, którzy chcą ścisłej walidacji typów dla podkluczy, deklarują type dla każdej właściwości w spec.schema. Warstwa renderowania FeatureRecipe w dalszej kolejności obsługuje każdy kształt, jaki niesie udział adnotacji.

Kompozycja międzystronowa

Gdy zarówno adnotacja po stronie encji Aggregate (podklucze values), jak i adnotacja po stronie encji Release (podklucze infra) dotyczą tego samego dołączenia encji Feature w tej samej encji Component, budowanie scala te udziały w jedno dołączenie encji Feature z wypełnionymi oboma filarami. Pochodzenie na poziomie liści zapisuje źródło każdego podklucza — syntetyczne dołączenie zawiera values.db_name przypisane do miejsca autorskiego w encji Aggregate oraz infra.pool_size przypisane do miejsca autorskiego w encji Release.

Wzorzec kompozycji międzystronowej to kanoniczny kształt autorski dla encji Features z mieszanymi polami intencji programisty i wymiarowania przez operatora: Aggregate deklaruje wybory koncepcyjne (która baza danych, ile replik na poziomie aplikacji); Release deklaruje wymiarowanie fizyczne (jak duża pula, ile połączeń na poziomie infrastruktury). Jedno powiązanie w encji Manifest łączy je jednym zestawem deklaracji maps.