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

Macierz rozwijania szablonów

Dokumentacja rozwijania szablonów — pełna macierz

DSL Aggrega obsługuje rozwijanie szablonów Go text/template (z wstępnie zarejestrowaną biblioteką Sprig) w wielu miejscach encji YAML. Każde miejsce ma określony zestaw dostępnych odwołań, wyznaczony przez moment, w którym dane stają się konkretne w toku kompilacji. Ta strona jest źródłem informacji o tym, do czego i gdzie można się odwoływać.

1. Drzewo czasowe potoku (kiedy dane stają się konkretne)

Aby zrozumieć, jakie odwołania są dostępne, trzeba zrozumieć, kiedy rozwiązywany jest każdy element danych. Poniższe etapy wymieniono w kolejności wykonywania, a nazwa każdego z nich opisuje, co robi — pod tą nazwą występuje on w dalszej części strony:

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. Macierz rozwijania szablonów

Każde miejsce w DSL, w którym obliczane są wyrażenia szablonów Go, oraz dokładny zestaw dostępnych odwołań:

#LocationEncjaEtap obliczaniaDostępne odwołania
1{{ .parameters.X }} w ciągach YAML encji AggregateAggregateRozwiązywanie (interpolacja)Wyłącznie .parameters. Pozostałe dane nie są jeszcze rozwiązane.
2{{ .parameters.X }} w ciągach YAML encji ReleaseReleaseNieobliczaneBrak. Ciągi encji Release są odczytywane tak, jak zostały zapisane: {{ .parameters.X }} pod infra:, w adnotacji lub jako wartość parameters: trafia do miejsca docelowego jako ten dosłowny tekst. Encja Release dostarcza wartości parametrów (wbudowana mapa parameters: i wartości wczytane przez $import: łączone w scaloną mapę parametrów); odczytują je ciągi encji Aggregate (#1), a także szablony ścieżek (#3).
3Szablony directory / subDirectoryGranica encji ReleaseRenderowanie (obliczanie ścieżek).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* oraz .component_id (tylko subDirectory: — szablon directory: go odrzuca).
4Ciągi value: w inject encji ComponentKomponent encji AggregateRozwiązywanie self-inject.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (wszystkie 3 kubełki), .metadata.* (release_name, release_version, environment, aggregate_name). ZABRONIONE: .context.inject (cykliczne — potok jest właśnie budowany), .context.uses (do powiązań między komponentami należy zamiast tego użyć uses[].inject). Szablon znajduje się w tekście encji Aggregate, który jako pierwsza odczytuje interpolacja parametrów z #1, dlatego aby dotarł do tego etapu, należy zapisać go w postaci ze znakami ucieczki — value: '{{"{{"}} .metadata.release_name }}'; zapisany wprost zostaje obliczony przez interpolację i zatrzymuje kompilację, ponieważ tekst encji Aggregate nie definiuje żadnego korzenia poza .parameters.
5Ciągi pola source (ciąg najwyższego poziomu LUB podpola o wartościach tekstowych strukturalnej mapy source:)Recipe / FeatureRecipeRozwiązywanie źródłaDwie powierzchnie, zależnie od tego, co wskazuje źródło. Zdalna współrzędna — pola version, chart, ref i module_subdir bloku strukturalnego wskazującego rejestr, repozytorium chartów lub repozytorium git — jest obliczana, gdy aggrega pull rozwiązuje artefakt, aby go przypiąć: tylko .values, .infra, .locals i statyczne ciągi, z własnymi funkcjami pomocniczymi Aggrega (optional, capitalizedWords, index), bez żadnych funkcji Sprig i bez korzenia .context. Obliczane tam wpisy .locals to te, które te pola odczytują, bezpośrednio lub przez inny wpis — wszystkie wpisy, jeśli pole odczytuje .locals w sposób niewskazujący konkretnego wpisu — więc wpis, którego żadne pole nie odczytuje, pozostaje do renderowania. Źródło wskazujące ścieżkę w przestrzeni roboczej jest obliczane podczas renderowania encji: .context.instance_id, .values, .infra, .locals (cały rozwiązany blok encji deklarującej), statyczne ciągi. Tam źródło encji FeatureRecipe odczytuje dodatkowo .attachment_name — rozwiązywane jest właśnie dołączenie — a jego .context.instance_id wskazuje komponent hosta, obok .context.rendered_name, zgłoszonej nazwy komponentu hosta (zob. #9); encja FeatureRecipe o zasięgu granicy odczytuje .boundary.* i żadnego z filarów przypisanych do komponentu. ZABRONIONE na obu: .context.inject, .context.uses, .provides (niezmiennik samowystarczalności — powierzchnia źródła z przestrzeni roboczej dzieli kontekst z własnym locals encji deklarującej, więc obie dopuszczają i odrzucają te same odwołania, a zdalna współrzędna odczytuje podzbiór tego kontekstu; rozwiązywanie źródła musi się zakończyć przed hydratacją potoku topologii i przed wczytaniem jakiegokolwiek charta, modułu lub treści artefaktu).
6Szablony provides encji RecipeRecipeObliczanie provides.context.instance_id, .context.rendered_name (nazwa, którą dostawca węzła nadaje wynikowi renderowanemu dla węzła — ze źródła dostarczonego przez autora albo z syntetyzowanego workloadu; odczyt na węźle, którego dostawca nie zgłasza takiej nazwy, przerywa kompilację — zob. Nazywanie renderowanego zasobu), .values, .infra, .locals (cały rozwiązany blok węzła — lokalne wartości są rozwiązywane w preambule tego etapu, przed provides), statyczne ciągi. ZABRONIONE: każdy inny korzeń — .context.inject, .context.uses (między węzłami), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (powiązane z rozmieszczeniem/wdrożeniem) oraz .attachment_name (podczas obliczania provides bazowej encji Recipe nie jest rozwiązywane żadne dołączenie). Kontrola opiera się na liście dozwolonych: odwołanie do dowolnego korzenia, którego kontekst provides nie udostępnia, przerywa kompilację (niezmiennik samowystarczalności — umożliwia obliczanie równoległe bez sortowania topologicznego). Przerywa ją również .locals.<key> wskazujące klucz, którego blok locals nie deklaruje, ponieważ ten filar jest otwartą mapą kluczy, której sama kontrola korzeni nie jest w stanie pilnować.
7valuesMapping encji Recipe (wbudowane, plikowe $import: lub biblioteczne $import:)RecipeRenderowanie bazowePełny kontekst szablonu: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Odwołanie do .context.rendered_name zapisane bezpośrednio przerywa kompilację na węźle, którego dostawca nie zgłasza takiej nazwy, jak w #6; odwołanie wewnątrz treści wczytanej przez $import: nie jest sprawdzane i na takim węźle renderuje się jako puste.
8injectMapping encji FeatureRecipeFeatureRecipeMapowanie injectPełny kontekst szablonu: .values, .infra, .context.* (w tym .context.inject — przechwytywany potok — oraz .context.uses). .context.used_by jest tu puste: wynik mapowania trafia do własnego potoku dostarczania hosta. .context.render_facts nie występuje: mapowanie działa przed renderowaniem hosta. .context.rendered_name to zgłoszona nazwa komponentu hosta, jak w #9; mapowanie, które ją odczytuje, nie jest sprawdzane i renderuje ją jako pustą na hoście, którego dostawca żadnej nie zgłasza. Kontekst jest ten sam niezależnie od executionScope encji FeatureRecipe: mapowanie encji FeatureRecipe o zakresie granicy działa raz dla każdego komponentu, do którego dociera dołączenie, odczytuje .context.* tego komponentu, a .features.<attachment>.provides i .locals odczytuje jako wynik jednego obliczenia dla granicy. ZABRONIONE: .boundary, którego nie niesie kontekst żadnego komponentu — odwołanie zatrzymuje kompilację.
9valuesMapping encji FeatureRecipe (oraz jej workload: i artifacts:)FeatureRecipeRenderowanie bazowePełny kontekst szablonu + .attachment_name, .inject (własne wpisy inject: dołączenia, jeśli dołączenie zawiera blok inject:), .context.render_facts — to, co dostawca hosta zgłosił o renderowaniu hosta — oraz .context.used_by — komponenty korzystające z hosta, każdy z własnymi faktami renderowania, jeśli encja FeatureRecipe ustawia readsCallerRenderFacts: true. Każde połączenie w .context.uses niesie fakty renderowania swojego celu, w .render_facts, jeśli encja FeatureRecipe ustawia readsTargetRenderFacts: true. .context.instance_id i .context.rendered_name to tożsamość komponentu hosta i nazwa, którą zgłasza dla niego własny dostawca hosta — ta sama wartość, którą odczytuje encja Recipe hosta, również w locals: i provides: encji FeatureRecipe — a odwołanie do .context.rendered_name zapisane bezpośrednio przerywa kompilację na hoście, którego dostawca nie zgłasza takiej nazwy. .source to własne obliczone source: encji FeatureRecipe, nigdy komponentu hosta, i nie zawiera niczego, jeśli encja FeatureRecipe go nie deklaruje.
10Bloki with: potokuRecipe / FeatureRecipePotok pluginówPełny kontekst szablonu + .steps (wyniki pośrednie z poprzednich kroków potoku). .context.used_by jest tu puste i żadne połączenie w .context.uses nie niesie faktów renderowania swojego celu: krok może przepisać własne dokumenty hosta. Krok dołączonej encji FeatureRecipe odczytuje .context.render_facts, własne fakty renderowania hosta, tak jak #9.
11Treść workload: encji Recipe (każde szablonowane pole wewnątrz, wbudowane lub wczytane przez $import:)RecipeRenderowanie bazowePełny kontekst szablonu. Każde pole w treści Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — należy do tego samego obliczenia szablonu, które przetwarza cały ciąg Workload. Treść Workload jest pojedynczym szablonem Go obliczanym raz względem pełnego kontekstu szablonu; szablony na poziomie pól wewnątrz są rozwiązywane w tym samym obliczeniu, a nie w osobnym.

Uwaga o samowystarczalności. Ciągi source (#5) podlegają tej samej niezmienności samowystarczalności co provides (#6): obie powierzchnie odrzucają odwołania do .context.inject i .context.uses. Rozwiązywanie źródeł odbywa się przed hydratacją inject, która wypełnia .context.inject, i zanim cokolwiek dalej w potoku skorzysta z rozwiązanego źródła — dlatego reguła i jej uzasadnienie obowiązują na obu powierzchniach. Różnią się one filarem provides: source z przestrzeni roboczej dzieli kontekst z locals deklarującej encji, a zdalna współrzędna odczytuje jego podzbiór, więc obie odrzucają .provides, podczas gdy samo provides jest powierzchnią, która jest rozwiązywana. Obie odczytują .locals. Reguła obejmuje source encji FeatureRecipe na tych samych zasadach co w encji Recipe, przy czym każde z nich jest sprawdzane względem własnej powierzchni locals danej encji.

Uwaga o szablonach w treści Workload (#11). Treść Workload to jeden szablonowy ciąg, który renderer ewaluuje w całości, a następnie parsuje wynik jako dokument Workload. Szablony na poziomie pól (tu replicas: {{ .infra.replicas | default 1 }}, tam LOG_LEVEL: "{{ .values.log_level }}" wewnątrz containers.app.variables) nie są osobnymi miejscami ewaluacji szablonów — wszystkie uczestniczą w jednej ewaluacji renderowania bazowego, która tworzy Workload. Autorzy nie potrzebują osobnej reguły dostępności dla pól wewnątrz Workload; reguła dla Workload jako całości (#11) obejmuje każdy szablon na poziomie pól.

Wartość zastępcza uwzględniająca dyskryminator w treści Workload. Powyższy przykład replicas: {{ .infra.replicas | default 1 }} utożsamia sytuację „autor nie ustawił replicas” z sytuacją „autor ustawił replicas na 0” — default zadziała w obu przypadkach. Gdy encja Release celowo zawiera infra.replicas: 0, aby wyrazić skalowanie do zera (częsty wzorzec Knative / KEDA), forma | default 1 po cichu nadpisuje ten zamiar. Kształt uwzględniający dyskryminator to replicas: {{ optional .infra "replicas" 1 }} — optional sprawdza obecność klucza i zwraca wartość podaną przez autora (w tym podane zero), gdy klucz jest ustawiony, a do 1 wraca tylko wtedy, gdy klucza brak. Pełna semantyka i wskazówki, kiedy ją preferować: sprig-functions.md.

3. Zabronione odwołania i uzasadnienie

LocationZabronione odwołanieUzasadnienie
Component inject value: (#4).context.injectPotok inject jest w tym momencie budowany — szablon value: samowstrzyknięcia nie może czytać z potoku, do którego sam się dokłada.
Component inject value: (#4).context.usesPowiązania między komponentami znajdują się w uses[].inject. Szablony value: samowstrzyknięcia komponentu pozostają zamknięte nad własnymi danymi komponentu.
Recipe provides (#6).context.injectSzablony provides są ewaluowane w dowolnej kolejności i zamykają się wyłącznie nad własnymi danymi węzła (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Potok inject zostaje wypełniony dopiero podczas hydratacji inject, która następuje po ewaluacji provides wszystkich węzłów.
Recipe provides (#6).attachment_namePrzebieg provides bazowej encji Recipe nie rozwiązuje żadnego dołączenia, więc nazwa zostałaby wyrenderowana jako pusta. Korzeń jest odrzucany, zamiast być dostarczany pusty.
source (#5).providesŻadna z powierzchni źródła nie ma filaru provides: powierzchnia źródła z przestrzeni roboczej dzieli kontekst z własnymi locals deklarującej encji, które go nie mają, a zdalna współrzędna odczytuje podzbiór tego kontekstu. Locals są rozwiązywane przed provides, aby provides: mogło odczytywać .locals; szablon źródła odczytuje te same locals, zamiast sięgać wstecz po provides.
Recipe locals (preambuła #6).providesLocals są rozwiązywane przed provides, więc w chwili ewaluacji wartości lokalnej własne provides węzła jeszcze nie istnieją. Wartość lokalna potrzebująca wartości, którą publikują także provides, oblicza ją bezpośrednio z .values / .infra — a wpis provides odczytuje następnie tę wartość lokalną.
Recipe locals (preambuła #6).context.rendered_nameLocals encji Recipe dzielą kontekst z jej szablonem source (#5), a ta powierzchnia nie udostępnia nazwy: to, czy węzeł dostarcza źródło, o czym decyduje szablon source, jest jednym z czynników, od których nazwa zależy. Odwołanie zatrzymuje kompilację diagnostyką nieznanego korzenia, która podaje .context.instance_id jako to, co .context tam definiuje. Zamiast tego należy odczytać klucz we wpisie provides lub w szablonie etapu renderowania bazowego.
Recipe provides (#6).context.uses.context.uses odwołuje się do provides innych węzłów, a ewaluacja provides przetwarza je w dowolnej kolejności. Szablony provides pozostają samowystarczalne, aby ewaluacja nie zależała od kolejności.
FeatureRecipe locals, provides, source (#5) i szablony renderowania inline (#9, #10), na hoście, którego dostawca nie zgłasza nazwy.context.rendered_nameW dołączeniu encji Feature klucz przenosi zgłoszoną nazwę komponentu-hosta, a host umieszczający sam zestaw artefaktów lub renderujący przez dostawcę, który nie wyprowadza takiej nazwy, nie ma czego przenieść. Odwołanie zatrzymuje kompilację diagnostyką nieznanego korzenia, która wymienia .context.instance_id wśród tego, co .context tam definiuje; zamiast tego należy odczytać tożsamość, od której na takim hoście pochodzą nazwy własnych zasobów hosta.
source (#5).context.injectRozwiązywanie źródeł odbywa się przed hydratacją inject, która wypełnia .context.inject. W chwili ewaluacji URI źródła potok nie jest jeszcze wypełniony.
source (#5).context.usesRozwiązywanie źródeł musi się zakończyć, zanim cokolwiek dalej w potoku załaduje chart, moduł lub treść artefaktu deklarującej encji. Dopuszczenie odwołań między węzłami powiązałoby rozwiązywanie źródeł z kolejnością iteracji topologii, czego celowo się unika.
Parametry (wszędzie poza szablonami ścieżek)Każda powierzchnia szablonów wartości po interpolacjiInterpolacja konsumuje każde odwołanie {{ .parameters.X }} w napisanym YAML i wstawia w jego miejsce rozwiązaną wartość, więc powierzchnia szablonów wartości otrzymuje rozwiązany literał zamiast filaru parametrów. Szablony ścieżek pisane przez operatora są jedynym wyjątkiem i odczytują .parameters.X bezpośrednio.

4. Ścieżka rozwiązywania samowstrzyknięcia

Rozwiązywanie samowstrzyknięcia to pierwsza połowa hydratacji inject i następuje po ewaluacji provides wszystkich węzłów. Gdy komponent deklaruje blok inject: na poziomie komponentu, kompilator ewaluuje go w tym miejscu:

  1. Literalne ciągi value:: jeśli wartość zawiera wyrażenia szablonów Go, kompilator ewaluuje je z kontekstem z wiersza #4 macierzy (.values, .infra, .context.instance_id, .metadata.* itd.), zapisane ze znakami ucieczki, jak pokazuje wiersz #4. Zwykłe ciągi przechodzą bez zmian.
  2. Odwołania from:: kompilator wyszukuje klucz we własnym słowniku provides węzła, rozwiązanym już w tym momencie. Jeśli klucz nie istnieje, kompilator zatrzymuje kompilację błędem nieprawidłowego klucza inject.
  3. Sprawdzenie kolizji: przed scaleniem z potokiem .context.inject kompilator sprawdza, czy żaden klucz nie koliduje z kluczami uses-inject, które rozwiązuje druga połowa hydratacji inject. Kolizje zatrzymują kompilację błędem zduplikowanego klucza dostarczania.

Wynikowe ciągi są scalane z .context.inject.env, .context.inject.file, .context.inject.arg (oraz dowolnymi niestandardowymi mechanizmami) obok tych rozwiązań uses-inject. Zanim zostanie uruchomione mapowanie inject (injectMapping), potok zawiera wszystkie wartości inject napisane przez programistę z obu źródeł.