FeatureRecipe
Koncepcyjna rola encji FeatureRecipe (Domena 3 — sterowana przez Wasm-plugin implementacja interfejsu Feature) jest opisana w architecture/04-entity-taxonomy.md. Ta strona omawia powierzchnię tworzenia katalogu encji FeatureRecipe.
Położenie w katalogu
Encje FeatureRecipes są uporządkowane z dostawcą w pierwszym segmencie ścieżki (według tego samego wzorca co Recipes):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlURI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (np. hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Kontrakt tworzenia
Encje FeatureRecipes wiążą się z interfejsem Feature przez implements i deklarują konkretnego dostawcę. Ich powierzchnia tworzenia to pełny zestaw rodzajów wejścia bazowej encji Recipe oraz dwa bloki specyficzne dla FeatureRecipe:
- Trzy rodzaje wejść —
source+valuesMapping(pozyskiwane),workload(syntetyzowane) orazartifacts: mają kształt identyczny jak w bazowej encji Recipe (zob. Recipe Input Composition orazentities/recipe.md). Encja FeatureRecipe, która zawiera którykolwiek z nich, jest generująca zasoby — renderuje zasoby obok bazowego komponentu. Miejsce, w którym te zasoby trafiają, niesie komponent, do którego dołączona jest encja Feature, a następnie nazwę, pod którą jest dołączona, w tej z dwóch form, którą dopuszcza układ samego celu: jako katalog{component}--{instance}/obok katalogu hosta, w tym katalogu, który dany cel przeznacza dla swoich kontrybutorów, na celu, którego dostawca daje każdemu kontrybutorowi własną pozycję; jako prefiks nazwy pliku{component}--{instance}--obok własnych plików komponentu, na celu, który odczytuje tylko pliki leżące bezpośrednio w katalogu. U dostawcy, który składa swoich kontrybutorów w jeden dokument, zasoby są zamiast tego wkomponowywane w ten dokument — niezależnie od rodziny, do której należy encja Feature: CRDServiceMonitorlubExternalSecretjakoartifacts:w treści lub przez$import; zewnętrzny chart lub moduł przezsource:+valuesMapping:; albo własne obliczenia (na przykład Deployment agenta sidecar) przezworkload:. PolevaluesMapping:dzieli z bazową encją Recipe trzy tryby tworzenia (blokowy skalar w treści, plikowy$import:, biblioteczny$import:do wpisu MappingLibrary) — zob.entities/recipe.md„ThevaluesMappingfield — three authoring modes”. Zgodnie z konwencją encja FeatureRecipe modyfikuje bazowy komponent lub dodaje zasoby obok niego, ale schemat nie ogranicza, których rodzajów wejść może używać — kompilator renderuje wszystko, co deklaruje FeatureRecipe, ograniczony jedynie możliwościami powiązanego dostawcy, i pozostaje bez własnego zdania co do tego, czy dany rodzaj jest „odpowiedni dla modyfikatora” (zob. niezmienniki założycielskie). Synteza (workload:) wymaga dostawcy, który ją obsługuje; w przeciwnym razie kompilacja zatrzymuje się na etapie renderowania z diagnostyką możliwości dostawcy. injectMapping(przechwytywanie przed renderowaniem): natywny blok szablonu Go wykonywany przed renderowaniem bazowej encji Recipe. Zwraca słownik JSON lub YAML, który kompilator natywnie głęboko scala z kanałem pamięci.context.injectwywołującego, umożliwiając modyfikację zmiennych środowiskowych i ciągów połączeń po stronie wywołującego bez Wasm.pipeline: sekwencyjna tablica kroków wtyczek WebAssembly (Wasm) służących do modyfikacji Workload po renderowaniu (np. wstrzyknięcia sidecara Envoy za pomocą JSONPatch lub zamontowania woluminu z sekretem). Polepluginkażdego kroku wskazuje encjęPluginpo jej URI, zawsze w zakresie typu gniazda samej wtyczki (<pluginType>/<name>, opcjonalnie z wersją, jak wparser/yamllubparser/yaml:1.0.0); kompilacja rozwiązuje encję do jej adresowanego treścią artefaktu.wasm, lokalizowanego na podstawie tożsamości wtyczki i skonfigurowanego rejestru, a sam plik.wasmani odwołanie do artefaktu nie są tu akceptowane. Zobacz przewodnik dla twórców wtyczek Wasm, aby dowiedzieć się, jak tworzyć wtyczkę i się do niej odwoływać, oraz architecture/04-entity-taxonomy.md §„Domain 3: Infrastructure Base”, gdzie opisano zasadę dwuczęściowej wtyczki (Fetcher / Injector). Kompilator wykonuje kroki w zadeklarowanej kolejności: wywołuje eksport gościa wskazanej wtyczki na wyrenderowanym wyniku i stosuje zwrócone poprawki JSON Patch oraz wyemitowane efekty uboczne; stan wykonania każdej powierzchni potoku opisano w Status of the Language. Blokpipeline:jest samodzielny: FeatureRecipe może zadeklarować go bez żadnego rodzaju wejścia — wówczas nie emituje własnych zasobów, a cały jej efekt to to, co jej kroki nanoszą jako poprawki na dokumenty już wyrenderowane przez kompilację lub emitują obok nich.
Encja FeatureRecipe może też nie zawierać żadnego z tych bloków: czysto łącząca encja Feature, której efektem jest krawędź uses, nic nie renderuje, a jej FeatureRecipe istnieje wyłącznie po to, by spełnić rozwiązywanie — każda instancja funkcji rozwiązuje się do encji FeatureRecipe, tak samo jak każdy komponent rozwiązuje się do encji Recipe. Spośród powyższych bloków injectMapping jest jedynym polem bez odpowiednika w bazowej encji Recipe; trzy rodzaje wejścia oraz pipeline są wspólne z bazową encją Recipe.
To, co jest przypinane obok encji FeatureRecipe, jest tym samym, co obok encji Recipe: skrót każdego pliku importowanego przez wpis artifacts oraz każdego zdalnego source:, którego współrzędne zapisano w pełni, w pliku entity.lock we własnym katalogu encji FeatureRecipe, który zapisuje aggrega pin i który należy zatwierdzić obok niej. Pobranie encji FeatureRecipe, której plik blokady nie zawiera tych przypięć, zatrzymuje się i wskazuje ten krok, chyba że pobranie ma go wykonać. Kompilacja zatrzymuje się, gdy importowany plik przestaje odpowiadać swojemu skrótowi oraz gdy skrót źródła różni się od zapisanego w pliku blokady encji Release (źródło zapisane z git ref: jest rejestrowane przy commicie, do którego zostało rozwiązane, i nie jest porównywane); sam plik encji FeatureRecipe nigdy nie jest modyfikowany. aggrega pull opisuje ten plik i sposób reagowania na każde zatrzymanie.
Szablonowanie pola source
Pole source: encji FeatureRecipe jest powierzchnią szablonowania na tych samych zasadach co w encji Recipe: szablon jest obliczany podczas rozwiązywania źródła, a to, co wygenerował, jest tym, co kompilacja następnie rozwiązuje. Oba kształty przyjmują szablony Go — postać uniwersalnego ciągu znaków oraz postać obiektu strukturalnego, którego podpola o wartościach tekstowych są obliczane jako szablony, a podpola nietekstowe przechodzą bez zmian. Inwentarz kształtów, obsługa schematów i sposób zakotwiczania są takie, jak opisano w entities/recipe.md „Source field templating”, „Source field scheme inventory” i „How a source: path is anchored”; ta sekcja opisuje jedynie to, co różni się w przypadku dołączenia.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Względem czego rozwiązywany jest wynik względny. Względem katalogu zawierającego dokument FeatureRecipe, który go zadeklarował — własnego pliku dołączenia, nigdy pliku komponentu — a wynik musi pozostać wewnątrz tego katalogu, dokładnie tak jak w encji Recipe: wynik, który z niego wychodzi lub jest ścieżką bezwzględną, wskazuje plik, który nie przemieszczałby się razem z encją FeatureRecipe, i zatrzymuje build. Wynik zawierający schemat transportu jest pobierany, a nie łączony z katalogiem. Encja FeatureRecipe rozwiązana z rejestru jest odczytywana z plików, które zawiera jej opublikowane archiwum, rozmieszczonych w pamięci podręcznej treści, więc wynik względny rozwiązuje się wewnątrz tego, co opublikowano, dokładnie tak, jak rozwiązuje się obok encji FeatureRecipe w katalogu katalogu encji, z zachowaniem tego samego ograniczenia.
Co może odczytywać szablon. Zbiór referencji jest tym samym, względem którego sprawdzane są własne wpisy locals: encji FeatureRecipe, i różni się od zbioru encji Recipe na dwa sposoby, wynikające z tego, że rozwiązywane jest dołączenie, a nie komponent:
.attachment_namejest dostępne i wskazuje nazwę instancji, pod którą dołączono encję Feature. Szablon źródła encji Recipe go odrzuca, ponieważ źródło encji Recipe jest rozwiązywane dla węzła i żadne dołączenie nie bierze w tym udziału..context.instance_idwskazuje komponent hosta, dla którego rozwiązywane jest dołączenie, a nie samo dołączenie, a.context.rendered_namezawiera nazwę, którą własny dostawca hosta zgłasza dla hosta — obecną tylko tam, gdzie ten dostawca ją zgłasza, i zatrzymującą build tam, gdzie tego nie robi. Zob. Nazywanie wyrenderowanego zasobu.
.locals zawiera zbiór odczytywany przez pozostałe szablony tej encji FeatureRecipe: jej własny rozwiązany blok, a pod nim blok encji Recipe hosta, więc klucz zadeklarowany przez dołączenie ma pierwszeństwo przed kluczem hosta o tej samej nazwie. Odwołanie do klucza, którego ten zbiór nie zawiera, zatrzymuje build i wskazuje ten klucz, zamiast go pominąć przy renderowaniu. .provides, .context.inject i .context.uses są odrzucane z tych samych powodów samowystarczalności, z jakich odrzuca je powierzchnia źródła encji Recipe.
Encja FeatureRecipe o zakresie granicy odczytuje zamiast tego granicę. Encja Feature, której FeatureRecipe deklaruje executionScope: boundary, renderuje się raz dla granicy, a nie raz na komponent, więc jej szablon źródła nie ma komponentu hosta do odczytania. Odczytuje .boundary.* — te same filary, które odczytują jej locals: i provides: — a filary poszczególnych komponentów (.context, .workload, .attachment_name, .inject) są dla niej niedostępne.
Pusty wynik. Szablon, który nic nie generuje, pozostawia dołączenie bez źródła, co oznacza tryb bez źródła — tak samo interpretowane jest źródło encji Recipe, a różni się to od samodzielnego zapisania source: "".
Co .source odczytuje później. Źródło jest obliczane przed valuesMapping:, tak jak w encji Recipe źródło jest obliczane przed jej własnym, a to, co wytworzyło, jest dostępne jako .source w każdym szablonie uruchamianym po nim: w valuesMapping:, w omits:, w treściach workload: i artifacts: oraz w krokach pipeline:. Zatem valuesMapping: odczytujący .source odczytuje własne źródło tej encji FeatureRecipe, nigdy źródło komponentu, do którego jest ona dołączona, i nie odczytuje niczego, gdy ta encja FeatureRecipe nie deklaruje źródła lub jej szablon nic nie wytwarza. Encja FeatureRecipe o zakresie boundary odczytuje własne źródło w ten sam sposób. injectMapping: jest uruchamiany przed obliczeniem źródła dołączenia, więc .source oznacza tam źródło komponentu-hosta.
Wyłączność injectMapping
Pole injectMapping jest dostępne wyłącznie w encjach FeatureRecipes — celowo nie występuje w bazowym schemacie Recipe. Ta wyłączność oddziela przechwytywanie zmiennych od valuesMapping: pole valuesMapping bazowej encji Recipe, nie wiedząc o tym, konsumuje przepisane ciągi .context.inject wygenerowane przez bloki injectMapping encji FeatureRecipe, dzięki czemu oba pozostają rozprzęgnięte. Opis działania tego mechanizmu znajduje się w poniższej sekcji o przechwytywaniu inject-mapping, a pełną semantykę przechwytywania przed renderowaniem opisuje fragment o inject mapping w architecture/10-compilation-pipeline.md.
Przechwytywanie inject mapping: jak działa injectMapping
Gdy element wywołujący potrzebuje ciągu połączenia do swojego celu w innej postaci niż niezmodyfikowane .provides.host celu — z dołączoną przestrzenią nazw dla DNS Kubernetes przekraczającego granice, z prefiksem kodu regionu dla bramy wieloregionowej lub z sufiksem trybu SSL dodanym do DSN — injectMapping obsługuje tę mutację po stronie wywołującego, zanim valuesMapping bazowej encji Recipe w ogóle zobaczy potok inject.
Pole injectMapping to szablon Go text/template, który renderer ewaluuje na etapie inject mapping, zanim uruchomi się renderowanie bazowej encji Recipe. Szablon zwraca słownik JSON lub YAML z opcjonalnymi kluczami mechanizmu (env, file, arg albo niestandardowy mechanizm, który encja Recipe komponentu odczytuje pod .context.inject.<name>) — albo płaską mapę, która domyślnie trafia do env — a renderer głęboko scala tę nakładkę z potokiem .context.inject węzła wywołującego. Routing po stronie wywołującego za pomocą injectMapping działa na etapie inject mapping bez uruchamiania piaskownicy Wasm dla prostych operacji na ciągach; pluginy Wasm pozostają zarezerwowane dla strukturalnych zmian AST za pomocą tablicy pipeline.
Każdą wartość należy zapisywać przez toJson. Renderer odczytuje wynik szablonu jako YAML, więc wartość wstawiona w niezmienionej postaci między cudzysłowy albo psuje ten wynik, albo zostaje odczytana z powrotem w zmienionej postaci, gdy tylko zawiera cudzysłów podwójny lub ukośnik odwrotny — typowym przypadkiem jest hasło. toJson zapisuje wartość jako ciąg JSON, który YAML odczytuje dokładnie, więc wartość zostaje dostarczona ze wszystkimi znakami, które zawiera:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}Wartość składaną z kilku części należy najpierw złożyć, a następnie zapisać przez toJson jeden raz, tak jak w poniższych przykładach.
Wynik, którego nie można odczytać, zatrzymuje kompilację. Gdy wyniku szablonu nie da się odczytać w żadnej z dwóch postaci — typową przyczyną jest skalar w cudzysłowie zepsuty przez wartość wewnątrz niego — żaden z jego kluczy nie mógłby zostać dostarczony, więc kompilacja zatrzymuje się, wskazując dołączenie i encję FeatureRecipe, zamiast renderować komponent tak, jakby nic nie zostało dostarczone; zob. fatal-halts.md „An attached Feature’s injectMapping output cannot be read (Nie można odczytać wyniku injectMapping dołączonej encji Feature)”. Podawana przyczyna jest ukrywana, gdy zależy od wartości zadeklarowanej jako wrażliwa. Wynik pusty albo parsowany jako słownik, który niczego nie dostarcza, nie dostarcza niczego i nie jest błędem.
Klucz najwyższego poziomu jest mechanizmem, a all nim nie jest. Każdy klucz najwyższego poziomu wyniku w postaci słownika nazywa mechanizm, przez który dostarczane są jego wpisy: env, file i arg lub dowolna inna nazwa, dostarczana jako osobny mechanizm pod tą nazwą. .context.inject.all jest budowane z tych mechanizmów po scaleniu i nigdy nie jest scalane z wyniku, więc wpisy zapisane pod all: nie trafiłyby nigdzie; zamiast tego kompilacja zatrzymuje się, wskazując dołączenie, klucz i encję FeatureRecipe oraz podając, jakie klucze może zawierać wynik — zob. fatal-halts.md „An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Wynik injectMapping dołączonej encji Feature zapisuje dostarczenia pod kluczem, którego nic nie dostarcza)”. Takie wpisy należy zapisywać pod mechanizmem, z którego komponent je odczytuje.
Mutacja jest ściśle lokalna dla wywołującego. FeatureRecipe modyfikuje wyłącznie potok inject węzła, do którego jest dołączony, nigdy wyjście .provides celu. Wartość .provides.host celu może być konsumowana przez wielu wywołujących w całym klastrze; injectMapping po stronie wywołującego scala dane tylko z potokiem konkretnego wywołującego, więc mutacje routingu pozostają ograniczone do krawędzi, która ich zażądała.
Co może przepisać mapowanie. W chwili renderowania mapowań każdy blok inject: dostarczył już swoje dane, więc wyjście mapowania jest zawsze scalane z kluczami, które zapisało już coś innego — a to, kto zapisał klucz, decyduje o tym, co się stanie. Klucz dostarczony przez własny blok inject: wywołującego lub przez blok inject: jednego z jego połączeń mapowanie może przepisać: to jest przechwytywanie, a wartość mapowania zastępuje ten jeden wpis. Klucz, który własne dołączenie mapowania dostarczyło przez swój blok inject:, również może ono przepisać. Klucza, który dostarczył już inny dołączony Feature — przez własny blok inject: lub przez injectMapping własnego FeatureRecipe — przepisać nie może: kompilacja zostaje zatrzymana z podaniem obu dołączeń, zamiast pozwolić, by o tym, którą wartość odczyta wywołujący, zdecydowało mapowanie uruchomione jako ostatnie. Dwa Features routingu mogą więc każdy kwalifikować własny klucz, ale dwa Features nie mogą dostarczyć tego samego klucza — dotyczy to także dwóch Features routingu przepisujących klucz tego samego połączenia, ponieważ pierwszy jest przechwyceniem, a drugi trafia na dostarczenie pierwszego; zob. fatal-halts.md „Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Dwa dołączone Features dostarczają jeden klucz, późniejszy przez injectMapping swojego FeatureRecipe)”.
Wnioskowanie o celu bez sprzężenia
Ponieważ kompilator osadza kaskadowe adnotacje każdego celu w potoku .context.uses wywołującego, szablon injectMapping może wyodrębnić współrzędne routingu bez konieczności zapisywania przez zespół Ops tożsamości celu na sztywno w infra encji Feature:
- Szablon przeszukuje
.context.uses, aby znaleźć dokładną krawędź topologiczną, która wstrzyknęła zmienną żądaną przez dewelopera. - Wyodrębnia kaskadowe
release_annotationscelu (np.aggrega.ai/namespace). - Formatuje w pełni kwalifikowaną nazwę domeny (FQDN) lub ciąg połączenia.
- Emituje słownik nadpisań.
Kompilator pozostaje agnostyczny wobec semantyki sieciowej — przestrzeni nazw Kubernetes, regionów chmury, topologii bridge-proxy — i po prostu wykonuje głębokie scalenie z tym, co wygenerował szablon. Gdy następnie uruchamia się valuesMapping bazowej encji Recipe, konsumuje przechwycone, przepisane ciągi z .context.inject.env tak, jakby były oryginałami dewelopera.
Przykład praktyczny: resolver DNS K8s
Standardowy katalog dostarcza to jako core/k8s-dns-resolver z FeatureRecipe dla helm. Ponieważ nazwy zmiennych środowiskowych muszą być unikalne w obrębie kontenera, target_var (np. API_HOST) działa jako globalnie unikalny identyfikator konkretnego kontraktu wstrzykiwania w obrębie wywołującego. Iterując po jawnych krawędziach w .context.uses i sprawdzając, która krawędź zgłosiła target_var, szablon lokalizuje właściwy węzeł docelowy i odczytuje jego przestrzeń nazw. Jedynym parametrem jest zmienna do przepisania; cel i jego przestrzeń nazw są wykrywane, nigdy zapisywane na sztywno.
Schemat encji Feature routingu (core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}Implementacja FeatureRecipe:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}Zastosowania wykraczające poza routing
injectMapping najczęściej służy do rozwiązywania adresów między granicami (jak w powyższym resolverze DNS K8s), ale ta mutacja po stronie wywołującego ma zastosowanie w każdym scenariuszu, który wymaga przechwycenia i sformatowania intencji dewelopera przed renderowaniem infrastruktury. Zakres ilustrują dwa kolejne wzorce.
Dynamiczne formatowanie zabezpieczeń (dopisywanie trybu SSL). Jeśli przedsiębiorstwo wymaga, aby wszystkie zewnętrzne połączenia z bazami danych używały ścisłej weryfikacji TLS, encja Feature może przechwycić żądaną przez dewelopera zmienną DB_URL i dopisać wymagany tryb SSL, tak aby aplikacja uruchamiała się z prawidłowymi parametrami bezpieczeństwa.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}Prefiksowanie bram wieloregionowych. Jeśli ogólny komponent API jest wdrażany globalnie, regionalna encja Feature odpowiedzialna za routing może samodzielnie odczytać adnotacje granicy własnego środowiska, aby poprzedzić prefiksem wstrzykiwane ciągi połączeń dla swoich wywołujących.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}Granica injectMapping. Mechanizm ogranicza się do mutowania potoku pamięci .context.inject (kontraktu dostarczania). Nie może dodawać nowych kontenerów, montować wolumenów ani zmieniać wyniku valuesMapping bazowej encji Recipe. Każda mutacja wymagająca zmian strukturalnych w wyrenderowanym AST (np. tablic JSON lub YAML) należy do tablicy pipeline encji FeatureRecipe i jest wykonywana przez wtyczki WebAssembly.
Granica celów łatek w pipeline. Krok pipeline łata wyłącznie dane wyjściowe, które provider renderuje do ustrukturyzowanego drzewa. Dane wyjściowe w postaci YAML i JSON są ustrukturyzowane — łącznie z modułami Terraform .tf.json pisanymi w JSON — więc JSONPatch kroku edytuje adresowane wartości w miejscu, pozostawiając każdy inny bajt (komentarze, kolejność, formatowanie) nietknięty. Dane wyjściowe, które provider emituje jako nieprzezroczystą treść, takie jak konfiguracja Terraform w natywnym HCL, nie są celem łatek: łatka zastosowana do nieprzezroczystej treści zatrzymuje kompilację z komunikatem diagnostycznym, zamiast modyfikować tekst, którego nie da się zaadresować strukturalnie. Napisanie kroku pipeline dla nieprzezroczystych danych wyjściowych jest zatem błędem projektowym ujawnianym jako głośne zatrzymanie, a nie cicha pusta operacja.
Dane wejściowe dołączonego modułu Terraform nie są celem łatki i warto ten brak wyraźnie zaznaczyć. Są to argumenty bloku module danego komponentu, które provider terraform zapisuje w konfiguracji głównej granicy: natywny HCL, a więc nieprzezroczysty według powyższej zasady, i artefakt całej granicy, a nie węzła, którego wynik łata krok. Nie istnieje więc miejsce, z którego krok pipeline mógłby je zaadresować, ani nic, co mógłby zrobić, aby zmienić to, co otrzymuje pobrany moduł Terraform. Te wartości kształtuje się tam, gdzie są definiowane — w valuesMapping: bazowej encji Recipe.
Kroki warunkowe — when:
Krok pipeline może zawierać opcjonalne pole when:: wbudowany szablon Go, który kompilator ewaluuje w czasie przechodzenia potoku, względem tego samego kontekstu szablonu i tego samego ewaluatora, których używa treść with: danego kroku. Wyrenderowany wynik decyduje, czy krok zostanie wykonany.
- Wynik fałszywy pomija krok jako przejście bez zmian: zbiór dokumentów trafia do następnego kroku niezmieniony, a pominięty krok nie wnosi niczego — żadnej łaty, żadnego efektu ubocznego, żadnego śladu wykonania.
- Puste lub nieobecne pole
when:zawsze powoduje wykonanie kroku.
when: i optional: są od siebie niezależne. when: decyduje, czy krok w ogóle zostanie wykonany; optional: łagodzi niepowodzenie kroku, który jest wykonywany. Krok może deklarować oba pola — when: kontroluje wejście, a jeśli krok zostanie wykonany, optional: określa, jak obsłużyć niepowodzenie wewnątrz niego. Szablon when:, którego nie da się wyrenderować, jest błędem autorskim i zatrzymuje kompilację niezależnie od optional:.
Wyrenderowany tekst when: jest oceniany według wspólnej reguły szablonów logicznych: ciągi true, True i TRUE, każda liczba niezerowa oraz każdy inny niepusty ciąg są prawdziwe; ciągi false, False i FALSE, pusty ciąg oraz liczba zero są fałszywe.
Wzorzec FeatureRecipe dla poświadczeń
Gdy FeatureRecipe implementuje Feature poświadczeń (oznaczoną etykietą feature.aggrega.ai/kind: secret), może stosować zasadę dwuczęściowego Plugin: pipeline łączący w łańcuch plugin Fetcher (generujący CRD specyficzny dla danego sejfu) i plugin Injector (montujący sekret w kontenerze docelowym), czyli kształt opisany w examples/04-secrets. Encje FeatureRecipes poświadczeń z biblioteki standardowej nie deklarują pipeline: i same renderują zasób sekretu; zob. examples/05-credential-features.
FeatureRecipe poświadczeń jest renderowana w tym samym przebiegu Resource Generation co każde inne powiązanie, a jej pipeline: wykonuje się na tych samych zasadach: kompilator przechodzi przez wszystkie powiązania, które mają w tym przebiegu coś do zrobienia, jako jedną uporządkowaną sekwencję i uruchamia zadeklarowany pipeline każdego z nich, z tą samą semantyką zbiorów dokumentów /own i /host. Powiązanie dołącza do tej sekwencji z jednego z dwóch powodów — jego FeatureRecipe deklaruje rodzaj wejścia, więc generuje własne zasoby, albo deklaruje pipeline:, więc przepisuje dokumenty już wyemitowane. Powiązanie poświadczeń może zatem sięgać do wyrenderowanych dokumentów komponentu hosta — montując wolumin z sekretem, dodając odwołanie do zmiennej środowiskowej — dokładnie tak jak powiązanie operacyjne, a jedyna różnica między nimi polega na tym, gdzie trafiają jego własne wygenerowane pliki.
W przypadku komponentu deklaracja wrażliwości w encji Feature podąża za valuesMapping: encji FeatureRecipe dokładnie tak, jak deklaracja encji Component podąża za mapowaniem jej encji Recipe. Gdy FeatureRecipe renderuje z source: bez valuesMapping:, wartości otrzymywane przez cel są kluczowane ścieżkami liści deklarowanymi przez Feature, więc liść zadeklarowany jako sensitive: true oznacza swój wyrenderowany klucz. Gdy FeatureRecipe deklaruje valuesMapping:, klucze są własnym wymysłem tego szablonu, żadna deklaracja ich nie nazywa, a kompilacja wypisuje jedno ostrzeżenie na każdy taki liść, podając powiązanie, liść i FeatureRecipe. Feature powiązana z granicą nie generuje żadnego: jej .values jest zawsze puste, więc żaden zadeklarowany liść nie ma wartości do oznaczenia — zob. A declared-sensitive value reaches the target through a values mapping (Wartość zadeklarowana jako wrażliwa trafia do celu przez mapowanie wartości).
Blok provides: — publikowanie dla konsumenta
Blok provides: encji FeatureRecipe to jej opublikowany wynik: mapa szablonów Go o wartościach tekstowych, ewaluowanych w zakresie samego przyłączenia (.values, .infra, w pełni rozwiązane .locals encji FeatureRecipe oraz .context.instance_id i .context.rendered_name węzła hosta). Zmienne lokalne są rozwiązywane najpierw, więc wpis bloku provides: je odczytuje i otrzymuje rozwiązane wartości; odwołanie do klucza, którego blok locals: nie deklaruje, zatrzymuje kompilację. W ten sposób przyłączenie informuje konsumenta o tym, co wytworzyło — nazwie wyemitowanego zasobu, wygenerowanym kluczu danych, tożsamości w chmurze — bez konieczności ponownego wyprowadzania tej tożsamości przez konsumenta z tych samych danych wejściowych.
Konsument odczytuje ją pod .features.<instance-name>.provides.<key> (lub .features.<slot>.provides.<key> w przypadku przyłączenia poświadczeń), analogicznie do .context.uses.<alias>.provides dla krawędzi uses. Gdy przyłączenie jest zapisane na jednym z połączeń konsumenta, konsument odczytuje tę samą mapę w ramach tego połączenia, pod .context.uses.<alias>.features.<slot>.provides.<key>, a przyłączenia nie ma wśród jego .features (zob. Przyłączenia połączenia). Własny blok inject: przyłączenia rozwiązuje swoje odwołania from: względem tej samej mapy, więc autor może wybrać dowolny kanał: provides do odczytu w szablonie, inject do dostarczenia do zmiennej środowiskowej, pliku lub argumentu.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"Gdy encja Feature, którą ta encja FeatureRecipe implements, deklaruje kontrakt schema.provides, kontrakt jest egzekwowany wobec encji FeatureRecipe: każdy klucz zadeklarowany przez Feature musi wystąpić w bloku provides: encji FeatureRecipe, w przeciwnym razie kompilacja zatrzymuje się, podając brakujący klucz. Dodatkowe opublikowane klucze są dozwolone — kontrakt wyznacza minimum, a nie maksimum. Wartości nigdy nie są analizowane; są nieprzezroczystymi, deterministycznymi wskaźnikami rozwiązywanymi przez środowisko uruchomieniowe.
Rozwiązanie następuje raz na przyłączenie, zanim konsument zostanie wyrenderowany, a ta sama rozwiązana mapa zasila odczyt konsumenta, sprawdzenie kontraktu i własny etap Resource Generation przyłączenia — dlatego to, co odczytuje konsument, i to, co emituje przyłączenie, nie może się różnić.
Provider i implements
spec.capability jest wymagane i wskazuje dostawcę, którego plugin renderujący Wasm renderuje wynik encji FeatureRecipe (helm, helm-chart, compose itd.), na tych samych warunkach co spec.capability encji Recipe (zob. entities/recipe.md): przypięcie wersji wybiera, która wersja tego pluginu renderuje wynik, i nie jest częścią nazwy encji FeatureRecipe — Manifest mapuje encję FeatureRecipe deklarującą capability: "compose:1.2.3" jako compose/<name>:<version>, a wartość mapowania, która wpisuje przypięcie do nazwy, jest odrzucana jako niepoprawne odwołanie do receptury (E0095), zanim cokolwiek zostanie wyszukane. Pole implements wiąże encję FeatureRecipe z jej interfejsem Feature i obsługuje dopasowanie dokładne, dopasowanie do zakresu zgodnego w obrębie wersji głównej lub dopasowanie bez wersji — semantykę dopasowywania wersji w implements opisuje vocabulary/inheritance-and-interface.
Zakres wykonania — spec.executionScope
Opcjonalne wyliczenie spec.executionScope wybiera model wywoływania dla Resource Generation. Akceptowane są dwie wartości; gdy pole zostanie pominięte, wartością domyślną jest component.
component(domyślnie). Resource Generation encji FeatureRecipe uruchamia się raz na każdą dołączoną instancję komponentu. Każde wywołanie otrzymuje osobny dla komponentu kontekst szablonu zakorzeniony w.context.*:.context.instance_id,.context.inject,.context.uses,.context.annotationsitd. JejvaluesMapping:,workload:iartifacts:odczytują również.context.used_by, czyli komponenty, których wpisyuseswskazują na hosta — każdy z jego tożsamością, gniazdem, tym, co publikuje, oraz przestrzenią nazw i granicą, w których jest umieszczony — czego nie widzi żaden szablon renderowany przez samego hosta.boundary. Resource Generation uruchamia się raz na każdą dołączoną granicę, niezależnie od tego, ile komponentów w poddrzewie granicy korzysta z funkcji. Każde wywołanie otrzymuje kontekst szablonu w zakresie granicy, zakorzeniony w.boundary.*zamiast.context.*.
Opisane wyżej przechwytywanie injectMapping działa zawsze osobno dla każdego konsumenta, niezależnie od executionScope. Każdy komponent korzystający z funkcji nadal otrzymuje własne przepisanie .context.inject po stronie wywołującego. Tylko krok Resource Generation (source/valuesMapping i tablica pipeline) jest deduplikowany w zakresie granicy.
Szablony encji FeatureRecipe o zakresie granicy działają więc w dwóch zakresach. Jej injectMapping uruchamia się raz dla każdego komponentu, do którego sięga dołączenie, w kontekście tego komponentu — tym samym, który odczytuje injectMapping encji FeatureRecipe o zakresie komponentu: .context.*, .attachment_name, .features oraz własne .values, .infra i .locals dołączenia. Jej .infra to blok infra: dołączenia do granicy, a jej .locals to blok obliczony raz dla granicy. Każdy inny szablon, który zapisuje — w tym jej locals:, provides:, source:, valuesMapping: i artifacts: oraz with: i when: kroków jej potoku — uruchamia się raz dla granicy, w opisanym niżej kontekście zakresu granicy. Każdy szablon jest sprawdzany względem zakresu, w którym działa: valuesMapping: odczytujące .context.instance_id zatrzymuje kompilację, a injectMapping, które je odczytuje, renderuje tożsamość tego komponentu. .boundary nie jest ustawiane w kontekście żadnego komponentu, więc injectMapping, które je odczytuje, zatrzymuje kompilację, wskazując odwołanie, niezależnie od executionScope encji FeatureRecipe.
Kontekst szablonu w zakresie granicy
Gdy ustawiono executionScope: boundary, szablony encji FeatureRecipe inne niż jej injectMapping są obliczane względem widoku .boundary.* granicy, do której dołączono funkcję. Widok udostępnia:
.boundary.path— ścieżka granicy encji Release, do której dołączono funkcję: nazwy granic od najbardziej zewnętrznej do wewnątrz, połączone znakiem/(bridge,bridge/frontend). Wskazuje granicę, a nie katalog, do którego zapisywany jest jej wynik — ten ustawiadirectory:(zastępuje.context.instance_id)..boundary.assembly_path— katalog, względem katalogu wyjściowego kompilacji, do którego asemblowany jest własny wynik dołączenia: obliczonedirectory:isubDirectory:granicy, czyli katalog, do którego kompilacja kieruje ten wynik (bridge/compose). Jest równysource_assembly_pathlubtarget_assembly_pathkońca połączenia dokładnie wtedy, gdy ten koniec renderuje się do tego samego zasemblowanego pliku, więc encja FeatureRecipe porównuje je, aby odróżnić połączenie wewnątrz własnego pliku od połączenia w innym pliku..boundary.boundary_name— nazwę granicy nadaną przez autora w encji Release..boundary.components— mapę kluczowaną identyfikatorem instancji, zawierającą każdy komponent w poddrzewie granicy (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— krawędzieuses:, których oba końce znajdują się w poddrzewie tej granicy (wzorzec compose-bridge wylicza je, zachowując krawędzie, których oba końce są asemblowane do jego własnego pliku compose i umieszczone w różnych sieciach tego pliku, aby wyprowadzić konfigurację proxy dla każdej krawędzi). Każda krawędź niesie rozwiązane provides swoich końców, wstrzyknięte zmienne środowiskowe oraz umiejscowienie każdego końca:source_namespaceitarget_namespace, czyli adnotacjęaggrega.ai/namespaceobowiązującą dla danego końca — ustawienie z jego własnego wpisu w encji Release, jeśli istnieje, a w przeciwnym razie ustawienie jego granicy;source_boundary_pathitarget_boundary_path, czyli ścieżkę granicy encji Release, która go zawiera; orazsource_assembly_pathitarget_assembly_path, czyli katalog w katalogu wyjściowym kompilacji, do którego jego dostawca go asembluje, złożony z obliczonychdirectory:isubDirectory:jego granicy (bridge/compose). Dwa końce o jednej ścieżce asemblacji renderują się do jednego zasemblowanego pliku, a dostawca compose odczytuje ścieżkę asemblacji jako sieć końca, gdy nie obowiązuje żadna przestrzeń nazw..boundary.outgoing_cross_boundary_uses_edges— krawędzie ze źródłem wewnątrz poddrzewa i celem poza nim..boundary.incoming_cross_boundary_uses_edges— krawędzie z celem wewnątrz poddrzewa i źródłem poza nim (używane przez agregatory w stylu ingress)..boundary.cross_boundary_uses_edges— sumę przychodzących i wychodzących krawędzi międzygranicznych, gdy encja FeatureRecipe potrzebuje pełnego widoku międzygranicznego..boundary.labels— sumę etykiet poddrzewa z zachowaniem kolejności nadanej przez autora..boundary.annotations— własne adnotacje granicy wraz z kaskadą..boundary.feature_attachments— każdą funkcję dołączoną do tej granicy (aby FR w zakresie granicy mogła w razie potrzeby zbadać rodzeństwo).
Filar .infra w FR w zakresie granicy rozwiązuje się do bloku infra: funkcji dołączonej do granicy (fizyczne wymiarowanie dla tego dołączenia do granicy, określone przez autora po stronie encji Release). .values jest zawsze puste dla FR w zakresie granicy: reguła podziału filarów w schemacie encji Release zabrania values: w dołączeniach encji Feature na poziomie encji Release, więc funkcja dołączona do granicy nie niesie żadnych wartości do rzutowania. FR w zakresie granicy, które potrzebują danych o kształcie parametrów, powinny pobierać je przez .infra (powierzchnię, na której operator konfiguruje funkcje granicy) albo przez .boundary.annotations (wartości tekstowe rozwiązywalne kaskadowo, określone na granicy lub dowolnym przodku); .parameters nie jest częścią widoku, a szablon, który je odczytuje, zatrzymuje się, wskazując korzenie definiowane przez widok. .locals nadal jest własnym blokiem locals danej FR. .steps i .metadata pozostają bez zmian.
Lista dozwolonych pól szablonu w zakresie granicy
FR w zakresie granicy mogą we wszystkich szablonach poza injectMapping odwoływać się wyłącznie do pól dostępnych w widoku zakresu granicy. Taki szablon odwołujący się do pola dostępnego tylko dla komponentu (np. .context.instance_id, .context.inject, .context.uses) przy executionScope: boundary powoduje, że encja FeatureRecipe nie przechodzi walidacji podczas parsowania, a błąd wskazuje FR, niedozwolone pole oraz pola definiowane przez widok zakresu granicy. Lustrzana reguła działa w drugą stronę: FR w zakresie komponentu odwołująca się do pól .boundary.* nie przechodzi tego samego walidatora. injectMapping jest w obu zakresach sprawdzane względem kontekstu komponentu, w którym działa, więc może odczytywać .context.*, a odwołanie do .boundary w nim zatrzymuje się, wskazując odwołanie i korzenie definiowane przez ten kontekst.
Walidator wykonuje to samo przejście po AST szablonu, którego używa lista dozwolonych zmiennych szablonów ścieżek, z innym zbiorem odwołań dla każdego zakresu.
Deduplikacja i wynik Resource Generation
Dla executionScope: boundary kompilator deduplikuje Resource Generation według krotki (boundary_path, FR-instance). Dwa komponenty w tym samym poddrzewie granicy, korzystające z tej samej funkcji dołączonej do granicy, wywołują FR jeden raz, a nie dwa. Dołączenia tej samej funkcji w różnych granicach działają niezależnie dla każdej granicy.
FR w zakresie granicy emituje jeden zestaw plików niepośrednich na każdą krotkę (boundary_path, FR-instance), a ich położenie wynika z tego, jak dostawca łączy wynik swojej granicy. Współrzędną jest tu sama nazwa instancji, podczas gdy dołączenie w zakresie komponentu niesie również swój komponent: funkcja w zakresie granicy jest dołączona do granicy, a nie do żadnego komponentu, więc obejmujący katalog granicy mówi już wszystko, co powiedziałby segment komponentu, i nie ma komponentu do nazwania.
Dostawca, który zapisuje każdy dokument bezpośrednio w katalogu granicy, deklaruje, że jego cel odczytuje tylko pliki leżące bezpośrednio w katalogu. Nie ma więc obejmującego katalogu, w którym mogłoby leżeć dołączenie, i nazwa instancji staje się zamiast tego prefiksem nazwy pliku: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, obok własnych plików granicy. Nazwa instancji jest kodowana, ponieważ nazwa pliku nie ma separatora, na którym można by się oprzeć, i styka się z własną nazwą pliku na dwuznakowej granicy, której nie może zawierać żadna zakodowana współrzędna — dzięki temu dwa dołączenia emitujące tę samą nazwę pliku nadal trafiają do dwóch plików.
Dostawca, który składa wynik swojej granicy w obejmującą strukturę — jeden chart zawierający chart dla każdego współtwórcy, jedna główna konfiguracja zawierająca moduł dla każdego współtwórcy — umieszcza każdego współtwórcę we własnym podkatalogu, a dołączenie do granicy jest współtwórcą jak każdy inny. Jego wynik trafia wtedy do <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, gdzie <contributors-directory> to nazwa, jaką dany cel nadaje miejscu, w którym żyją jego jednostki podrzędne. Podkatalog nosi nazwę instancji dołączenia, czyli nazwę, pod którą zapisano je w bloku features: granicy, więc katalog wygenerowany przez kompilację można odnaleźć w tym, co napisał autor.
Wynik pośredni trafia do asemblera granicy działającego dla każdej pary (ścieżka, dostawca), w obliczonej ścieżce FR, pod własnym spec.capability tej FR — to mechanizm, którego Feature core/compose-bridge używa do scalenia usługi mostu z należącymi do poszczególnych komponentów współtwórcami compose w tej samej ścieżce asemblacji. Taki wynik jest zapisywany wyłącznie jako część pliku asemblowanego tam z komponentów granicy, więc gdy żaden z nich nie trafia do tej ścieżki — na przykład każdy komponent jest kierowany gdzie indziej przez swoje subDirectory: — kompilacja zatrzymuje się, wskazując granicę, Feature, ścieżkę, do której skierowano jej wynik, oraz dostawcę, zamiast zapisywać wynik donikąd (zob. „A boundary-level Feature’s output reaches no assembled file (wynik Feature na poziomie granicy nie trafia do żadnego zasemblowanego pliku)” w fatal-halts.md).
Rozwiązywanie provides: uwzględniające kaskadę
FR o zakresie granicy tworzą jeden zestaw provides: na krotkę (boundary_path, FR-instance), obliczany raz. Szablon provides: danego FR jest obliczany z kontekstem szablonu o zakresie granicy (może więc odwoływać się do .boundary.components, .boundary.path, .infra, ale nie do pól per konsument ani do .values). Wartości provides są stałe względem konsumentów — każdy konsument w poddrzewie granicy widzi te same udostępniane wartości.
Rozwiązywanie provides FR o zakresie granicy po stronie konsumenta wszędzie odczytuje to jedno obliczenie. Każdy komponent, do którego sięga dołączenie, odczytuje je pod .features.<instance-name>.provides.<key> — w szablonach własnej encji Recipe oraz we własnym injectMapping encji FeatureRecipe, które działa w kontekście tego komponentu. Konsument Component odczytujący przez krawędź uses, którą niesie dołączenie, pod .context.uses.<feature-alias>.provides.<provided-name>, otrzymuje te same wartości: kompilator rozwiązuje to do provides: encji FeatureRecipe o zakresie granicy dla granicy, w której znajduje się konsument, przechodząc od krawędzi uses konsumenta — która niesie tożsamość instancji funkcji dla danego dołączenia — do provides: FR o zakresie granicy. Wstępny przebieg oblicza te provides przed asemblacją konsumenta, więc wartości są dostępne w chwili budowania potoku konsumenta.
Efekt dla każdego konsumenta to tabela w provides: odczytywana przez injectMapping. Encja FeatureRecipe o zakresie granicy, która musi coś zmienić dla każdego konsumenta, oblicza raz, w swoim provides:, tabelę kluczowaną konsumentem na podstawie połączeń granicy, a jej injectMapping odczytuje wiersze bieżącego komponentu — (index .features .attachment_name).provides, kluczowane przez .context.instance_id — i dostarcza je przez własny potok konsumenta, zgodnie z regułą, której podlega każde mapowanie (zob. Co mapowanie może przepisać). Kompilator przekazuje tabelę zapisaną przez encję FeatureRecipe i niczego w niej nie odczytuje.
Wzorzec compose-bridge
Encja FeatureRecipe compose-bridge to kanoniczny wzorzec FR o zakresie granicy i jest to treść katalogu napisana za pomocą powyższych mechanizmów: ani kompilator, ani dostawca compose nie zawiera żadnej logiki mostu, więc katalog może zrealizować Feature core/compose-bridge inaczej. Funkcja core/compose-bridge jest dołączona do granicy nadrzędnej, która zawiera dwie granice podrzędne (np. services-net i data-net) ze wspólnym directory:, z których każda ma własną adnotację aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net), aby każda trafiła do własnej sieci; bez adnotacji obie współdzielą jedną sieć nazwaną od ścieżki ich pliku compose i docierają do siebie bez mostu. Jej executionScope: boundary uruchamia FR raz na każde dołączenie do granicy nadrzędnej.
Jej provides: oblicza tabelę mostu, raz. Z .boundary.internal_uses_edges zachowuje krawędzie, których oba końce są asemblowane do jej własnego pliku compose — source_assembly_path i target_assembly_path są równe .boundary.assembly_path — i znajdują się w różnych sieciach tego pliku; siecią końca jest jego aggrega.ai/namespace, a w przeciwnym razie jego ścieżka asemblacji. Krawędź między dwoma plikami compose nie jest mostkowana, a jej konsument zachowuje własną nazwę celu. Każda zmostkowana krawędź otrzymuje port nasłuchu — własny port celu albo, jeśli wcześniejsza krawędź już na nim nasłuchuje, pierwszy wolny port nie mniejszy niż portBase dołączenia (domyślnie 10000) — oraz upstream, czyli opublikowany host celu (pole provides wskazane przez providesField dołączenia, domyślnie host) i jego port; upstream jest wyprowadzany z krawędzi, nigdy nie jest pisany ręcznie. Z tej samej tabeli oblicza przepisanie dla każdego konsumenta: zmienna, którą krawędź dostarcza z pola hosta, staje się aggrega-gw:<listen port>, albo aggrega-gw, gdy ta sama krawędź dostarcza też zmienną z port, która wtedy staje się portem nasłuchu.
Jej injectMapping dostarcza wiersze każdego konsumenta. Działając w kontekście każdego konsumenta, odczytuje wiersze tabeli tego konsumenta pod .features.<attachment>.provides i dostarcza je ponad wartościami dostarczonymi przez własne połączenie konsumenta (np. DB_HOST), co jest przechwyceniem; konsument bez wiersza nic nie otrzymuje. Jeśli ten klucz dostarczyła inna encja Feature dołączona do konsumenta — przez swój blok inject: lub swoje injectMapping — kompilacja zatrzymuje się, wskazując obie encje Features, zamiast zastępować to dostarczenie (zob. „Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (dwie dołączone Features dostarczają jeden klucz, późniejsza przez injectMapping swojej FeatureRecipe)” w fatal-halts.md). listen bramy i przepisanie u konsumenta są odczytywane z jednej tabeli, więc zgadzają się dla każdej krawędzi z samej konstrukcji, łącznie z kolizjami przeniesionymi przez portBase.
Jej valuesMapping zapisuje bramę. Własny fragment compose encji FeatureRecipe deklaruje usługę aggrega-gw. Jeśli cokolwiek jest mostkowane, jej valuesMapping dodaje jeden blok nginx stream server na każdą zmostkowaną krawędź (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, pod dyrektywą resolver, aby każdy upstream był rozwiązywany w chwili połączenia, a nie raz przy starcie; znak $ w tych zmiennych jest zapisywany jako $$, aby interpolacja $ w Docker Compose pozostawiła dla nginx dosłowny $), dostarczany jako zamontowana konfiguracja compose — wpis najwyższego poziomu configs: z wbudowanym content:, do którego odwołuje się aggrega-gw i który jest montowany w /etc/nginx/nginx.conf (dzięki czemu nginx ładuje go bez zapisanego przez autora command:). Wbudowane configs.content wymaga Docker Compose ≥ 2.23.1. Wymienia również każdy zmostkowany koniec w x-aggrega-networks-of bramy, które dostawca compose rozwiązuje do sieci, w których umieszczone są te końce, więc brama dołącza do każdej sieci, którą obejmują jej zmostkowane krawędzie (sieci konsumenta i sieci celu) — w czasie działania konsument może osiągnąć aggrega-gw:<port>, a brama może wykonać proxy_pass do celu. Gdy nic nie jest mostkowane, brama zadeklarowana przez fragment nadal jest renderowana, bezczynna: bez konfiguracji, bez dodatkowej sieci i bez przepisania.
Asembler compose działający dla każdej pary (ścieżka, dostawca) scala bramę ze współtwórcami poszczególnych komponentów w tej samej obliczonej ścieżce: jeden docker-compose.yaml zawierający każdy komponent oraz bramę mostu. Gdy żaden z komponentów granicy nie jest asemblowany do pliku bramy, kompilacja zatrzymuje się, zamiast zapisywać bramę donikąd. Upstream jest deterministycznym wskaźnikiem na usługę compose ustalanym w czasie kompilacji; rozwiązuje go DNS compose w czasie działania (bez rozwiązywania czasu działania w czasie kompilacji).
Renderowanie po wywołujących — spec.readsCallerRenderFacts
Opcjonalny klucz spec.readsCallerRenderFacts (wartość logiczna, domyślnie false) deklaruje, że szablony tej encji FeatureRecipe odczytują to, co wyrenderowały komponenty łączące się z jej hostem: fakty renderowania, które dostawca każdego z tych wywołujących zgłasza na temat wyemitowanego przez siebie wyniku. To, co dostawca zgłasza i pod jakimi nazwami, jest własnym kontraktem tego dostawcy; sekcja Reporting facts about what a guest emitted opisuje fakty, które dostawca może zgłaszać.
Kiedy takie dołączenie jest renderowane. Kompilacja renderuje swoje komponenty po kolei, w ustalonej kolejności, a dołączenie zwykle jest renderowane zaraz po komponencie, do którego jest dołączone. Komponent, który łączy się z hostem i występuje później w tej kolejności, w tym momencie nie został jeszcze wyrenderowany, więc nie istnieje nic, co wyemitował i co można by odczytać. Dołączenie, którego FeatureRecipe ustawia readsCallerRenderFacts: true, jest zamiast tego renderowane dopiero wtedy, gdy wszystkie komponenty w kompilacji zostaną wyrenderowane, razem z każdym dołączeniem, które nie ustawia ani tego klucza, ani readsTargetRenderFacts — dzięki temu renderowanie każdego wywołującego jest zakończone, zanim dołączenie zostanie ewaluowane. Jego wynik trafia tam, gdzie trafiłby i tak, i pod tymi samymi nazwami; klucz zmienia to, kiedy dołączenie jest renderowane, a nie to, co renderuje. Z późniejszego renderowania wynika jedna kolejność: gdy FeatureRecipe zawiera pipeline, który przepisuje dokumenty komponentu hosta, a dostawca hosta zapisuje odrębne dokumenty, te kroki są wykonywane po potokach pozostałych dołączeń hosta, a nie w kolejności dołączeń.
Co odczytuje. Gdy klucz jest ustawiony, każdy wpis .context.used_by zawiera .render_facts: fakty renderowania wywołującego, indeksowane nazwą faktu. Każdy fakt renderowania jest listą, więc szablon zawsze iteruje po nim — nawet gdy zawiera jeden wpis. Jego wpisy mogą pochodzić z renderowania samego wywołującego oraz z renderowań encji Features dołączonych do wywołującego: listy, które jedna nazwa otrzymuje z każdego z nich, są łączone w jedną — najpierw wywołania własnego providera wywołującego, potem każda z jego encji Features w kolejności, w jakiej były renderowane. Encja Feature wywołującego, która sama ustawia ten klucz, również renderuje się po wszystkich komponentach, więc to, co zgłosiła, nie znajduje się wśród nich. Wywołujący, którego providery niczego nie zgłaszają, zawiera puste .render_facts, więc nazwa, której nikt nie zgłosił, odczytuje się jako nic:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}To, jakie nazwy faktów istnieją i co zawiera każdy wpis, jest udokumentowanym kontraktem dostawcy wywołującego — w przypadku dostawcy helm są to na przykład jego fakty renderowania, które podają etykiety wyrenderowanych przez niego podów. Fakty wywołujących znajdują się na połączeniach, które odczytują valuesMapping:, workload: i artifacts: encji FeatureRecipe; with: i when: kroku pipeline: w ogóle nie widzą komponentów łączących się z hostem, więc krok odczytuje wyłącznie własne fakty hosta. Każda encja FeatureRecipe dołączona do komponentu — niezależnie od tego, czy ustawia ten klucz — odczytuje własne fakty komponentu w .context.render_facts, w tym samym kształcie; kontekst szablonu opisuje oba przypadki.
Należy go deklarować zawsze, gdy szablon odczytuje fakty. Szablon zapisany inline w encji FeatureRecipe, która nie ustawia tego klucza — w jej valuesMapping:, jej workload: lub we wpisie artifacts: — i odczytujący render_facts pod .context.used_by zatrzymuje kompilację, zanim cokolwiek zostanie wyrenderowane, wskazując odwołanie i pole, w którym je zapisano (zob. „A template reads its callers’ render facts without declaring it (Szablon odczytuje fakty renderowania swoich wywołujących bez zadeklarowania tego)” w fatal-halts.md). Sprawdzenie odczytuje szablon w postaci zapisanej, więc nie widzi odwołania zbudowanego w trakcie działania szablonu ani zapisanego w treści zaimportowanej z pliku lub biblioteki — a szablon odczytujący pole o nazwie render_facts z jakiejś innej listy obok .context.used_by lub odczytujący własne fakty hosta jako .render_facts wewnątrz {{ with .context }} obok niego jest traktowany jako odczytujący fakty wywołujących; własne fakty hosta należy zapisywać w pełnej postaci .context.render_facts. To klucz, a nie sprawdzenie, decyduje o tym, kiedy dołączenie jest renderowane, dlatego należy go ustawiać w każdej encji FeatureRecipe, której szablony odczytują fakty renderowania wywołujących, niezależnie od sposobu dotarcia do nich; jego ustawienie nie kosztuje nic poza późniejszym renderowaniem.
Krok potoku odczytuje wyłącznie własne fakty swojego hosta. Krok może przepisywać własne dokumenty komponentu hosta, a własny wynik komponentu pozostaje taki sam niezależnie od tego, kto się z nim łączy, więc with: i when: kroku nigdy nie widzą komponentów łączących się z hostem — niezależnie od tego, czy FeatureRecipe ustawia ten klucz, który decyduje o tym, kiedy dołączenie jest renderowane, i o niczym, co widzi krok. Zapisane inline with: lub when: kroku, które odczytuje render_facts pod .context.used_by, zatrzymuje zatem kompilację, zanim cokolwiek zostanie wyrenderowane, z krótkim kodem E0326, wskazując odwołanie i pole kroku — zamiast renderować pustą wartość. Własne fakty hosta należy odczytywać w kroku w pełnej postaci .context.render_facts, a fakty wywołujących — w valuesMapping:, workload: lub artifacts: encji FeatureRecipe. To sprawdzenie odczytuje szablon w postaci zapisanej, z tymi samymi ograniczeniami co opisane wyżej.
Zakres. Klucz dotyczy encji FeatureRecipe renderowanej raz na komponent — executionScope: component, wartość domyślna. Encja FeatureRecipe deklarująca executionScope: boundary jest renderowana tam, gdzie zawsze, niezależnie od tego, czy ustawia ten klucz, a szablony tworzące jej zasoby odczytują .boundary, a nie .context.
Renderowanie po celach — spec.readsTargetRenderFacts
Opcjonalny klucz spec.readsTargetRenderFacts (wartość logiczna, domyślnie false) deklaruje, że szablony tej encji FeatureRecipe odczytują to, co wyrenderowały komponenty, z którymi połączony jest jej host: fakty renderowania, które dostawca każdego z tych celów zgłasza o wyemitowanym przez siebie wyniku. Klucz ten odczytuje przeciwny koniec połączenia niż readsCallerRenderFacts — komponenty, na które wskazują wpisy uses hosta, a nie komponenty, których wpisy uses wskazują na hosta — a wszystko, co dotyczy samych faktów, działa tak samo.
Każdy z kluczy sprawia, że załącznik renderuje się po wszystkich komponentach. Załącznik, którego FeatureRecipe ustawia readsCallerRenderFacts: true, readsTargetRenderFacts: true lub oba, renderuje się dopiero wtedy, gdy wyrenderowały się wszystkie komponenty w buildzie, jak opisuje to powyższa sekcja — istnieje jedno takie późniejsze renderowanie, a jego wpływ na to, gdzie trafia wynik załącznika, oraz na kolejność kroków jego potoku jest taki sam niezależnie od tego, który klucz je spowodował. Oba klucze różnią się jedynie tym, które połączenia niosą fakty w kontekście załącznika: cel, który w kolejności buildu występuje po hoście, jest już wtedy wyrenderowany, więc to, co wyemitował, jest dostępne do odczytu.
Co odczytuje. Gdy klucz jest ustawiony, każdy wpis .context.uses zawiera .render_facts: fakty renderowania celu, indeksowane nazwą faktu, w takim samym kształcie, jaki ma wpis wywołującego. Każdy fakt renderowania jest listą, więc szablon zawsze iteruje po nim. Jego wpisy mogą pochodzić z własnego renderowania celu oraz z renderowań encji Features dołączonych do celu: najpierw wywołania własnego dostawcy celu, potem każda z jego encji Features w kolejności, w jakiej się renderowały; encja Feature celu, która sama renderuje się po wszystkich komponentach, nie jest wśród nich. Cel, którego dostawcy niczego nie raportują, ma puste .render_facts. Szablon odczytuje fakty jednego połączenia pod jego aliasem, .context.uses.<alias>.render_facts.<name>, albo fakty każdego połączenia po kolei:
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Encja FeatureRecipe, która nie ustawia tego klucza, nie widzi .render_facts na żadnym połączeniu, niezależnie od tego, co jeszcze ustawia. To, jakie nazwy faktów istnieją, określa udokumentowany kontrakt dostawcy każdego celu — fakty dostawcy helm to jego fakty renderowania, które podają etykiety, selektory kontrolerów i porty kontenerów wyrenderowanych przez niego podów, a więc to, czego polityka ruchu wychodzącego potrzebuje, aby wybrać dokładnie te pody, do których host może się łączyć.
Należy go deklarować zawsze, gdy szablon odczytuje fakty. Szablon zapisany bezpośrednio w encji FeatureRecipe, która nie ustawia tego klucza — w jej valuesMapping:, jej workload: lub we wpisie artifacts: — i odczytujący render_facts pod .context.uses, zatrzymuje kompilację, zanim cokolwiek zostanie wyrenderowane, z krótkim kodem E0347, wskazując odwołanie i pole, w którym je zapisano (zob. „A template reads its targets’ render facts without declaring it (Szablon odczytuje fakty renderowania swoich celów bez ich zadeklarowania)” w fatal-halts.md). Ustawienie readsCallerRenderFacts tego nie znosi. Sprawdzenie odczytuje szablon w postaci zapisanej, z tymi samymi ograniczeniami co sprawdzenie dla wywołujących: nie widzi odwołania zbudowanego podczas wykonywania szablonu ani odwołania zapisanego w treści zaimportowanej z pliku lub biblioteki — a szablon, który w ogóle odczytuje .context.uses i dodatkowo odczytuje pole o nazwie render_facts z jakiejś innej wartości, łącznie z wpisem wywołującego wewnątrz {{ range .context.used_by }}, jest traktowany jako odczytujący fakty swoich celów. Szablon odczytujący fakty obu końców ustawia oba klucze.
Krok potoku odczytuje wyłącznie własne fakty hosta. Pola with: i when: kroku odczytują połączenia tworzone przez hosta, tak jak odczytuje je własna encja Recipe hosta, i nigdy faktów renderowania ich celów — niezależnie od tego, czy FeatureRecipe ustawia klucz. Krok może przepisywać własne dokumenty komponentu hosta, a własne renderowanie hosta odczytuje to, co jego cele publikują, nigdy to, co wyemitowały. Dlatego zapisane bezpośrednio with: lub when: kroku, które odczytuje render_facts pod .context.uses, zatrzymuje build, zanim cokolwiek zostanie wyrenderowane, z krótkim kodem E0348, podając odwołanie i pole kroku — zamiast renderować pustą wartość. Fakty celów należy odczytywać w valuesMapping:, workload: lub artifacts: encji FeatureRecipe.
Zakres. Tak jak w przypadku klucza dla wywołujących: dotyczy encji FeatureRecipe, która renderuje się raz na komponent. Encja FeatureRecipe deklarująca executionScope: boundary renderuje się tam, gdzie zawsze, niezależnie od tego, czy ustawia klucz, a połączenia, które odczytuje pod .boundary, nie niosą żadnych faktów renderowania.
Blok locals:
FeatureRecipe.spec.locals: to opcjonalna mapa nazwanych ciągów szablonów Go, których wyrenderowany wynik udostępnia mapę .locals.* wszystkim pozostałym szablonom w tej samej encji FeatureRecipe. Jest to prywatny dla encji FeatureRecipe odpowiednik bloku locals: encji Recipe — miejsce, w którym można raz obliczyć pochodne ciągi i odwoływać się do nich z injectMapping, valuesMapping, pipeline[].with i provides bez ponownego obliczania. Wpisy assertions: encji FeatureRecipe ich nie odczytują: .locals asercji pochodzą z encji Recipe komponentu hosta, jak podaje assertions-block.md. Wyrenderowany wynik każdego wpisu jest zapisywany bez początkowych i końcowych białych znaków. Blok jest mapą, a nie pojedynczą treścią szablonu; wartość skalarna w tym miejscu jest odrzucana przez schemat.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* dotyczy pojedynczego wywołania: każde wywołanie FR rozwiązuje własny blok locals:, a wynik jest widoczny tylko dla dalszych szablonów tego wywołania. Blok jest rozwiązywany, zanim zostaną obliczone pozostałe szablony powierzchni autorskiej FR, więc każdy z nich widzi rozwiązane wartości.
Każdy wpis jest obliczany względem samodzielnego kontekstu: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra oraz już rozwiązanych wpisów tego samego bloku. Jest to celowo węższy kontekst niż ten, który odczytują pozostałe szablony FR — wpis locals: nie ma dostępu do .context.annotations, .context.inject, .context.uses ani .provides, a odwołanie do któregokolwiek z nich zatrzymuje kompilację z podaniem tego odwołania. Wartości pochodne, które wymagają tych filarów, należy umieścić w szablonie, który je odczytuje, a nie w locals:.
Nazwy w tym kontekście odpowiadają na różne pytania, a wpis locals: odczytuje je dokładnie tak samo jak pozostałe szablony encji FeatureRecipe:
.context.instance_idto komponent hosta, dla którego rozwiązywane jest dołączenie. Oznacza komponent hosta na każdej powierzchni szablonów obliczanej przez kompilator, więc to samo odwołanie odczytuje się tak samo niezależnie od tego, blok której encji jest pisany..context.rendered_nameto nazwa komponentu hosta w postaci zgłaszanej przez jego własnego dostawcę — w przypadkuhelmnazwa wydania, czyli tożsamość hosta zapisana w alfabecie dopuszczalnym w nazwach Kubernetes. Występuje tylko wtedy, gdy dostawca hosta zgłasza nazwę, a odczytanie jej na hoście, którego dostawca żadnej nie zgłasza, zatrzymuje kompilację..attachment_nameto rozwiązywana instancja dołączenia — miejsce, które wypełnia wfeaturesSchemaencji będącej właścicielem, lub dowolna nadana mu nazwa.
Wpis locals:, który wyprowadza nazwę emitowanego zasobu, łączy więc hosta i dołączenie, dokładnie tak jak zrobiłby to szablon artifacts::
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetJeśli nazwa musi być akceptowana przez platformę, a dostawca hosta zgłasza nazwę, należy zamiast tego złożyć ją z .context.rendered_name: dla hosta o nazwie my_api w helm i dołączenia scrape szablon {{ .context.rendered_name }}-{{ .attachment_name }} daje my-zuapi-scrape, podczas gdy tożsamość dałaby my_api-scrape, czego nazwa Kubernetes nie dopuszcza. Zob. Nazywanie wyrenderowanego zasobu.
.values i .infra we wpisie locals: to własne filary dołączenia, zdefiniowane w deklaracji dołączenia — a nie filary komponentu hosta.
Kolejność zapisu ma znaczenie
Wpisy są rozwiązywane w kolejności zapisu, a wpis może odczytać wpis sąsiedni zdefiniowany powyżej, otrzymując jego rozwiązaną wartość:
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveŁańcuchowanie działa tylko w dół. Gdy jeden wpis odczytuje inny, kolejność wpisów decyduje o powodzeniu kompilacji: przeniesienie region_prefix poniżej bucket zatrzymuje kompilację. Kompilator nigdy nie zmienia kolejności bloku, aby odwołanie dało się rozwiązać, więc zmiana kolejności w bloku locals: jest zmianą zachowania, a nie kosmetyczną.
Odwołanie do wpisu, który blok definiuje później, zatrzymuje kompilację z podaniem błędu kolejności (należy przenieść definicję powyżej wpisu, który ją odczytuje); odwołanie do klucza, którego blok w ogóle nie deklaruje, zatrzymuje kompilację z podaniem tego klucza (należy poprawić pisownię). Sprawdzenie podąża za aliasem bloku: klucz osiągnięty przez kropkę, którą ponownie wiąże ciało with .locals, lub przez zmienną powiązaną z .locals, zatrzymuje kompilację na dokładnie tych samych warunkach co zapis bezpośredni, podobnie jak klucz odczytany z bloku ujętego w nawiasy — {{ (.locals).nope }} lub {{ ($.locals).nope }}. Sprawdzeniu umyka jeden zapis: klucz osiągnięty przez wywołanie, którego wyniku tekst szablonu nie może nazwać — {{ index .locals "nope" }} lub {{ (default dict .locals).nope }}. Pole odczytane z wyniku takiego wywołania nie zatrzymuje kompilacji i renderuje dosłowny tekst <no value>; odczyt przez index zatrzymuje kompilację z podaniem klucza, ponieważ index zatrzymuje ją na każdej powierzchni szablonów, gdy odczytywana mapa nie zawiera klucza — zob. errors/fatal-halts.md „A template indexes a map with a key the map does not hold (Szablon indeksuje mapę kluczem, którego mapa nie zawiera)”. provides: odczytuje w pełni rozwiązany blok, ponieważ zmienne lokalne tej encji FeatureRecipe są rozwiązywane przed jej provides; szablon provides: odwołujący się do niezadeklarowanego klucza zatrzymuje kompilację. Są to te same zasady, których przestrzega blok locals: encji Recipe — zob. entities/recipe.md „Blok locals:”.
Zachowanie zależne od zakresu. Dla executionScope: component (domyślnie) locals: jest obliczany dla każdej dołączonej instancji komponentu względem opisanego wyżej samodzielnego kontekstu. Dla executionScope: boundary locals: jest obliczany dla każdego dołączenia do granicy względem widoku zakresu granicy zakorzenionego w .boundary.*; pola dotyczące poszczególnych komponentów (.context.instance_id, .context.inject, .context.uses) oraz .attachment_name są niedostępne, ponieważ FeatureRecipe działa raz dla granicy, a nie raz dla każdego komponentu. Lista dozwolonych pól szablonów zakresu granicy dotyczy locals: tak samo jak pozostałych szablonów powierzchni autorskiej FR. injectMapping, które działa dla każdego komponentu, do którego sięga dołączenie, odczytuje to jedno obliczenie dla granicy jako swoje .locals. Kontrakt obliczania — kolejność zapisu, odczyty sąsiednich wpisów tylko w dół, dwa zatrzymania — jest identyczny w obu zakresach; różni się jedynie kształt otaczającego kontekstu.
Różnica względem nakładek injectMapping i mapowań pipeline[].with. locals: tworzy mapę widoczną w kontekście dla dalszych szablonów; nie wnosi niczego do wyniku. injectMapping zapisuje do potoku .context.inject konsumenta (mutacja po stronie wywołującego). pipeline[].with dostarcza ładunek args wtyczki Wasm. Te trzy powierzchnie są ortogonalne — FeatureRecipe zwykle używa wszystkich trzech jednocześnie, przy czym locals: przenosi wspólne ciągi pochodne, do których odwołują się dwie pozostałe.
Blok assertions:
FeatureRecipe.spec.assertions: to opcjonalna mapa nazwanych reguł wyrażających niezmienniki implementacyjne encji FeatureRecipe — reguł obejmujących wiele pól, które obowiązują przy konkretnym potoku pluginów Wasm, charcie lub mechanizmie, na którym zbudowano FeatureRecipe. Każdy klucz jest identyfikatorem reguły, który pojawia się w komunikacie o niepowodzeniu; każda wartość jest treścią szablonu Go. Podobnie jak asercje encji Recipe, asercje encji FeatureRecipe są właściwościami konkretnej implementacji; reguły kontraktu na poziomie encji Feature obowiązują niezależnie, we wcześniejszej fazie potoku.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}Powyższa reguła jest specyficzna dla pluginu aws-secrets-manager w wersji 1.x; nie obowiązuje, jeśli zostanie powiązana inna encja FeatureRecipe dla core/referenced-secret. Reguły kontraktu na poziomie encji Feature z definicji Feature nadal obowiązują równolegle.
Asercje encji FeatureRecipe są ewaluowane po powiązaniu FeatureRecipe i przed generowaniem zasobów (Resource Generation). Kontekst szablonu dla FR o zakresie komponentu odzwierciedla kontekst asercji encji Recipe (pola instancji encji oraz .provides, .locals, .recipe.metadata, .recipe.source); dla FR o zakresie granicy (executionScope: boundary) asercje są ewaluowane względem widoku zakresu granicy (dostępne są pola .boundary.*; pola poszczególnych komponentów nie są dostępne). Pełną gramatykę i przykłady opisano w templates/assertions-block.md.
Pole omits: — pomijanie wyrenderowanych dokumentów źródła
Większość FeatureRecipes nigdy tego nie potrzebuje. Pole jest przeznaczone dla encji FeatureRecipe, której source: to chart używany w niezmienionej postaci — najczęściej pobrany z rejestru — renderujący dokument, którego dołączenie nie może emitować: Secret generowany przez chart od nowa przy każdym renderowaniu albo obiekt, który już dostarcza komponent hosta lub operator. omits: pomija taki dokument w tym, co generuje FeatureRecipe — albo, w przypadku pliku compose będącego źródłem FeatureRecipe, usługę, wolumin lub konfigurację, których dołączenie nie może wnosić, a w przypadku szablonu CloudFormation będącego jej źródłem — zasób.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsKlucz definiuje się identycznie w encji Recipe, a Recipe → Pole omits: — pomijanie wyrenderowanych dokumentów źródła stanowi jego pełny opis: co wybiera każde pole wpisu, że when: jest wyliczane jako pierwsze, a wartość fałszywa odrzuca wpis, że każdy obowiązujący wpis musi coś pominąć, w przeciwnym razie kompilacja zostaje zatrzymana ze wskazaniem tego wpisu, że źródło nadal jest renderowane w całości, a filtrowane są tylko jego dane wyjściowe, oraz którzy dostawcy obsługują ten klucz. W encji FeatureRecipe różni się jedynie miejsce, w którym wyliczane są szablony:
- Szablony każdego wpisu są wyliczane względem tego samego kontekstu, względem którego wyliczane jest
valuesMapping:tej encji FeatureRecipe, w zakresie wybranym przez jejexecutionScope. Wpisy FeatureRecipe o zakresie komponentu są wyliczane raz na dołączenie, względem.valuesi.infratego dołączenia; wpisy FeatureRecipe o zakresie granicy — raz na granicę, względem widoku zakresu granicy i.infradołączenia granicy. Zasady określające, co mogą odczytywać szablony dołączenia, obowiązują wpisy tak samo jak jegovaluesMapping:. - Filtrowane jest tylko to, co renderuje własne
source:tej encji FeatureRecipe. Jejworkload:iartifacts:nie są filtrowane, podobnie jak dane wyjściowe komponentu hosta: wpisy dołączenia obejmują jego własny chart, jego własny plik compose lub jego własny szablon CloudFormation i nic więcej — usługa compose zadeklarowana przez hosta pod tym samym kluczem wdocker-compose.yaml, do którego oba są składane, pozostaje nietknięta, podobnie jak zasób zadeklarowany przez hosta pod tym samym identyfikatorem logicznym w stosie, do którego oba są składane. Aby zmienić dokument renderowany przez hosta, wpis deklaruje encja Recipe hosta albo łata go krokpipeline:.
Zatrzymanie z powodu wpisu wskazuje węzeł, dostawcę, tę encję FeatureRecipe oraz pozycję wpisu na jej liście omits:; w przypadku FeatureRecipe o zakresie granicy wiersz nad komunikatem wskazuje dołączenie i jego granicę.
Przykład użycia klucza zdefiniowanego w encji Recipe — pominięcie Secret generowanego przez pobrany chart oraz zatrzymania przy braku wpisu i przy wpisie, który niczego nie dopasowuje — zawiera ai-gateway-own-webhook-certificate.