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

Etykiety i adnotacje

Encje Aggrega mają dwa strukturalnie podobne mechanizmy metadanych — metadata.labels i metadata.annotations — a także pola przenoszące adnotacje, rozproszone po miejscach kaskadowania granic i dołączania funkcji. Sześć odrębnych miejsc definiuje lub przenosi treść adnotacji i etykiet, a każde z nich ma inne reguły kaskadowania, innych odbiorców i inne konwencje prefiksów. Ta strona opisuje te miejsca w jednym miejscu, definiuje trzy semantyczne kategorie, które udostępnia kontekst szablonów w czasie wykonania, określa dyscyplinę prefiksów, której autorzy powinni przestrzegać, oraz zestawia obok siebie pięć miejsc dołączania encji Feature, aby były widoczne w kontekście szerszego słownictwa etykiet i adnotacji.

Sześć miejsc zawierających adnotacje i etykiety

Autorzy spotykają etykiety i adnotacje w sześciu odrębnych miejscach. Każde z nich ma inny zakres, inną regułę kaskadowania i innego konsumenta.

#MiejsceZakresReguła kaskadowaniaGłówny konsument
1metadata.labels encji katalogowejTożsamość poszczególnej encji (Component, Feature, Aggregate)Nie kaskaduje do instancji; przenoszone na samej encji katalogowejaggrega search -l dla encji Components i Features; etykiety encji Aggregate są przechowywane w jej dokumencie i żadne polecenie ich nie odczytuje
2metadata.labels encji Component (wewnętrzne)Właściwości poszczególnej instancji encji Component (component.aggrega.ai/type itp.)Kaskaduje do .context.labels każdego węzła IR po mutacjach label-transformDopasowywanie selektorów (deklaracje usesSchema selector:, przenoszone jako x-aggrega-selector: w syntetyzowanym JSON Schema), logika szablonów Recipe
3metadata.annotations encji ComponentCechy poszczególnej instancji encji Component tworzone przez architektaKaskaduje do kubełka .context.annotations.catalog każdego węzła IRrole werdyktów zarządczych (polityki cech wewnętrznych), logika szablonów Recipe
4annotations: encji Aggregate / podsystemuMetadane kognitywne po stronie encji AggregateKaskaduje do kubełka .context.annotations.aggregate każdego węzła IRvaluesMapping: encji Recipe do routingu kognitywnego
5annotations: granicy ReleaseFizyczne metadane po stronie Ops, w tym dobrze znane adnotacje aggrega.ai/*Kaskaduje do kubełka .context.annotations.release każdego węzła IRProviders (helm odczytuje aggrega.ai/namespace; compose wyprowadza nazwę sieci z tego samego klucza); injectMapping: encji FeatureRecipe do routingu między granicami
6Powiązania features.annotations encji ManifestPowiązanie klucz adnotacji → typ Feature z routingiem podkluczy pogrupowanych według filarów (maps.infra / maps.values) do dołączania Feature sterowanego adnotacjamiPodfaza rozwijania adnotacji w ramach rozwiązywania przechodzi granice Release (od zewnętrznych do wewnętrznych) i podsystemy Aggregate (od zewnętrznych do wewnętrznych); obowiązuje nadpisanie na poziomie komponentu oraz rezygnacja przez null dla całej wartości / poszczególnego podklucza; egzekwowanie strona–filar określa, który filar zostaje uruchomiony dla danej strony autorskiejRozwijanie Feature sterowane adnotacjami (syntetyczne dołączenia Feature, zapisywane w grafie IR z origin: annotation)

Miejsca 4 i 5 mają wspólny kształt YAML (mapa annotations: na kaskadującej granicy), ale kaskadują do odrębnych kubełków IR — rozróżnienie kubełków jest kluczową regułą udostępnianą przez środowisko uruchomieniowe. Miejsce 6 jest strukturalnie odrębne: znajduje się w encji Manifest, a nie w treści Aggregate / Release, a jego konsumpcję warunkuje przebieg rozwijania sterowanego adnotacjami.

Semantyka trzech koszyków .context.annotations.*

Gdy renderer przetwarza szablon encji Recipe, pole .context.annotations każdego węzła zawiera trzy nazwane koszyki. Każdy koszyk jest płaską mapą string → string z kluczami w postaci nazw adnotacji; koszyk określa, kto utworzył adnotację i jaki jest jej cel.

  • .context.annotations.release — adnotacje granicy encji Release (miejsce 5). Służą do zarządzania rzeczywistością fizyczną; renderery kierują je w stosownych przypadkach do pól infra:. W tym koszyku znajdują się dobrze znane adnotacje aggrega.ai/*.
  • .context.annotations.catalog — adnotacje z metadanych encji Component (miejsce 3). Niezmienne cechy wewnętrzne tworzone przez architekta; konsumowane głównie przez pluginy polityk Wasm.
  • .context.annotations.aggregate — adnotacje podsystemu encji Aggregate (miejsce 4). Metadane kognitywne; renderery kierują je w stosownych przypadkach do ładunków values:.

Rozdział trzech koszyków jest umową społeczną

Kompilator nie egzekwuje granic koszyków. Trzy koszyki mają ten sam płaski kształt string → string; szablon encji Recipe może odczytać wszystkie trzy i nic nie stoi na przeszkodzie, by adnotacja granicy encji Release została zinterpretowana jako pole metadanych kognitywnych albo by adnotacja katalogowa została skierowana do infra:. Rozdział jest dyscypliną autorską, a nie gwarancją kompilatora.

Cel tej dyscypliny — co koszyki mają w zamierzeniu wyrażać:

  • release = „gdzie działa ten komponent, zarządzane przez Ops”
  • catalog = „czym jest ten komponent, tworzone przez architekta”
  • aggregate = „co robi ten komponent, tworzone przez programistę”

Gdy autorzy przestrzegają tego rozdziału, narzędzia na dalszych etapach mogą odczytywać właściwy koszyk dla właściwego zagadnienia. Gdy autorzy go naruszają (np. umieszczając metadane kognitywne w adnotacjach release, bo plik encji Release jest pod ręką), środowisko uruchomieniowe nadal działa, ale cel koszyka się zaciera.

Gniazdo lintera — oznaczanie odczytów między koszykami

Plugin lintera (doradczy, działający poza głównym przebiegiem; kryterium umiejscowienia opisano w plugins/plugin-contract.md) może oznaczać odczyty między koszykami, w których szablon encji Recipe pobiera dane z koszyka, którego cel nie odpowiada kierowanemu polu. Kryterium:

  • Odczyt .context.annotations.release w celu wypełnienia pola values: — oznaczyć (metadane kognitywne powinny pochodzić z koszyka aggregate).
  • Odczyt .context.annotations.aggregate w celu wypełnienia pola infra: — oznaczyć (metadane fizyczne powinny pochodzić z koszyka release).
  • Odczyt .context.annotations.catalog w celu wypełnienia values: lub infra: — zwykle tylko ostrzeżenie doradcze (adnotacje katalogowe to cechy wewnętrzne; kierowanie ich do filarów jest nietypowe, ale nie zawsze błędne).

Linter publikacji nie ma reguły dla tego kryterium, a kompilacja go nie sprawdza; może to zrobić własny plugin lintera przez gniazdo lintera uruchamiane przez aggrega lint. Tej dyscypliny przestrzegają recenzenci i autorzy stosujący konwencję przeznaczenia koszyków.

Dyscyplina prefiksów

Klucze adnotacji i etykiet mają jednolitą postać <namespace>/<name>. Poniższe rodziny prefiksów określają, kto tworzy klucze w każdej z nich i jak każda jest przestrzegana — jeden prefiks jest zarezerwowany, a kompilacja zatrzymuje się, gdy powiązanie encji Manifest lub etykieta wyjściowa encji Recipe deklaruje w nim nowy klucz; pozostałe są konwencją katalogu i nic nie odrzuca w nich klucza. Różnica między nimi polega na tym, czy kompilacja się zatrzymuje, dlatego środkową kolumnę należy przeczytać przed pozostałymi.

PrefiksKto tworzy tu kluczeJak jest przestrzeganyPrzeznaczeniePrzykłady
aggrega.ai/Wyłącznie platforma AggregaZarezerwowany i egzekwowany. Platforma definiuje tu klucze, a użytkownik zapisuje te, które ona definiuje — np. aggrega.ai/namespace na granicy encji Release. Deklaracja nowego klucza w tym prefiksie zatrzymuje kompilację: zarówno powiązanie features.annotations encji Manifest pod samym prefiksem, jak i klucz etykiety wyjściowej encji Recipe pod nim w outputLabels: lub outputComponentLabels:. Adnotacja zapisana pod nim, której platforma nie definiuje, nie jest odrzucana: kompilacja ją przenosi, a gdy znajduje się w encji Release, cel, który jej nie obsługuje, informuje o tym ostrzeżeniem. Zob. errors/fatal-halts.md „A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Powiązanie adnotacji w manifeście deklaruje zarezerwowany prefiks)” oraz „An output-label key uses a reserved namespace (Klucz etykiety wyjściowej używa zarezerwowanej przestrzeni nazw)”.Natywne adnotacje platformy konsumowane bezpośrednio przez dostawcęaggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Oficjalna biblioteka standardowaKonwencja. Nic nie odrzuca tu klucza; słownictwo należy do biblioteki standardowej na mocy porozumienia, a nie kontroli.Skróty adnotacji encji Feature wiązane w features.annotations encji Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Oficjalna biblioteka standardowaKonwencja. Nic nie odrzuca tu klucza.Etykiety cech wewnętrznych encji Component (tu znajduje się klucz selektora component.aggrega.ai/type)component.aggrega.ai/type
aggregate.aggrega.ai/Oficjalna biblioteka standardowaKonwencja. Nic nie odrzuca tu klucza.Etykiety tożsamości na poziomie modułu encji Aggregateaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Oficjalna biblioteka standardowa oraz przedsiębiorstwa we własnych katalogachKonwencja. Nic nie odrzuca tu klucza.Etykiety możliwości — wymiary behawioralne, według których rozróżnia selektor usesSchema lub appliesTo encji Feature. <role> nazywa obszar, do którego należy wymiar: rolę komponentu albo zagadnienie przekrojowe wspólne dla kilku ról.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Przedsiębiorstwo / społecznośćOtwarty. Należy tworzyć klucze w domenie, którą się kontroluje.Niestandardowe adnotacje i etykietyacme.com/billing-tier, corp/cost-center

Autorzy niestandardowych adnotacji używają kontrolowanej przez siebie domeny (zwykle w stylu odwróconego DNS). Tworzenie kluczy bezpośrednio pod aggrega.ai/ (bez podprefiksu) jest zarezerwowane dla platformy; powiązania features.annotations encji Manifest również nie mogą wiązać kluczy bezpośrednio pod aggrega.ai/ — zob. entities/manifest.md „Rezerwacja prefiksu aggrega.ai/”.

Nazywanie prefiksu możliwości

Klucz możliwości ma postać <role>.aggrega.ai/<dimension>, a <role> to część, która wymaga osądu. Rządzą nią trzy zasady, a pierwszą najczęściej rozumie się na odwrót.

  • Należy nazywać zagadnienie, a nie rodzaj komponentu, który akurat jako pierwszy je ma. Gdy wymiar opisuje coś wspólnego dla kilku rodzajów komponentów, prefiks nazywa wspólne zagadnienie, aby kolejny rodzaj, który je zyska, ponownie użył słownictwa zamiast wymyślać równoległe. component.aggrega.ai/hosting to zagadnienie — kto obsługuje zasób bazowy — i opisuje bazę danych oraz API modelu tymi samymi słowami; dataplane.aggrega.ai/* nazywa pozycję na ścieżce ruchu, więc proxy, brama ingress i service mesh opisują się jednakowo. Wymiar rzeczywiście specyficzny dla jednej roli przyjmuje nazwę tej roli, jak model.aggrega.ai/capability.
  • Jedno słowo małymi literami, bez łącznika, w prefiksie. Łącznik należy do połowy <dimension>, gdzie złożenie czyta się naturalnie (request-mirroring, data-class, upstream-licensing).
  • Wymiar dodaje się wtedy, gdy potrzebuje go selektor, a każda deklarowana przez niego wartość ma komponent, który ją nosi. Każde słowo tutaj autor katalogu musi poznać, a autor encji Feature może napotkać, więc wymiar zasługuje na miejsce, rozróżniając coś, o co rzeczywiście pyta usesSchema lub appliesTo. Wartość, której nie nosi żaden komponent, jest gorsza niż jej brak: selektor, który ją wskazuje, parsuje się, niczego nie dopasowuje i niczego nie zgłasza — dlatego wartość, której katalog nie potrafi wykazać, pozostaje poza słownictwem, dopóki nie nosi jej jakiś komponent. Wyjątkiem jest klucz, którego wartość jest deklaracją środowiska o tym, jak używa własnych komponentów, a nie właściwością produktu, i takim przypadkiem jest compliance.aggrega.ai/data-class: klasa danych komponentu zależy od tego, jak środowisko go używa, więc żadna encja Component biblioteki standardowej nie nosi żadnej z jego wartości i żadne gniazdo ani encja Feature biblioteki standardowej nie selekcjonuje według nich. Klucz i jego wartości są zadeklarowane po to, aby własne encje Components środowiska i dołączane przez nie polityki miały jedną pisownię; selektor lub polityka wskazująca wartość dopasowuje tylko w katalogu, którego encje Components ją noszą. policy-data-class-route pokazuje jedną taką encję Component i politykę, która ją odczytuje.

Rezerwacja i klucz zdefiniowany przez platformę to nie to samo

Rezerwacja dotyczy samego korzenia aggrega.ai/. Każda przestrzeń nazw <scope>.aggrega.ai/ pod nim jest osobną przestrzenią kluczy, której platforma nie posiada, i to właśnie zapewnia rozszerzalność słownictwa katalogu: katalog przedsiębiorstwa może utworzyć acme.aggrega.ai/team, nie naruszając niczego, co utrwala kompilacja.

Kilka kluczy w tych otwartych przestrzeniach nazw jest jednak zdefiniowanych przez platformę i odczytywanych przez kompilację, co nie czyni ich przestrzeni nazw zarezerwowaną:

  • component.aggrega.ai/type jest wymagany w metadata.labels każdej encji Component i przyjmuje jedną z ustalonego zbioru wartości. Selektory dopasowują według niego; kompilator nie rozgałęzia się w zależności od jego wartości.
  • features.aggrega.ai/requiredType.<label>, zapisany w metadata.annotations encji Component, deklaruje, że musi być dołączona encja Feature wskazanego typu. Kompilacja sprawdza ten wymóg względem końcowego zbioru dołączeń każdego węzła i zatrzymuje się, gdy nic go nie spełnia — zob. errors/fatal-halts.md „Required feature not attached (Wymagana funkcja nie jest dołączona)”. Należy zwrócić uwagę na liczbę mnogą: features.aggrega.ai/ to osobna przestrzeń nazw, różna od pojedynczej feature.aggrega.ai/ z powyższej tabeli, która zawiera skróty powiązań encji Manifest.

Różnicę należy rozumieć tak: prefiks zarezerwowany odrzuca klucz, który próbuje się w nim zdefiniować, natomiast klucz zdefiniowany przez platformę to jeden nazwany klucz znany kompilacji, znajdujący się w przestrzeni nazw, w której poza tym można swobodnie tworzyć klucze. Każdy inny klucz pod component.aggrega.ai/, features.aggrega.ai/ i pozostałymi to metadane, które kompilacja przenosi bez interpretowania.

Jeden taki klucz w metadata.annotations encji Component odczytuje standardowy linter publikacji, a nie kompilacja: observability.aggrega.ai/metrics-credential określa, jak uwierzytelniają się metryki produktu — none: są udostępniane bez poświadczenia; target-key: przyjmują klucz, którego encja Component wymaga od każdego wywołującego; separate-token: przyjmują własny token. Kompilacja przenosi go jak każdą inną adnotację. Linter odczytuje go, aby zdecydować, czy poświadczenie połączenia scrapującego jest porównywane z kluczem wywołującego celu, i wymaga jego zgodności z kluczem provides metrics_credential_required deklarowanym przez encję Component — zob. „The discipline rules” w cli/aggrega-lint.md.

Etykiety pochodzenia emitowane w renderowanym wyniku

Poza adnotacjami wejściowymi, które konsumują dostawcy, Aggrega emituje również etykiety pochodzenia w każdym manifeście Kubernetes renderowanym przez dostawcę helm i każdej emitowanej usłudze compose, a dostawca helm-chart zapisuje ten sam zestaw, tak jak zapisuje go dostawca helm, na każdym artefakcie ładowanym przez $import:. Ten zestaw etykiet pozwala narzędziom końcowym (pulpitom kosztów, stosom obserwowalności, kontrolerom GitOps) przypisać zasoby środowiska uruchomieniowego z powrotem do treści katalogu, która je wytworzyła. Własne szablony podwykresu helm-chart są kopiowane tak, jak napisał je ich autor, więc niosą te etykiety, które ten autor zapisał.

Zestaw emitowany przez dostawców helm i compose — w helm trzy z kluczy są zapisywane jako adnotacje, a nie etykiety, jak podaje tabela:

EtykietaŹródłoZawsze emitowana?
app.kubernetes.io/nameTożsamość encji Component — nazwa, którą zapisano, lub, w przypadku komponentu wnoszonego przez zaimportowaną encję Aggregate, jego nazwa kwalifikowana z rozpisanym separatorem modułu (zob. niżej); lub, w przypadku zasobu emitowanego przez encję FeatureRecipe, identyfikator wyprowadzony dla tego dołączeniaTak w manifestach Kubernetes; nie jest emitowana w usługach compose (standardowa etykieta jest specyficzna dla K8s)
aggrega.ai/component-idTożsamość encji Component — nazwa, którą zapisano, lub, w przypadku komponentu wnoszonego przez zaimportowaną encję Aggregate, jego nazwa kwalifikowana z rozpisanym separatorem modułu (zob. niżej); lub, w przypadku zasobu emitowanego przez encję FeatureRecipe, identyfikator wyprowadzony dla tego dołączeniaTak
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> wytwarzającej encji Recipe (lub wytwarzającej encji FeatureRecipe dla zasobów emitowanych przez FR)Gdy wytwarzająca encja ma ustawione zarówno nazwę, jak i wersję; w helm jako adnotacja
aggrega.ai/boundary-pathŚcieżka granicy, do której skierowano komponentGdy ścieżka granicy nie jest pusta; w helm jako adnotacja
aggrega.ai/aggregate-namemetadata.name encji AggregateGdy jest ustawiona
aggrega.ai/compiler-versionWersja kompilatora utrwalona w czasie kompilacjiGdy jest ustawiona
aggrega.ai/providerDostawca, który wyrenderował zasób (helm, helm-chart, compose)Tak
aggrega.ai/provider-versionWersja tego provideraTak
aggrega.ai/environmentmetadata.environment encji ReleaseTak — każda encja Release go deklaruje
aggrega.ai/sync-waveLiczba całkowita syncWave dla każdej granicy — kolejność, w jakiej narzędzie GitOps stosuje zasobyGdy różna od zera; w helm jako adnotacja obok argocd.argoproj.io/sync-wave

Nazwa agregatu, środowisko, wersja kompilatora oraz nazwa i wersja dostawcy to ciągi znaków wybrane przez użytkownika lub przez proces budowania, i żaden z nich nie podlega regułom Kubernetes dotyczącym wartości etykiet w miejscu, w którym jest zapisywany. W przypadku helm każda z tych etykiet przenosi wartość w zapisanej postaci, gdy jest ona już prawidłową wartością etykiety — litery, cyfry, -, _ i ., litera lub cyfra na obu końcach, najwyżej 63 znaki — a w przeciwnym razie wartość przepisaną na prawidłową, przy czym dosłowna wartość zostaje dodana jako adnotacja pod tym samym kluczem: encja Aggregate o nazwie imported/flow otrzymuje etykietę aggrega.ai/aggregate-name: imported-flow i adnotację aggrega.ai/aggregate-name: imported/flow. Wartość, która już spełnia te reguły, nie dodaje żadnej adnotacji. Compose przenosi dosłowną wartość jako etykietę. Reguła przepisywania jest opisana w providers/well-known-annotations.md „Etykiety pochodzenia emitowane przez dostawców”.

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 FeatureRecipe może dostarczyć te zasoby: czy syntetyzuje obciążenie, emituje samodzielny zestaw artefaktów, czy renderuje chart lub fragment dostarczony przez autora. Zapytanie wybierające zasoby dołączenia według tożsamości zwraca więc je wszystkie i żadnego z nich nie da się pomylić z zasobem wyemitowanym przez sam komponent-host. Sposób budowania wartości zależy od tego, gdzie dołączono encję Feature; w obu przypadkach wynik jest prawidłowym ciągiem etykiety Kubernetes.

Dla komponentu wnoszonego przez importowaną encję Aggregate tożsamością jest nazwa kwalifikowana tego komponentu z rozpisanym separatorem łączącym moduł z komponentem — data-layer.main-db jest utrwalana jako data-layer-zdmain-db — ponieważ kropka nie jest znakiem, który nazwa zasobu lub adres w klastrze mogą bezpiecznie zawierać. Zapisana nazwa bez separatora jest utrwalana bajt w bajt.

Tożsamość mówi, do czego zasób należy. To inne pytanie niż to, jak zasób się nazywa, i dla jednego sposobu dostarczania odpowiedzi są różne:

  • Gdy FeatureRecipe syntetyzuje obciążenie, Aggrega sama buduje te zasoby, więc nazywa je również według tożsamości: tożsamość trafia do ich metadata.name, etykiet selektora i nazw emitowanych plików, a także do ich etykiet. Jest to nazwa wewnątrz klastra, a nie tylko etykieta.
  • Gdy FeatureRecipe dostarcza chart lub fragment napisany przez autora, nazwy należą do tego, kto go napisał. Nazwa wydania Helm, względem której renderują się te szablony — oraz prefiks plików emitowanych przez to renderowanie — pozostają nazwą komponentu-hosta. Charty zwykle nazywają swoje zasoby według nazwy wydania, więc jej zmiana przemianowałaby zasoby deklarowane przez sam chart, w klastrze, w którym są już wdrożone, z powodu niezwiązanego z chartem. Etykiety nadal niosą własną tożsamość dołączenia, dzięki czemu zasoby dołączenia pozostają możliwe do odnalezienia.
  • Gdy encja Feature jest dołączona do granicy, nie ma komponentu-hosta, którego nazwa mogłaby ją zastąpić, więc złożona tożsamość jest tam podstawą nazewnictwa, a także etykietą.

W obu przypadkach wartość jest składana z zapisanych części, połączonych przez --, za stałym początkiem, który wskazuje, z którym przypadkiem mamy do czynienia. Używane są dwa początki, a zapisana tożsamość komponentu nie może zaczynać się od żadnego z nich — dzięki temu nazwy zapisanej i nazwy złożonej przez Aggrega nigdy nie można ze sobą pomylić.

Gdy encja Feature jest dołączona do komponentu, częściami są stały początek cfr, tożsamość komponentu, do którego dołączono encję Feature, oraz klucz, pod którym ją dołączono. Encja Feature dołączona do komponentu api pod mon daje cfr--api--mon. Komponent-host jest częścią wartości, ponieważ jedna nazwa encji Feature dołączona do kilku komponentów emituje osobny zestaw zasobów na każdym z nich, a każdy zestaw potrzebuje własnej tożsamości: dołączenie mon zarówno do api, jak i do worker daje cfr--api--mon i cfr--worker--mon zamiast jednej wartości dla obu. Z tego samego powodu dołączenie nazwane dokładnie tak jak hostujący je komponent daje wartość różną od własnej wartości tego komponentu — mon dołączone do mon daje cfr--mon--mon.

Gdy encja Feature jest dołączona do granicy — kanonicznym przykładem jest usługa bramy compose-bridge — częściami są stały początek bfr, następnie każdy segment ścieżki granicy, od najbardziej zewnętrznego, a potem nazwa, pod którą dołączono encję Feature. Encja Feature o nazwie gateway na granicy bridge daje bfr--bridge--gateway; ta sama encja Feature na granicy prod/eu daje bfr--prod--eu--gateway.

Znak, którego wartość nie może zawierać, jest rozpisywany, a nie zastępowany, a ponieważ wartość jest zarówno etykietą, jak i nazwą wewnątrz klastra, ogranicza się ją do znaków dopuszczanych przez nazwę zasobu Kubernetes każdego rodzaju: małych liter, cyfr i łącznika. Zapisany łącznik pozostaje więc łącznikiem, mała litera lub cyfra pozostaje bez zmian, a każdy inny znak — łącznie z wielką literą, którą wartość etykiety dopuszcza, a nazwa zasobu odrzuca — staje się krótką sekwencją ucieczki: dołączenie o nazwie my_zone wnosi my-zuzone, a komponent myApi z dołączeniem worker otrzymuje cfr--my-zx000041pi--worker. To właśnie tą wartością z sekwencjami ucieczki zasoby dołączenia są etykietowane i wybierane na każdym celu, według niej nazywane i zapisywane w plikach jest obciążenie syntetyzowane przez dołączenie, i z niej wyprowadzana jest nazwa wydania dołączenia granicy. Wielka litera to jedyny znak, który reguła nazw zasobów dodaje do tego, co rozpisałaby sama etykieta, więc złożona wartość, której części nie zawierają wielkich liter — cfr--api--mon, bfr--prod--eu--gateway — jest wartością, jaką niosłaby sama etykieta. Dwa dołączenia, które można odróżnić, otrzymują więc dwie wartości — niezależnie od nadanych nazw i głębokości granicy — ponieważ -- to ciąg, którego nie może zawierać żadna zapisana część, więc przesunięcie podziału między częściami zmienia wartość, zamiast z nią kolidować.

Dopuszczalna długość złożonej wartości zależy od celu, a nie od liczby przechowywanej przez Aggrega: pytany jest cel, dla którego renderowane są zasoby, a wartość jest skracana, dopóki ten cel jej nie zaakceptuje. Wartość etykiety Kubernetes ma co najwyżej 63 znaki, a nazwa wydania Helm wyprowadzona z tej samej tożsamości jest ograniczona jeszcze ściślej, więc to samo dołączenie może dla jednego celu zostać krótsze niż dla innego. Wartość, która się mieści, jest emitowana dokładnie w złożonej postaci — to przypadek zwykły i przypadek każdego dołączenia w katalogu biblioteki standardowej. Wartość, która się nie mieści, jest skracana: każda część zachowuje swój początek, a dziesięcioznakowy skrót całej tożsamości jest dołączany za znacznikiem, którego nie wytworzy żadna zapisana nazwa — skróconą wartość można więc rozpoznać i nigdy nie zostanie odczytana jako wartość, która się zmieściła. Głęboko zagnieżdżone dołączenie gateway może więc zostać wyrenderowane jako bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Spotkanie dwóch skróconych wartości jest bardzo mało prawdopodobne, a jeśli do niego dojdzie, kompilacja zostaje zatrzymana, zamiast pozwolić im współdzielić nazwę.

Zob. errors/fatal-halts.md „The same name is derived more than once inside the output (Ta sama nazwa jest wyprowadzana więcej niż raz w wyniku)”, aby dowiedzieć się, które pary powodują zatrzymanie i jak je rozdzielić.

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

Szczegóły emisji dla poszczególnych dostawców (gdzie w renderowanym wyniku trafiają etykiety i jak każdy dostawca je serializuje) opisuje providers/well-known-annotations.md „Provenance labels emitted by providers”.

Etykiety wyjściowe deklarowane w encji Recipe

Obok zestawu etykiet pochodzenia należącego do kompilatora autor encji Recipe może zadeklarować własne etykiety, które zostaną nadane wyrenderowanemu wynikowi tej encji Recipe, za pomocą Recipe.spec.outputLabels:. Korzystają one z tego samego mechanizmu emisji co etykiety pochodzenia — są scalane z tym samym zestawem etykiet i trafiają wszędzie tam, gdzie trafiają etykiety pochodzenia — ale należą do autora, a nie do kompilatora. Zamierzonym zastosowaniem jest cecha realizacji: właściwość tego, jak konkretna encja Recipe realizuje komponent (na przykład hosting: managed w porównaniu z hosting: self-hosted dla encji Recipe opartej na usłudze zarządzanej w porównaniu z encją Recipe opartą na samodzielnie hostowanym charcie dla tego samego typu komponentu), udostępniona w wyniku, aby narzędzia do analizy kosztów, polityk i inwentaryzacji mogły ją odpytywać.

Przestrzenie nazw aggrega.ai/ i app.kubernetes.io/ są zarezerwowane dla zestawu etykiet pochodzenia; klucz z którymkolwiek z tych prefiksów jest odrzucany podczas ładowania — w outputLabels: oraz w outputComponentLabels:, towarzyszącym bloku, który wskazuje klucz etykiety komponentu i nadaje wartość deklarowaną przez sam komponent. Zwalidowany zestaw etykiet wyjściowych jest zatem zawsze rozłączny z kluczami pochodzenia, więc oba zestawy nigdy nie kolidują w scalonym wyniku. Sprawdzany jest sam rdzeń: klucz z zakresem, taki jak component.aggrega.ai/hosting, należy do osobnej przestrzeni nazw i może zostać zapisany dosłownie lub promowany. Udostępnianie w poszczególnych encjach Provider (obiekt helm i szablon poda przy syntezie; obiekt przy renderowaniu źródła i artefaktach; etykiety usług compose; tagi terraform dla poszczególnych zasobów w treści artefaktów .tf.json) odpowiada rozmieszczeniu etykiet pochodzenia i jest w pełni opisane na stronie encji Recipe w sekcjach „Pole outputLabels:” oraz „Pole outputComponentLabels:”.

Dołączanie encji Feature — pięć miejsc

Features dołącza się do Components w pięciu odrębnych miejscach tworzenia, z których każde ma inny zakres, innego docelowego użytkownika i inne pierwszeństwo w kolejności w 5-poziomowym modelu cebuli (5-Tier Onion Model). Pełna kolejność dołączania i sam model cebuli są opisane w architecture/10-compilation-pipeline.md; poniższa tabela zestawia te pięć miejsc obok siebie.

PoziomMiejsceAutorZakresReguła kaskadowania
1Blok features: komponentu w encji AggregateProgramistaNa instancję komponentu (szczegółowo)Brak — bezpośrednio od autora
2Blok features: podsystemu w encji AggregateProgramistaZakres podsystemu (przekrojowo w obrębie encji Aggregate)Kaskaduje do każdego komponentu w podsystemie
3Granica w encji Release components.<id>.featuresOpsNa instancję komponentu (szczegółowo, po stronie Ops)Brak — bezpośrednio od autora
4Blok features: granicy w encji ReleaseOpsZakres granicy (przekrojowo w obrębie granicy)Kaskaduje do każdego komponentu w granicy
5Rozwinięcie features.annotations w encji ManifestOperator platformySterowane adnotacjami (dołączenie syntetyczne)Kaskaduje przez drzewo granic (po stronie Release) lub drzewo podsystemów (po stronie Aggregate); obowiązuje nadpisanie na poziomie komponentu i rezygnacja przez null na poziomie podklucza

Te pięć miejsc się sumuje; dołączenie obecne w dowolnym z nich wnosi wkład do rozstrzygniętego zbioru funkcji encji Component. Gdy ta sama nazwa instancji Feature pojawia się w więcej niż jednym miejscu, wkłady scalają się w jedno dołączenie zamiast się wzajemnie zastępować, a niezgodność typów między nimi zatrzymuje budowanie błędem konfliktu scalania funkcji.

Pięć miejsc jest zamierzonych zgodnie z rozdziałem odpowiedzialności w architekturze — programista (poziomy 1–2), Ops (poziomy 3–4), operator platformy (poziom 5) — a nie nadmiarowych. Autorzy wybierają miejsce odpowiadające temu, kto jest właścicielem dołączenia i w jakim zakresie.

Które etykiety decydują, czy Feature ma zastosowanie

Feature deklaruje, gdzie może zostać dołączony, za pomocą spec.appliesTo i spec.appliesToAnyOf, a budowanie ocenia tę deklarację względem ostatecznych etykiet węzła, do którego trafia dołączenie. Dołączenie encji Feature do węzła, którego etykiety jej nie spełniają, zatrzymuje budowanie; Feature niedeklarujący żadnego z tych pól nie stawia wymagań i ma zastosowanie wszędzie.

Ostateczny zbiór etykiet jest składany w dwóch krokach i żaden z nich nie jest tym, który autorzy najczęściej zakładają.

  1. Węzeł bierze etykiety z encji katalogowej Component wskazanej w jego type:. Są one właściwością typu komponentu, a nie instancji: encja Aggregate nie może nadać etykiety instancji komponentu, encja Release również nie. Własne metadata.labels encji Aggregate opisują ją jako moduł wielokrotnego użytku i nie kaskadują do komponentów w jej wnętrzu. Dwie instancje jednego typu mają więc identyczne etykiety, a zmiana etykiet węzła oznacza zmianę typu, na który wskazuje — albo zmianę encji tego typu.
  2. Dołączenie label-transform może je następnie przepisać. Gdy konfiguracja przestrzeni roboczej dołącza plugin nadzoru w roli label-transform, działa on podczas budowy topologii i może dodawać, zmieniać lub usuwać etykiety węzłów, zanim cokolwiek zostanie względem nich ocenione. Nie może dotknąć niczego innego, więc etykiety są jedyną częścią węzła, którą może zmienić — i to właśnie od nich zależy możliwość zastosowania.

Propozycja oparta na etykietach zadeklarowanych w pojedynczym dokumencie jest zatem przybliżeniem, a nie przewidywaniem. Odczyt metadata.labels encji Component mówi, od czego zaczyna węzeł tego typu; to odpowiedź wystarczająco często trafna, by była użyteczna, i błędna na dwa konkretne sposoby: dokument, który jedynie dzieli nazwę z węzłem, jest innym podmiotem z innymi etykietami, a dołączenie label-transform może zmienić zbiór niezależnie od jakiegokolwiek dokumentu. Narzędzia proponujące dołączenia na podstawie samego źródła pracują na tym przybliżeniu; ocena dokonywana przez budowanie dotyczy zbioru ostatecznego.

Pierwszeństwo załączników

Gdy dwa wkłady dostarczają to samo pole tego samego dołączenia, cztery reguły rozstrzygają, który z nich trafi do wyrenderowanego wyniku. Stosuje się je w tej kolejności i to kolejność czyni wynik przewidywalnym:

  1. Pochodzenie. Wkład jawnie napisany przez autora wygrywa z wkładem sterowanym adnotacją, niezależnie od zakresu, w którym każdy z nich zadeklarowano. Zapisanie pola w bloku features: to sposób, w jaki autor nadpisuje to, co wniosłaby adnotacja, a adnotacja nigdy po cichu nie wypiera czegoś napisanego ręcznie. Kompilator zapisuje pominiętą adnotację obok zwycięskiej wartości i zgłasza ją jako komunikat doradczy, więc nadpisanie jest widoczne, a nie tajemnicze.
  2. Własność filarów. Każda domena wypełnia własny filar: miejsca w encji Aggregate wnoszą values, miejsca w encji Release wnoszą infra. Ponieważ obie strony nigdy nie zapisują tego samego filaru, wkład programisty i wkład operatora nie mogą rywalizować o to samo pole — nie ma pytania o pierwszeństwo programisty względem operatora.
  3. Autorytet kompozycji. Deklaracja we wdrażanej encji Aggregate ma pierwszeństwo przed deklaracją w encji Aggregate, którą ona komponuje, nawet gdy komponowana encja Aggregate zadeklarowała ją w węższym zakresie. Kompozycja pozostaje nadrzędna: moduł nie może pokonać korzystającej z niego encji Aggregate tylko przez wybór węższego zakresu.
  4. Szczegółowość. W obrębie jednego poziomu tworzenia i jednego filaru węższy zakres doprecyzowuje szerszy, pole po polu. Dołączenie w zakresie komponentu nadpisuje dołączenie o tej samej nazwie instancji w zakresie podsystemu lub granicy — ale tylko w polach, które faktycznie wymienia. Pola pominięte przez węższy zakres zachowują wartości szerszego, więc wspólne dołączenie może dostarczać wspólną konfigurację, a pojedynczy komponent zmieniać jedno jej pole. Dwa wkłady w tym samym zakresie rozstrzyga kolejność autora, przy czym wygrywa późniejszy; dzięki temu wewnętrzny podsystem może doprecyzować zewnętrzny, a głębsza granica płytszą.

Pierwszeństwo dotyczy wartości pól. Nie zmienia kolejności ewaluacji: sekwencja, w której kompilator składa miejsca i wykonuje przedrenderowe injectMapping każdego dołączenia, to stała pięciopoziomowa sekwencja opisana w architecture/10-compilation-pipeline.md. Napisany przez autora blok inject dołączenia podąża za tą sekwencją ewaluacji, a nie za powyższym rankingiem zakresów, więc jedno dołączenie nigdy nie ma dwóch konkurujących kolejności.

Które rodzaje mają metadata.labels i metadata.annotations

metadata.labels występuje w encjach Component, Feature, Aggregate oraz czterech rodzajach bibliotek; metadata.annotations w tych samych rodzajach z wyjątkiem Aggregate. Encje Manifest, Release, Recipe, FeatureRecipe i Plugin nie mają żadnego z nich.

Podsumowanie kaskadowania

Reguły kaskadowania w sześciu powierzchniach, w postaci, w jakiej ocenia je kompilator:

  1. Etykiety encji katalogu (powierzchnia 1) pozostają w encji katalogu. Nie przechodzą do instancji; konsumenci odczytują je, bezpośrednio analizując zawartość katalogu.
  2. metadata.labels encji Component (powierzchnia 2) trafiają do .context.labels każdego węzła po opcjonalnym przebiegu label-transform podczas budowy topologii.
  3. metadata.annotations encji Component (powierzchnia 3) trafiają do koszyka .context.annotations.catalog każdego węzła.
  4. annotations: encji Aggregate / podsystemu (powierzchnia 4) kaskadują przez hierarchię podsystemów, kumulując się od podsystemów zewnętrznych do wewnętrznych, do koszyka .context.annotations.aggregate każdego węzła.
  5. annotations: granicy encji Release (powierzchnia 5) kaskadują przez hierarchię granic od granic zewnętrznych do wewnętrznych, do koszyka .context.annotations.release każdego węzła.
  6. features.annotations encji Manifest (powierzchnia 6) nie kaskadują bezpośrednio do danych IR poszczególnych węzłów; podfaza rozwijania sterowanego adnotacjami w fazie rozwiązywania wykorzystuje powiązania do syntezy dołączeń encji Feature do poszczególnych węzłów, które graf IR (--ir-graph) zapisuje z origin: annotation. Po fazie rozwiązywania syntetyczne dołączenia są strukturalnie nieodróżnialne od jawnych, z wyjątkiem tej proweniencji — pełny opis rozwijania zawiera providers/well-known-annotations.md, a mechanikę ładowania katalogu i inspekcji opisuje architecture/13-catalog-and-registry.md §„Annotation-driven Feature expansion”.

Kanoniczny projekt kaskadowania adnotacji opisuje architecture/06-data-taxonomy-and-composition.md §2 (Flow 5).

Odsyłacze