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
- 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.
- Każdy dostawca dokumentuje, które adnotacje odczytuje i jakie wartości domyślne stosuje.
- 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
infrakomponentu. - Dobrze znane adnotacje Provider nigdy nie powielają etykiet Component. Etykiety Component opisują, czym jest komponent. Adnotacje granicy opisują, gdzie komponent jest wdrażany.
- 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ść.
- Prefiks
aggrega.ai/jest zarezerwowany dla biblioteki standardowej. Własne adnotacje przedsiębiorstwa używają własnego prefiksu. - 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-chartpobiera nazwę chartu nadrzędnego zaggrega.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. - 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-namejest 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-accountiaggrega.ai/kubernetes-versionkształ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-namejest rozwiązywany raz, gdy składany jest chart parasolowy, a trzy kluczeaggrega.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
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/namespace | helm (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-name | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla nazwy projektu Docker Compose | — |
aggrega.ai/region | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla regionu chmury w zakresie rozmieszczenia | — |
aggrega.ai/account-id | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla identyfikatora konta chmurowego w zakresie rozmieszczenia | — |
aggrega.ai/kubernetes-version | helm (sourced) | Wersja Kubernetes klastra, w którym wdrażany jest komponent, odczytywana przez chart renderowany ze źródła jako .Capabilities.KubeVersion | Wersja, 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
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — tylko synthesized | Prefiks rejestru dla obrazów kontenerów, stosowany do każdej referencji do syntetyzowanego obrazu kontenera | Brak prefiksu |
aggrega.ai/image-pull-secret | helm — tylko synthesized | Nazwa imagePullSecrets Kubernetes, łączona z istniejącymi wpisami syntetyzowanego poda | Brak |
Kategoria 3 — Sieć
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/cluster-domain | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla sufiksu DNS do wykrywania usług między przestrzeniami nazw | — |
aggrega.ai/ingress-class | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla IngressClass Kubernetes w zasobach Ingress | — |
aggrega.ai/service-mesh | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla adnotacji wstrzykiwania sidecara siatki usług | — |
Kategoria 4 — Bezpieczeństwo
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/service-account | helm — tylko synthesized | ServiceAccount Kubernetes dla syntetyzowanych podów; nadpisuje workload.serviceAccount encji Recipe, gdy ustawiono oba | workload.serviceAccount encji Recipe lub brak ustawienia, gdy encja Recipe go nie deklaruje |
aggrega.ai/pod-security-standard | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla poziomu Pod Security Standards | — |
aggrega.ai/iam-role | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla roli tożsamości chmurowej powiązanej z obciążeniem | — |
Kategoria 5 — Pakowanie
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — dla złożenia | Nazwa chartu parasolowego | Nazwa encji Aggregate połączona ze ścieżką zestawienia wykresu parasolowego — zob. Rozwiązywanie nazwy wykresu |
aggrega.ai/chart-version | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla wersji chartu Helm | — |
aggrega.ai/stack-name | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla jawnie nazwanego stosu | — |
aggrega.ai/tf-backend | zarezerwowana; żaden provider jej nie odczytuje | Zarezerwowana dla identyfikatora backendu stanu Terraform | — |
Kategoria 6 — Docelowa chmura
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — 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-region | cloudformation — 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-arn | cloudformation — 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ędny | Przy 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.
| Provider | Rodzaj wejścia | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-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 itW 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 itZatem 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.
| Adnotacja | Stosowana przez | Przeznaczenie | Domyślnie |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | Nazwa 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-account | cloudformation | Konto 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-region | cloudformation | Region 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-arn | cloudformation | ARN 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.annotationsw encji Manifest używające prefiksuaggrega.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
nullw 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.
| Adnotacja | Tworzona w | Odczytywana przez | Przeznaczenie |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | metadata.annotations encji Component | kompilator, na sfinalizowanym grafie | Deklaruje 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ło | Emisja |
|---|---|---|
app.kubernetes.io/name | Identyfikator 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-id | Identyfikator 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 komponent | Wszyscy trzej dostawcy, gdy ścieżka granicy nie jest pusta; w helm i helm-chart jako adnotacja |
aggrega.ai/aggregate-name | metadata.name encji Aggregate | Wszyscy trzej dostawcy, gdy wartość jest ustawiona |
aggrega.ai/compiler-version | Wersja kompilatora utrwalona w czasie kompilacji | Wszyscy trzej dostawcy, gdy wartość jest ustawiona |
aggrega.ai/provider | Provider, który wyrenderował zasób | Wszyscy trzej dostawcy |
aggrega.ai/provider-version | Wersja tego providera | Wszyscy trzej dostawcy |
aggrega.ai/environment | metadata.environment encji Release | Wszyscy trzej dostawcy — każda encja Release ją deklaruje |
aggrega.ai/sync-wave | Liczba całkowita syncWave dla danej granicy | Wszyscy 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ą dometadata.labelsw 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-waveoraz dosłowna wartość każdej etykiety przepisanej w sposób opisany powyżej — dometadata.annotations. Ścieżki trybu źródłowego (renderowanie Helm SDK z wstrzykiwaniem etykiet po renderowaniu), trybu syntetyzowanego (synteza obciążenia) iartifacts:dają ten sam zestaw.helm-chart— te same etykiety i adnotacje trafiają na każdy artefakt ładowany przez$import:, który provider dodaje dotemplates/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ą doservices.<name>.labelsw 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 etykietaapp.kubernetes.io/namejest 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.
| Adnotacja | Emisja | Odczytywana przez |
|---|---|---|
argocd.argoproj.io/sync-wave | helm — 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 niezerowe | Kolejność sync-wave w ArgoCD |
helm.sh/hook-weight | tylko helm, na manifestach generowanych z szablonów chartu, które mają już adnotację helm.sh/hook, gdy syncWave jest niezerowe | Kolejność 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:
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ą):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereKaskada 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
nullw 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 overrideAdnotacje 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ą.
# Aggregatespec: 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# Releasespec: 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 bindingspec: 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# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0Po 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: 100Powiązanie w encji Manifest deklaruje routing wszystkich czterech podkluczy na listach maps: pogrupowanych według filarów:
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsWartość 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.infralubmaps.valuespowią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 parentEfektywne adnotacje po kaskadzie:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }—read_replicaswyłą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 scopecomponents: api: annotations: feature.myco/db-pool: nullCał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 subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullAdnotacja 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.
Powiązane materiały
- Architektura Provider — architektura wtyczek dostawców i rola wtyczki Plugin odpowiedzialnej za renderowanie przez dostawcę.
- ../entities/release.md — powierzchnia autorska encji Release, w której znajdują się adnotacje granic i komponentów.
- ../entities/aggregate.md — powierzchnia autorska encji Aggregate, w której znajdują się adnotacje podsystemów i komponentów.
- ../entities/manifest.md — mapa
mappings.features.annotationsencji Manifest, w której powiązania adnotacji deklarują swoje kierowaniemaps:. - ../../architecture/11-governance-and-compliance.md — opis znakowania pochodzenia w czasie kompilacji, uzupełniającego adnotacje kontrolowane przez autorów.