Zmienne szablonów ścieżek
Pola directory: i subDirectory: granicy w encji Release to szablony Go ewaluowane w czasie budowania. Określają, gdzie na dysku trafiają wyrenderowane artefakty, a co za tym idzie, które artefakty są składane razem — dwie granice, których ewaluacja daje tę samą krotkę (path, provider), współdzielą asembler i tworzą jeden scalony wynik (jeden Chart.yaml, jeden docker-compose.yaml). Ta strona jest dokumentacją referencyjną dla autorów: opisuje zmienne, do których mogą odwoływać się te szablony, semantykę ścisłej ewaluacji oraz reguły kaskady, dzięki którym granice dziedziczą po swoich rodzicach.
Koncepcyjne omówienie segregacji przestrzennej i rozdziału według (path, provider) znajduje się w architecture/16-recipe-input-composition.md. Opis tworzenia encji Release na poziomie encji znajduje się w entities/release.md. Konsekwencje po stronie dostawców opisano w providers/architecture.md oraz na stronach poszczególnych dostawców.
Ścisła ewaluacja: missingkey=error
Szablony ścieżek są ewaluowane w trybie Go missingkey=error. Odwołanie do niezadeklarowanego pola, nieustawionego klucza parameters.X lub literówka, taka jak {{ .parmaeters.region }}, powoduje jawny błąd, zamiast po cichu wstawić do ścieżki pusty ciąg znaków.
Ta ścisłość jest niesymetryczna względem reszty kompilatora — valuesMapping, injectMapping i inne mechanizmy renderowania wartości używają missingkey=zero zgodnie z konwencją Helm/Sprig. Generowanie ścieżek różni się strukturalnie: szablon renderowania wartości, który zwraca pusty ciąg znaków, trafia do pola manifestu, gdzie skutki są ograniczone; szablon ścieżki, który zwraca pusty ciąg znaków, trafia do układu katalogów, gdzie skutki są nieograniczone (kolizje, zepsute składanie, ścieżki widmo). Ścisły reżim szablonów ścieżek istnieje po to, aby ujawniać takie błędy w czasie budowania, a nie w czasie wdrażania.
Walidacja listy dozwolonych zmiennych w czasie parsowania
Oprócz ścisłej ewaluacji w czasie wykonania szablony ścieżek są walidowane w czasie parsowania względem zamkniętej listy dozwolonych nazw zmiennych. Odwołanie do nazwy zmiennej spoza tej listy zatrzymuje kompilację, zanim rozpocznie się jakiekolwiek renderowanie, a komunikat diagnostyczny wskazuje błędne pole i granicę, w której ono występuje.
Lista dozwolonych zmiennych jest zamknięta celowo: powierzchnie takie jak .context.inject, .values i .locals świadomie nie są udostępniane szablonom ścieżek. Emisja ścieżek jest kwestią strukturalną, a nie kwestią renderowania wartości; powiązanie ścieżek złożenia z wartościami poszczególnych komponentów uzależniłoby graf ścieżek od danych i podważyło niezmiennik deterministycznego wyniku.
Macierz zmiennych
| Zmienna | directory: | subDirectory: | Opis |
|---|---|---|---|
{{ .capability }} | tak | tak | Funkcja renderowania (helm, helm-chart, compose, terraform, cloudformation) deklarowana przez encję Recipe wnoszącego komponentu, dla artefaktów emitowanych w tej ścieżce. |
{{ .boundary_name }} | tak | tak | Nazwa granicy nadana w encji Release (np. production, eu-prod). |
{{ .parameters.X }} | tak | tak | Dowolny typowany parametr zadeklarowany w encji Aggregate i wypełniony przez encję Release. Dostęp ścisły — odwołanie do .parameters.unknown zatrzymuje kompilację. |
{{ .manifest.recipe_name }} | tak | tak | Nazwa encji Recipe rozwiązana przez encję Manifest dla wnoszącego komponentu. Przydatna do kierowania artefaktów poszczególnych encji Recipe do osobnych podfolderów. |
{{ .parent_boundary.* }} | tak | tak | Kaskadowy dostęp do obliczonych wartości granicy nadrzędnej. Zob. Kaskada granicy nadrzędnej poniżej. |
{{ .component_id }} | — | tak | Identyfikator instancji komponentu, który wnosi wkład. Dla encji Feature dołączonej na granicy, której encja FeatureRecipe działa raz dla tej granicy (executionScope: boundary), jest to złożona tożsamość, którą zasoby tego dołączenia noszą w etykiecie aggrega.ai/component-id — bfr--app--shared dla dołączenia shared na granicy app, skrócona tam, gdzie dostawca dołączenia ogranicza nazwy — dzięki czemu wynik dołączenia trafia do katalogu nazwanego od tej etykiety. Dostępne tylko w subDirectory:, ponieważ directory: jest właściwością przypisaną do granicy — ciąg katalogu jest obliczany raz na granicę, zanim nastąpi jakiekolwiek kierowanie dla poszczególnych komponentów. |
Pole directory: domyślnie przyjmuje boundaries/, po którym następuje ścieżka granicy (stabilny identyfikator czasu kompilacji wyprowadzony z drzewa granic); encja Release, która wymienia swoje komponenty bez deklarowania granic, zapisuje je bez żadnego segmentu katalogu. Pole subDirectory: domyślnie przyjmuje {{ .capability }}, tak aby artefakty każdej funkcji trafiały do własnego podfolderu w katalogu granicy — niezależnie od tego, czy pole pominięto, czy zapisano jako subDirectory: "", co jest odczytywane dokładnie jak pominięcie. Ustawienie subDirectory: "." lub zapisanie szablonu, który daje pusty ciąg, spłaszcza to grupowanie.
Czego te szablony nie rozstrzygają: umieszczenie artifacts:
Jednego segmentu ścieżki wyjściowej szablon ścieżki nie ustawia. Plik wskazany w bloku artifacts: encji Recipe jest zapisywany w katalogu nazwanym od komponentu, który go zadeklarował, wewnątrz tego, do czego zostanie obliczone subDirectory:. Ten segment jest stały i zawsze obecny w przypadku celu, który zapisuje pliki wnoszących obok siebie, zamiast zagnieżdżać każdego wnoszącego we własnym charcie lub module.
Powodem jest to, co nadaje plikowi nazwę. Manifest renderowany lub syntetyzowany przez cel jest nazywany przez cel od komponentu, do którego należy, więc już identyfikuje swój komponent. Artefakt jest nazywany kluczem zapisanym przez autora — app-config.yaml, netpol.yaml — a ten klucz nic nie mówi o komponencie, ponieważ deklarująca go encja Recipe nie wie, które komponenty zostaną z nią powiązane. Dwa komponenty w jednej granicy powiązane z jedną encją Recipe zapisałyby jedną ścieżkę, a ani autor encji Recipe, ani autor encji Release nie ma miejsca, w którym mógłby je rozdzielić.
Dodawany jest tylko katalog; nazwa pliku pozostaje kluczem zapisanym przez autora, więc plik, który autor odczytuje w wyniku, nosi nadaną przez niego nazwę.
Co nadal daje subDirectory: i jak oba mechanizmy się składają. subDirectory: przenosi każdy plik emitowany przez wnoszącego — manifesty renderowane, manifesty syntetyzowane i artefakty razem — jest więc narzędziem do nadania jednemu komponentowi własnego katalogu na potrzeby dalszych narzędzi działających na całym zestawie manifestów jednego komponentu albo do kierowania kilku komponentów do jednego wspólnego folderu. Segment artifacts: jest stosowany pod tym, do czego zostanie ono obliczone. Zapisanie subDirectory: "{{ .capability }}/{{ .component_id }}" w komponencie, którego encja Recipe deklaruje artifacts:, daje zatem nazwę komponentu dwukrotnie — artefakt trafia do <capability>/<component>/<component>/<key>, a renderowane manifesty tego komponentu do <capability>/<component>/<key>. Nadpisanie należy stosować, gdy ma zostać zebrany cały wynik komponentu, a pominąć je, gdy wystarczy rozdzielenie artefaktów, co zapewnia już ustawienie domyślne.
.capability jest rozwiązywane dla każdego komponentu, a directory: granicy jest obliczane w dwóch odrębnych celach. Obliczenie na poziomie granicy, które publikuje .parent_boundary.directory granicom podrzędnym, wykonuje się przed powiązaniem jakiegokolwiek komponentu, więc .capability jest tam puste. Obliczenie na poziomie komponentu, które ustala, gdzie faktycznie trafiają artefakty wnoszącego, niesie funkcję tego komponentu. Granica nadrzędna zapisująca directory: "d-{{ .capability }}" publikuje zatem w dół kaskady d-, podczas gdy jej własne artefakty trafiają do d-compose.
Kaskada granicy nadrzędnej
Zagnieżdżone granice otrzymują widok .parent_boundary, który udostępnia obliczoną ścieżkę bezpośredniej granicy nadrzędnej oraz jej własne dane rozwiązane kaskadowo. Kaskada ma jeden poziom — .parent_boundary granicy to jej bezpośredni rodzic, a nie dziadek. Aby sięgnąć wyżej, sama granica nadrzędna używa .parent_boundary we własnych szablonach, jawnie przekazując wartości w dół drzewa.
Pola dostępne w .parent_boundary:
| Pole | Opis |
|---|---|
.parent_boundary.directory | Obliczona wartość directory: granicy nadrzędnej (po przetworzeniu szablonu). |
.parent_boundary.boundary_name | Nazwa granicy nadrzędnej nadana przez autora. |
.parent_boundary.parameters | Ta sama mapa .parameters.*, którą widziała granica nadrzędna (wartości parametrów są globalne dla encji Release, ale alias jest udostępniany dla symetrii). |
.parent_boundary.annotations | Adnotacje granicy nadrzędnej rozwiązane kaskadowo. |
Wzorzec kanoniczny: granica nadrzędna, która jednorazowo definiuje directory:, oraz granice podrzędne, które kierują swoje artefakty pod granicę nadrzędną, deklarując directory: "{{ .parent_boundary.directory }}". W ten sposób granice podrzędne zostają złączone na ścieżce składania granicy nadrzędnej, co daje jeden scalony wynik zawierający kontrybutorów ze wszystkich granic podrzędnych. Właśnie na tym opiera się encja Feature core/compose-bridge: granica nadrzędna zawierająca funkcję bridge, dwie granice podrzędne (na przykład services-net i data-net) współdzielące directory: granicy nadrzędnej oraz jeden scalony plik docker-compose.yaml zawierający każdy komponent oraz usługę bridge.
Wariant odwrotny: należy pominąć .parent_boundary.directory w granicach podrzędnych (lub obliczyć odrębną ścieżkę), a każda granica podrzędna otrzyma własne składanie. Oba kształty są w pełni wspierane.
Przykładowe układy
Układ 1 — domyślna segregacja według granic
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Każda granica daje w wyniku odrębną wartość directory:, więc każda otrzymuje własne złożenie:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...Domyślne subDirectory: "{{ .capability }}" rozdziela artefakty według możliwości wewnątrz katalogu każdej granicy. Dwie granice, dwa wyniki złożenia na każdą możliwość, bez scalania.
Układ 2 — złożenie scalone przez wspólny katalog nadrzędny
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Obie granice podrzędne obliczają directory: jako deploy/cluster (katalog granicy nadrzędnej), więc wszystkie składowe scalają się w jednej ścieżce złożenia. Przy domyślnym subDirectory: "{{ .capability }}" składowe compose z obu granic podrzędnych trafiają do deploy/cluster/compose/ i tworzą jeden scalony plik docker-compose.yaml. Encja Feature compose-bridge dołączona do granicy nadrzędnej uruchamia się raz (wywołanie w zakresie granicy) i dodaje usługę mostu do tego samego scalonego pliku.
Adnotacja aggrega.ai/chart-name: "cluster-umbrella" granicy nadrzędnej kaskadowo przechodzi na obie granice podrzędne; gdyby granice zawierały także składowe helm-chart, podwykresy helm-chart obu granic podrzędnych złożyłyby się pod jednym wykresem parasolowym o nazwie cluster-umbrella. Niezgodne wartości chart-name między składowymi w jednej ścieżce przerywają kompilację.
Układ 3 — kierowanie według komponentów przez subDirectory: i parametry
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"Wartość directory: granicy daje w wyniku deploy/eu-west-1 (podstawienie parametru). Nadpisania subDirectory: dla poszczególnych komponentów kierują każdą składową do osobnego podfolderu komponentu, przy czym komponent ingress nadpisuje je płaskim podfolderem shared na artefakty przekrojowe:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Ten wzorzec pasuje do przedsiębiorstw, które chcą mieć katalogi artefaktów dla poszczególnych komponentów na potrzeby narzędzi dalszego etapu, działających na manifestach pojedynczego komponentu. Jeśli encja Recipe komponentu deklaruje także artifacts:, przed wyborem tego układu należy przeczytać sekcję Czego te szablony nie rozstrzygają powyżej: te pliki mają już segment komponentu, więc to nadpisanie dodaje drugi.
Diagnostyka
Mechanizm szablonów ścieżek zatrzymuje kompilację w każdej z poniższych sytuacji, a strona errors/fatal-halts.md opisuje je pod tymi nazwami. Ta strona przytacza komunikat, który emituje każde zatrzymanie; wyjście kompilacji należy porównywać z tym tekstem.
- Path-template references a variable outside the allowlist (Szablon ścieżki odwołuje się do zmiennej spoza listy dozwolonych) — na etapie parsowania: szablon ścieżki odwołuje się do zmiennej, której nie ma na liście dozwolonych.
- Path collision (Kolizja ścieżek) — na etapie składania: dwa wkłady granic dają tę samą ścieżkę, ale różnią się właściwością, która musi być jednakowa dla wszystkich wkładów pod tą ścieżką.
- Instance-ID collision (Kolizja identyfikatorów instancji) — na etapie składania: dwie granice, które dają tę samą krotkę
(path, provider), wnoszą komponenty o identycznych identyfikatorach instancji. - Chart-name mismatch (Niezgodność nazw chartów) — na etapie składania: scalony zestaw helm-chart otrzymuje wkłady ze sprzecznymi adnotacjami
aggrega.ai/chart-namerozstrzygniętymi kaskadowo. - Missing template key (Brak klucza szablonu) — szablon ścieżki odwołuje się do pola otwartej zmiennej, które nie ma wartości (np.
{{ .parameters.region }}, gdy encja Release pomijaregion, albo klucz.parent_boundaryw granicy najwyższego poziomu, która nie ma rodzica);missingkey=errorgeneruje jawny komunikat podający granicę, pole szablonu (directory:lubsubDirectory:) oraz brakujący klucz..parametersi.parent_boundarysą otwarte — ich klucze to dane tworzone przez autora — natomiast.manifestdeklaruje swoje klucze, więc błędnie wpisany klucz pod.manifestzostaje odrzucony już na etapie parsowania jako nieznane odwołanie, a diagnostyka wymienia klucze definiowane przez.manifest.
Odsyłacze
entities/release.md— tworzenie encji Release, w tym segregacja przestrzenna oraz poladirectory:/subDirectory:.providers/architecture.md— rozdział pracy między dostawców i model składania według(path, provider).providers/compose.md— dane wyjściowe po stronie compose według(path, provider), w tym scenariusz scalonej ścieżki.providers/helm-chart.md— kompozycja parasolowa helm-chart i reguła kaskady nazwy chartu dla scalonych ścieżek.entities/featurerecipe.md— encje FeatureRecipes o zasięgu granicy (encja Featurecore/compose-bridgeopiera się na opisanym tutaj modelu składania scalonych ścieżek).errors/fatal-halts.md— pełny katalog diagnostyk, w tym wymienione powyżej zatrzymania związane z rozdziałem według ścieżek.