Filary danych
Koncepcyjne ujęcie pięciu strukturalnych słów kluczowych DSL — parameters, values, uses, infra, inject — znajduje się w architecture/06-data-taxonomy-and-composition.md. Ta strona omawia kanoniczną listę filarów danych, semantykę tworzenia poszczególnych filarów, mechanikę międzyfilarową oraz słownictwo wartości domyślnych, z którym autorzy spotykają się w różnych filarach. Uzupełniająca triada topologiczna (provides, inject, uses — słowa kluczowe łączące krawędzie grafu) jest opisana w topology-triad.md; słownictwo metadanych odrębne od filarów danych (etykiety, adnotacje, pola powierzchni publikacji) znajduje się w labels-and-annotations.md i publishing-surface.md.
Kanoniczna lista filarów
Encje Aggrega mają siedem nazwanych filarów danych. Pięć z nich uczestniczy w przepływie danych IR jako stan żywy aż do renderowania; dwa są przejściowe lub prywatne i istnieją tylko na określonych etapach kompilacji.
| Filar | Występuje w | Cykl życia | Rola |
|---|---|---|---|
values | Instancje komponentów / załączników encji Aggregate | Żywy aż do renderowania | Ładunek poznawczy tworzony przez Developera |
infra | Wpisy komponentów, załączników i połączeń encji Release | Żywy aż do renderowania | Fizyczne wymiarowanie tworzone przez Operatora |
provides | Blok provides: encji Recipe | Żywy aż do renderowania (filar pochodny — zob. niżej) | Publiczne wyjściowe ciągi znaków obliczane przez Recipe, konsumowane przez potok topologii |
uses | Instancje komponentów / funkcji encji Aggregate | Żywy aż do renderowania | Krawędzie topologiczne do innych komponentów / funkcji |
features | Instancje komponentów w encjach Aggregate + Release; sloty zadeklarowane w featuresSchema encji katalogu — zob. „Features pillar” (filar Features) poniżej | Żywy aż do renderowania | Filar załączników — jeden kształt dla każdej rodziny załączników |
parameters | Korzenie encji Aggregate + Release | Odczytywalny do końca potoku, aż zakończą się wszystkie fazy renderowania; dostępny dla szablonów ścieżek podczas renderowania dzięki asymetrycznemu uprawnieniu; konteksty szablonów wartości konsumują literały po interpolacji, a nie bezpośrednio .parameters | Sloty dla poszczególnych środowisk wypełniane przez encję Release |
locals | Blok locals: encji Recipe | Prywatny dla encji Recipe — widoczny tylko w jej własnych szablonach | Obliczany stan w postaci ciągów znaków, wyprowadzany przez encje Recipes w preambule locals |
values / infra / provides / uses / features to pięć żywych filarów, które kontekst szablonu w czasie wykonania udostępnia odpowiednio przez .values, .infra, .provides, .context.uses i .features. parameters i locals nie należą do listy żywych filarów — parameters, ponieważ nie przetrwa rozwiązywania; locals, ponieważ jest prywatny dla encji Recipe i nigdy nie przekracza granic encji.
Filary są drogowskazami, a nie murami: silnik szablonów pozwala na odczyty między filarami w każdym miejscu, chyba że wprost zabraniają tego reguły samowystarczalności (blok provides: encji Recipe i blok source: encji Recipe odczytujące .context.inject / .context.uses; opisane w templates/expansion-matrix.md). Granice filarów to dyscyplina tworzenia, a nie wymuszenie przez język.
Granice filarów i dyscyplina tworzenia
Odczyty między filarami z szablonu Recipe nie są ograniczone w żadnym miejscu, które udostępnia pełny kontekst szablonu. Dyscyplina tworzenia oczekuje od autorów, że będą:
- Odczytywać
.valuesdla ładunku kognitywnego (intencja tworzona przez Developera). - Odczytywać
.infradla wymiarowania fizycznego (wymiarowanie tworzone przez Operatora). - Odczytywać
.context.uses[].provides.<key>dla ciągów wskaźników między komponentami (przepływ danych triady topologii). - Odczytywać
.context.injectdla potoku dostarczania po hydratacji (składanego ze źródeł inject zcomponent.inject,uses[].injectoraz przechwyceńinjectMappingw FeatureRecipe).
Dyscyplina to drogowskazy, a nie mury. Szablon Recipe, który odczytuje .infra.replicas, aby sterować polem values:, działa; silnik szablonów nie blokuje odczytu. Architektura ujmuje to tak, że granice filarów opisują intencję tworzenia — kto jest właścicielem danych — a nie ograniczenie w czasie wykonania. Konwencje odpowiadają podziałowi na cztery domeny: wartości tworzone przez Developera pochodzą z .values; wymiarowanie tworzone przez Operatora pochodzi z .infra; współrzędne między komponentami pochodzą z potoku topologii.
Gdy potrzebny jest celowy pomost między filarami — np. schema: encji Component udostępnia pokrętło dla developera, które szablon valuesMapping: encji Recipe przekazuje do wyjścia w kształcie infra: po stronie Ops zgodnie z vocabulary/inheritance-and-interface.md — architektura traktuje ten pomost jako oznaczony drogowskazem wyjątek. Zob. „Mechanika między filarami” poniżej.
Values
Filar values: przenosi ładunek poznawczy tworzony przez Developera — parametry kształtu aplikacji, które Developer określa dla każdej instancji komponentu. Encja schema: w encji Component deklaruje kształt wartości; Aggregate Developera wypełnia konkretne wartości dla każdej instancji. To domena Developera.
Miejsce tworzenia:
- Aggregate
components.<id>.values:— ładunek poznawczy dla każdej instancji komponentu. - Aggregate
subsystems.<name>.components.<id>.values:— to samo, wewnątrz komponentów pogrupowanych w podsystemy. - Aggregate
components.<id>.features.<name>.values:orazfeatures.<name>.values:podsystemu — ładunek wartości dołączenia, niezależnie od rodziny, do której należy dołączona encja Feature (parametry zapytania do sejfu dla dołączenia poświadczeń tworzy się tutaj tak jak wszystkie inne).
Zabronione w:
- Encji Release (schemat encji Release zabrania bloku
values:na każdym poziomie zagnieżdżenia — Parameter Hoisting jest obsługiwaną ścieżką zmienności między środowiskami; zob. Parameters poniżej).
Walidacja: blok values: w schema encji Component (oraz blok values: w schema encji Feature dla dołączeń Feature), rozwiązywany do JSON Schema 2020-12 w momencie ładowania encji Component / Feature zgodnie z vocabulary/validation-surface.md, warstwa 2.
Konsumenci: szablony valuesMapping: encji Recipe poprzez .values. Pełny kontekst szablonu udostępnia rozwiązany słownik wartości w każdym miejscu szablonu renderowania bazowego.
Infra
Filar infra: przenosi fizyczne wymiarowanie tworzone przez operatora — repliki, żądania zasobów, limity IOPS, przypinanie do regionu, klasę maszyny. Wyraża gdzie i jak duże, uzupełniając co i jak się zachowuje z wartości. To domena operatora.
Cztery miejsca tworzenia
Autorzy spotykają infra: w czterech odrębnych miejscach, z których każde ma inny zakres i inne zachowanie kaskadowe:
| # | Miejsce | Zakres | Pierwszeństwo przy scalaniu |
|---|---|---|---|
| 1 | components.<id>.infra: granicy encji Release (spec.components.<id>.infra: w encji Release bez granic) | Jedna instancja komponentu | Własne wymiarowanie komponentu; żadne inne miejsce go nie zapisuje |
| 2 | features.<name>.infra: granicy encji Release | Dołączenie obejmujące całą granicę, na każdym komponencie w granicy | Najniższe dla tego dołączenia — miejsce 3 nadpisuje je pole po polu |
| 3 | components.<id>.features.<name>.infra: granicy encji Release | Jedno dołączenie na jednym komponencie | Nadpisuje miejsce 2 dla tego dołączenia, pole po polu |
| 4 | components.<id>.uses.<socket>.<alias>.infra: encji Release | Jedno połączenie | Walidowane względem infraSchema gniazda; trafia tylko do renderowania komponentu konsumującego |
Miejsce 1 jest używane najczęściej: operator wymiaruje każdy komponent, który umieszcza encja Release. Granica nie ma własnego infra: — schemat Release je odrzuca — więc wymiarowanie wspólne dla kilku komponentów zapisuje się przy każdym z nich albo dziedziczy z nadrzędnej encji Release przez extends: (poniżej). Miejsca 2 i 3 obejmują wymiarowanie dołączeń encji Feature — encje Features przenoszą własny ładunek infra, który FeatureRecipe wykorzystuje przy syntezie sidecarów lub zasobów dla poszczególnych encji Feature: dołączenie obejmujące całą granicę jest wymiarowane raz, a pojedynczy komponent dostosowuje jedno jego pole.
„Infra głównie lokalne” — reguła z wyjątkami
Docelowo w architekturze infra: jest lokalne dla komponentu: wymiarowanie komponentu dotyczy tej instancji komponentu i nie przenika do innych komponentów. To mechanizm, który pozwala zespołowi Ops zwiększyć IOPS bazy danych bez wpływu na żądanie CPU serwera API.
Reguła: infra: jest głównie lokalne dla miejsca, w którym je zdefiniowano. Wyjątki kaskadowe istnieją celowo:
- Kaskada adnotacji granicy.
annotations:granicy kaskadują przez zagnieżdżone granice do wewnętrznych komponentów (miejsce 5 macierzy adnotacji w labels-and-annotations.md). Adnotacje wykorzystywane przez encje Recipes jako dane wejściowe routingu stają się pośrednim zasięgieminfra— adnotacja na poziomie granicy przepływa przez.context.annotations.releasedo wyrenderowanego wyniku encji Recipe danego węzła. - Dziedziczenie encji Release przez
extends:. Encja Release, która przezextends:rozszerza nadrzędną encję Release, dziedziczy deklaracjeinfrarodzica w każdym miejscu, które je zawiera, chyba że potomek nadpisze je dla danego klucza. Wartość potomka wygrywa klucz po kluczu, aż do pierwszej niepodzielnej wartości — skalara, listy, szablonu — która jest zastępowana w całości, a klucz zapisany przez potomka jakonulljest usuwany, a nie ustawiany na pustą wartość. Dziedziczenie celowo przekracza granicę pojedynczej encji Release; pełną regułę scalania i to, co jeszcze jest z nią przenoszone, opisujeentities/release.md. - Przekazywanie między filarami przez most schematu.
schema:encji Component może udostępniać przeznaczone dla dewelopera pokrętłovalues:, które szablonvaluesMapping:encji Recipe przekazuje do wyniku dostawcy o kształcieinfra:(zob. „Mechanika międzyfilarowa — przekazywanie między filarami przez most schematu” poniżej). Ściśle biorąc, wartość pochodzi zvalues:i przepływa do wyrenderowanego wyniku; kaskada odbywa się w obrębie instancji, ale między filarami.
Lokalność jest zamiarem projektowym, a nie murem egzekwowanym przez silnik: powyższe kaskady to celowe wyjątki, z których każdy jest udokumentowany w miejscu, które go przenosi.
Podział strona–filar dla rozwijania encji Feature sterowanego adnotacjami. Niezmiennik „Aggregate jako miejsce tworzenia” obowiązuje także na ścieżce rozwijania encji Feature sterowanego adnotacjami: adnotacje po stronie Aggregate (zakres podsystemu i instancji komponentu) mogą uruchamiać wyłącznie podklucze maps.values; adnotacje po stronie Release (zakres granicy i instancji komponentu) mogą uruchamiać wyłącznie podklucze maps.infra. Powiązanie encji Manifest może deklarować ścieżki w obu filarach; każda strona uruchamia tylko zgodny z nią podzbiór, a kompozycja międzystronowa scala wkłady pole po polu w czasie budowania IR. Podział zachowuje rozdzielenie tworzenia values-deweloper / infra-operator w miejscu adnotacji — to samo rozdzielenie, które values: i infra: egzekwują w miejscach jawnego dołączania. Zob. providers/well-known-annotations.md §„Side-vs-pillar partition per subkey” (podział strona–filar dla podklucza), gdzie opisano poszczególne podklucze i wzorzec kompozycji międzystronowej.
Provides
Filar provides: jest pochodny — deklaruje go encja Recipe, ale w odróżnieniu od values / infra deweloper nie tworzy go bezpośrednio. Encje Recipes obliczają publiczne ciągi wyjściowe, które pobierze potok topologii.
Blok provides: encji Recipe jest mapą par <key>: <template>. Każdy szablon jest podczas ewaluacji provides obliczany względem własnej, samowystarczalnej powierzchni encji Recipe (.values, .infra, .context.instance_id, .context.rendered_name tam, gdzie provider węzła go zgłasza, oraz rozwiązane .locals węzła). Wynikowe ciągi są udostępniane przez .provides i pobierane przez bloki uses[].inject wywołujących za pomocą odwołań from: "<key>". .locals jest dostępne, ponieważ locals węzła są rozwiązywane w preambule tego etapu, przed jego provides (zob. Locals poniżej); podanie klucza, którego blok locals nie deklaruje, powoduje zatrzymanie.
Niezmiennik samowystarczalności. Szablony provides: encji Recipe nie mogą odwoływać się do .context.inject ani .context.uses. Ewaluacja provides uruchamia te szablony w dowolnej kolejności — domykają się one wyłącznie nad własnymi danymi węzła, więc kolejność nie ma znaczenia. Odwołania między węzłami uzależniłyby tę ewaluację od kolejności iteracji topologicznej, czego projekt celowo unika. Regułę i jej uzasadnienie opisuje wiersz 6 w templates/expansion-matrix.md.
Dlaczego provides: jest filarem. Ciągi wyjściowe stanowią kanoniczną publiczną powierzchnię każdej encji Recipe; dalsi konsumenci (uses[].inject wywołującego, bloki injectMapping encji FeatureRecipe odczytujące rozwiązane provides celu przez .context.uses) traktują ten słownik jako typowany kontrakt. Nazwanie provides: filarem uznaje jego pełnoprawny status obok values / infra / uses / features. Traktowanie go jako „zwykłego elementu wewnętrznego encji Recipe” umniejsza jego rolę jako głównego źródła danych potoku topologii.
Uses
Filar uses: to deklaracja krawędzi topologicznych. Blok uses: instancji komponentu wymienia krawędzie, w których komponent uczestniczy — gniazda, przez które konsumuje cele. Pełna gramatyka jest opisana w topology-triad.md; ta sekcja wymienia uses: jako filar dla kompletności.
uses: znajduje się w instancjach komponentów encji Aggregate oraz w dołączeniach funkcji; kontekst szablonu w czasie wykonania udostępnia jeden wpis na każde połączenie wychodzące, z jego aliasem jako kluczem, jako .context.uses. Projekcja niesie rozwiązane metadane celu każdej krawędzi (provides celu, etykiety, adnotacje), dzięki czemu encje Recipes wywołujących mogą odczytywać ciągi wskaźników między komponentami podczas ewaluacji szablonów renderowania bazowego, a także dołączenia zapisane na tym połączeniu, pod .context.uses.<alias>.features.<slot>.
Filar Features
features: to filar dołączeń: jedno słowo kluczowe, jeden kształt, wszystkie dołączenia. Operacyjna encja Feature, encja Feature z poświadczeniami i encja Feature tożsamości są deklarowane tutaj pod nazwą instancji wybraną przez autora. Kontekst szablonu w czasie wykonania udostępnia dołączenia węzła jako .features.<name>, każde z polami type, values, infra i rozwiązanym provides dołączenia. Dołączenie zapisane na jednym z połączeń komponentu jest udostępniane w tym samym kształcie pod połączeniem, w .context.uses.<alias>.features.<slot>, i nigdy pod .features — dlatego encja Recipe iterująca po .features napotyka wyłącznie własne dołączenia komponentu (zob. kontrakt kontekstu szablonu).
Dołączenie, którego nazwa instancji odpowiada slotowi zadeklarowanemu przez encję w featuresSchema, wypełnia ten slot; każda inna nazwa instancji oznacza dołączenie wolne. Wypełnienie slotu łączy cztery miejsca, przez które przechodzi poświadczenie oparte na slocie:
| Miejsce | Gdzie zapisywane | Rola |
|---|---|---|
Component / Feature featuresSchema: | encja katalogu | Deklaruje sloty oczekiwane przez encję; dla każdego slotu ogranicza listę dozwolonych sposobów dostarczenia (env / file / blackbox) i opcjonalnie selektor etykiet, który musi spełniać wypełnienie |
Aggregate components.<id>.features.<slot>: | instancja komponentu w encji Aggregate | Wypełnia slot dołączeniem; dostarcza własne values: dołączenia oraz, w przypadku slotu przezroczystego, jego mapowanie inject: |
Workload containers.<name>.attachments.<KEY>.from/as: | treść Workload w encji Recipe | Odwołuje się do zadeklarowanego slotu — lub, obok connection: <alias>, do slotu deklarowanego przez gniazdo tego połączenia — i określa dostarczenie tego, co go wypełniło, dla każdego kontenera |
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:) | powiązana encja FeatureRecipe | Wytwarza wynik dołączenia — emitowany zasób, przepisanie dostarczenia lub oba |
Nazwa slotu jest kluczowym identyfikatorem we wszystkich czterech miejscach: miejsce 1 ją deklaruje, miejsca 2–4 się do niej odwołują, a przepływ danych jest jednokierunkowy (deklaracja → wypełnienie → odwołanie → wytworzenie).
Listę kontrolną dla autorów zawiera examples/04-secrets.md, sekcja „The secret-delivery checklist”.
Locals
Filar locals: to prywatny stan encji Recipe. Cały blok jest rozwiązywany w preambule locals, przed provides: danego węzła; powstałe ciągi znaków są widoczne dla każdego z późniejszych szablonów tej samej encji Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Szablon provides: odwołujący się do klucza, którego blok nie deklaruje, zatrzymuje kompilację.
Miejsce definiowania: blok spec.locals: encji Recipe — mapa par <key>: <template> ewaluowanych względem samowystarczalnej, lokalnej dla węzła powierzchni: .context.instance_id, .values, .infra oraz już rozwiązanych wpisów tego samego bloku. Nic więcej się na niej nie znajduje: .provides, .metadata i pozostała część .context.* nie są dostępne, a odwołanie do któregokolwiek z nich zatrzymuje kompilację.
Kolejność ma znaczenie. Wpisy są rozwiązywane w kolejności zapisu, a wpis może odczytać wpis równorzędny zdefiniowany powyżej, otrzymując jego rozwiązaną wartość. Łańcuchowanie działa tylko w dół — gdy jeden wpis odczytuje inny, przeniesienie definicji poniżej wpisu, który ją odczytuje, jest odrzucane, a kompilator nigdy nie zmienia kolejności bloku, aby odwołanie dało się rozwiązać. Odwołanie do późniejszego wpisu zatrzymuje kompilację z komunikatem wskazującym błąd kolejności; odwołanie do niezadeklarowanego klucza zatrzymuje kompilację z komunikatem wskazującym ten klucz. W encji Recipe, której source: jest blokiem strukturalnym, oba błędy są odrzucane także podczas przypinania wskazanego w nim artefaktu, więc aggrega pull zgłasza je, zanim jakakolwiek kompilacja wygeneruje wynik. Sprawdzenie analizuje ścieżkę, do której odwołanie się rozwiązuje, a nie dosłowny zapis, więc obejmuje zarówno formę bezpośrednią, blok with .locals i zmienną powiązaną z .locals, jak i blok w nawiasach, (.locals).<key> lub ($.locals).<key>. Nie obejmuje jednego zapisu: klucza osiąganego przez funkcję, takiego jak index .locals lub (default dict .locals).<key>. Brakujący klucz osiągnięty w ten sposób nie zatrzymuje kompilacji i generuje dosłowny tekst <no value> zamiast pustego wyniku — z wyjątkiem samego index, który na każdej powierzchni szablonów zatrzymuje kompilację z komunikatem wskazującym klucz, gdy odczytywana mapa go nie zawiera.
Widoczność: prywatna dla encji Recipe. Nie istnieje pole .context.uses[].locals — wywołujący nie może odczytać locals swojego celu przez krawędź. Wywołujący może odczytać provides: celu.
Przypadki użycia:
- Obliczanie wewnętrznych dla encji Recipe ciągów wskazujących (np.
secret_target_admin_password: "redis-auth", sufiks nazwy obiektu Secret), które konsumują zarównovaluesMapping:, jak iprovides:tej encji Recipe, i które uwierzytelniająca encja FeatureRecipe dołączona do tego samego komponentu odczytuje jako.locals.secret_target_admin_password— szablony dołączenia widzą rozwiązane locals encji Recipe gospodarza scalone z własnymi locals dołączenia. W celuhelmkażdy z nich zapisuje pełną nazwę jako{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: nazwa wyrenderowana to nazwa komponentu zapisana znakami dozwolonymi w nazwie Kubernetes, a local nie może jej odczytać, więc local przenosi sufiks, a każdy odczytujący łączy oba elementy. - Eliminowanie powtórzeń (DRY) obliczanych wartości w obrębie jednej encji Recipe (nazwa hosta obliczana raz i używana w wielu polach
valuesMapping:). - Wartości pośrednie dla złożonej logiki szablonów, która zapisana w jednej linii byłaby nieczytelna.
provides: i locals: — oblicze publiczne a oblicze prywatne
Dwa filary po stronie encji Recipe mają celowo rozdzieloną widoczność, o której autorzy powinni pamiętać:
provides:to oblicze publiczne. Każdy klucz należy do kanonicznej powierzchni potoku topologii — blokiuses[].injectwywołujących niżej w łańcuchu konsumują je przez odwołaniafrom: "<key>". Słownikprovides:to typowany kontrakt, od którego zależą wywołujący; zmiana nazwy lub usunięcie klucza jest zmianą niekompatybilną dla każdej encji Recipe, której deklaracjeuses[].injectsię do niego odwołują.locals:to oblicze prywatne. Każdy klucz jest wewnętrznym stanem encji Recipe, widocznym tylko w jej własnych kolejnych szablonach. Żaden wywołujący nie może odczytać locals encji Recipe; nazwy wlocals:nie należą do żadnego publikowanego interfejsu, a zmiana ich nazw to wewnętrzna refaktoryzacja encji Recipe bez skutków dla odbiorców.
Oba filary są też uporządkowane: locals: jest rozwiązywany jako pierwszy, więc provides: może odczytywać .locals, ale locals: nie może odczytywać .provides. Opublikowanie wartości locala przez provides: oznacza zatem dodanie wpisu provides, który odczytuje ten local — wyrażenie pozostaje w jednym miejscu.
Rozdział jest celowy i wynika z architektonicznego oddzielenia wnętrza encji Recipe (prywatnego) od jej interfejsu (publicznego). Autorzy traktujący provides: i locals: jako jedną przestrzeń nazw tracą rozróżnienie widoczności i ryzykują ujawnienie stanu wewnętrznego przez potok topologii — każdy klucz zadeklarowany w provides: staje się częścią powierzchni kontraktu encji Recipe, niezależnie od intencji autora. Zalecana dyscyplina: najpierw zadeklarować klucz w locals:; przenosić go do provides: dopiero wtedy, gdy rzeczywiście potrzebuje go wywołujący niżej w łańcuchu.
Widoczność wyznacza filar, w którym zadeklarowano klucz: nie ma znacznika widoczności dla pojedynczego klucza, więc wartość jednocześnie prywatna i publikowana to wpis locals: oraz wpis provides:, który go odczytuje.
Parametry
Zarówno schemat Aggregate, jak i schemat Release zawierają w katalogu głównym słownik parameters. Programiści deklarują klucze, których oczekuje encja Aggregate; zespół Ops uzupełnia wartości w plikach Release właściwych dla danego środowiska. To rozdzielenie jest mechanizmem promocji GitOps: jeden niezmienny plik Aggregate.yaml przechodzi przez środowiska Dev, Staging i Production, a encja Release każdego środowiska dostarcza własne wartości parametrów.
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: falseW przepływach CI/CD, które przechowują wartości parametrów w osobnym pliku (np. w pliku .yaml dla danego środowiska, zapisanym w repozytorium obok encji Release), encja Release używa formy $import:: parameters: { $import: ./prod-values.yaml }. Zawartość pliku zastępuje mapę wpisaną bezpośrednio w encji Release. Ścieżka jest rozwiązywana względem katalogu zawierającego encję Release, niezależnie od tego, skąd uruchomiono polecenie, i musi prowadzić do pliku wewnątrz przestrzeni roboczej — lub, w przypadku encji Release wskazanej spoza przestrzeni roboczej, wewnątrz katalogu, który ją zawiera. Warstwowanie wielu plików (łączenie pliku bazowego z nakładką właściwą dla środowiska) wyraża się łańcuchami extends: encji Release — nadrzędna encja Release dostarcza parametry bazowe, a podrzędna encja Release je rozszerza i nadpisuje dla poszczególnych kluczy.
Cykl życia parametrów. Kompilator rozwiązuje parametry w trzech fazach. (1) Uzupełnienie wartości domyślnych — sloty ze zdefiniowanym default: i bez wartości z encji Release otrzymują wartość domyślną. (2) Walidacja kontraktu parametrów — typowany kontrakt parameters: sprawdza każdą wartość względem zadeklarowanych ograniczeń type / enum / min / max / pattern, łącznie z uzupełnioną wartością domyślną, więc wartość domyślna łamiąca własny kontrakt zatrzymuje kompilację. (3) Interpolacja — kompilator przetwarza cały tekst encji Aggregate jako szablon i zastępuje każde odwołanie {{ .parameters.<slot> }} rozwiązaną wartością. Scalona mapa pozostaje następnie dostępna do odczytu w trakcie renderowania, tak aby szablony ścieżek (directory: / subDirectory: na granicy encji Release) mogły odczytywać .parameters.<slot> bezpośrednio, w ramach zamkniętej listy dozwolonych zmiennych opisanej w ../path-template-variables.md. Miejsca szablonów wartości (valuesMapping encji Recipe, injectMapping / provides / pipeline.with encji FeatureRecipe, treści encji Workload) NIE otrzymują .parameters w swoim kontekście szablonu — korzystają z rozwiązanych wartości wpisanych do otaczających ciągów values: przez interpolację w fazie 3.
Lista kontrolna przenoszenia parametrów
Każda wartość zależna od środowiska przechodzi kolejno przez cztery miejsca w kodzie źródłowym. Model myślowy autora: dla każdej wartości, która różni się między Dev / Staging / Production, należy się spodziewać zmian w encji Aggregate (deklaracja), w szablonie wartości (odwołanie), w encji Release (uzupełnienie) i w szablonie encji Recipe (użycie).
| Krok | Miejsce | Działanie |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | Zadeklaruj parametr jako część typowanego kontraktu encji Aggregate. Każdy slot parametru ma zadeklarowany type (string, integer, number, boolean, array, object), opcjonalny description, opcjonalny default, opcjonalne ograniczenia przestrzeni wartości (enum, min, max, pattern, minLength, maxLength) oraz opcjonalną strukturę zagnieżdżoną dla slotów typu obiektowego. Kontrakt sprawdza każdą wartość dostarczoną przez encję Release przed interpolacją. |
| 2 | Szablon values: encji Component w tej samej encji Aggregate | Odwołaj się do parametru przez {{ .parameters.<name> }} w bloku values: dowolnego komponentu (lub funkcji albo podagregatu), który z niego korzysta. Odwołanie jest wyrażeniem szablonu Go — kompilator ewaluuje je w fazie interpolacji podczas rozwiązywania. |
| 3 | Release spec.parameters.<name> (bezpośrednio lub parameters: { $import: ./path.yaml }) | Uzupełnij parametr wartością właściwą dla środowiska w encji Release. Pliki Release poszczególnych środowisk dostarczają różne wartości dla tego samego klucza parametru bez modyfikowania encji Aggregate. |
| 4 | Szablon valuesMapping: encji Recipe | Użyj rozwiązanej wartości przez {{ .values.<key> }} — encja Recipe jest miejscem szablonu wartości; jej kontekst szablonu nie zawiera bezpośrednio .parameters. Zmienność między środowiskami dociera do encji Recipe przez słownik values: po interpolacji, zapisywany przez opisaną wyżej fazę interpolacji. (Wyjątkiem są szablony ścieżek na granicach encji Release: odczytują .parameters.<slot> bezpośrednio podczas renderowania, zgodnie z asymetrycznym uprawnieniem.) |
Cztery miejsca następują po sobie i są nośne: pominięcie deklaracji w encji Aggregate pozostawia encję Release bez slotu do uzupełnienia; pominięcie odwołania w values pozostawia encję Recipe bez wartości do użycia; pominięcie uzupełnienia w encji Release pozostawia parametr pusty. Kompilator sprawdza ten łańcuch podczas rozwiązywania (walidacja kontraktu parametrów względem typowanej deklaracji parameters:, następnie interpolacja do otaczających ciągów values:, a potem walidacja JSON Schema wynikowego słownika values: względem schema: encji Component lub Feature); niezgodności ujawniają się jako naruszenie kontraktu parametrów (wykryte względem typowanej deklaracji parameters:), błąd nieuzupełnionego szablonu (wykryty podczas interpolacji) albo naruszenie ograniczenia JSON Schema względem schematu values: (wykryte podczas walidacji schematu).
Ten wzorzec jest kanonicznym mechanizmem promocji GitOps: jedna niezmienna encja Aggregate przechodzi przez środowiska, a encja Release każdego środowiska dostarcza własne wartości parametrów. Każda wartość zależna od środowiska, którą autor chce różnicować, należy do łańcucha parametrów, a nie do treści wpisanej bezpośrednio w encję Aggregate.
Semantyka scalania extends: dla poszczególnych filarów
Gdy encja katalogu deklaruje extends:, a kompilator przechodzi łańcuch dziedziczenia, zawartość każdego filaru jest scalana według reguł właściwych dla tego filaru. Semantyka różni się między filarami; poniższa tabela jest kanonicznym odniesieniem dla poszczególnych filarów.
| Filar | Zachowanie scalania w łańcuchu extends: |
|---|---|
values (JSON Schema 2020-12) | W łańcuchu encji Feature schematy są składane za pomocą kompozycji JSON Schema 2020-12. Rozszerzająca encja Component nie definiuje żadnej zawartości filaru i otrzymuje blok swojej encji bazowej dokładnie w takiej postaci, w jakiej zdefiniowała go baza, na każdej głębokości łańcucha. |
infra (fragment JSON Schema 2020-12) | Tak samo jak values — składany w łańcuchu encji Feature, dziedziczony w całości przez rozszerzającą encję Component. |
provides (mapa szablonów encji Recipe) | Płytkie zastępowanie na najwyższym poziomie: klucz potomka w pełni zastępuje klucz rodzica o tej samej nazwie; klucze sąsiednie są zachowywane z rodzica. Szablony nie są składane; szablon potomka w pełni posiada swój slot. |
uses (usesSchema) | Nakładanie całych wpisów dla każdego gniazda według nazwy gniazda. Potomek dodaje gniazda, których jego baza nie deklaruje, a gniazdo ponownie zadeklarowane pod istniejącą nazwą całkowicie zastępuje ten wpis — razem z jego schematami values i infra oraz jego selector. Wpisy gniazd nie są składane i nic nie porównuje ponownie zadeklarowanego selector z selektorem bazy. |
features (schemat dla poszczególnych slotów featuresSchema) | Nakładanie całych wpisów dla każdego slotu według nazwy slotu, na tych samych zasadach co usesSchema. Potomek może swobodnie dodawać sloty; slot, który ponownie deklaruje, całkowicie zastępuje wpis bazy, zamiast być z nim składany. |
locals (mapa szablonów encji Recipe) | Płytkie zastępowanie na najwyższym poziomie — tak samo jak provides. |
parameters (mapa główna encji Aggregate) | Encja Aggregate nie ma pola extends:, więc żaden łańcuch encji Aggregate nie scala parametrów. W łańcuchu extends: encji Release parametr o wartości mapy jest scalany głęboko z pierwszeństwem klucza potomka, parametr o wartości skalarnej jest zastępowany przez potomka, a klucz, który potomek zapisuje jako null, jest usuwany. |
Ogólny wzorzec zależy od rodzaju encji i od miejsca. Filary encji Feature walidowane schematem są składane zgodnie z JSON Schema 2020-12. Filary rozszerzającej encji Component są dziedziczone w całości — nie definiuje ona żadnego, więc jej kontrakt jest dokładnie kontraktem bazy, a zatem ograniczenia bazy nie da się z założenia poluzować. Miejsca o stałym kształcie — usesSchema i featuresSchema — są nakładane według nazwy w obu rodzajach: potomek dodaje wpisy, a wpis ponownie zadeklarowany całkowicie zastępuje wpis bazy. Filary definiowane szablonami używają płytkiego zastępowania dla każdego klucza, dając potomkowi pełną własność każdego zadeklarowanego slotu szablonu.
Rozszerzająca encja Component zaostrza ograniczenie za pomocą assertions:, a nie filaru — jest to dodany przez nią predykat, oceniany wraz z odziedziczonymi. Opis tego mechanizmu znajduje się w inheritance-and-interface.md.
Sam mechanizm dziedziczenia opisano w inheritance-and-interface.md, w sekcji „Dziedziczenie przez extends”, która obejmuje rodzaje encji katalogu. Encja Release nie jest encją katalogu i jest składana według własnej reguły; reguła ta znajduje się w entities/release.md, w sekcji „Złożona encja Release i dziedziczenie extends:”.
Mechanika międzyfilarowa
Ujęcie oparte na drogowskazach pozwala na odczyty międzyfilarowe wszędzie poza udokumentowanymi powierzchniami samowystarczalności. Poniższe wzorce formalizują typowe mechanizmy międzyfilarowe; udokumentowano też jeden niepokojący sygnał w tworzeniu, aby autorzy rozpoznawali związany z nim kompromis.
Międzyfilarowe przekazywanie przez most schematu — oznaczone drogowskazem, nie zamurowane
Granice filarów to dyscyplina autorska: architektura wskazuje drogowskazami, co gdzie trafia (values: dla intencji poznawczej dewelopera, infra: dla fizycznego wymiarowania po stronie Ops, provides: dla ciągów emitowanych przez Recipe itd.), a recenzent katalogu egzekwuje konwencję. Sam silnik szablonów pozwala na odczyty międzyfilarowe, chyba że zabraniają ich udokumentowane reguły samowystarczalności (provides: encji Recipe nie widzi .context.inject; provides: o zakresie granicy w encji FeatureRecipe nie widzi pól poszczególnych konsumentów). Ściany filarów to drogowskazy, nie mechanizm egzekwowania.
Kanoniczny wyjątek oznaczony drogowskazem: schema: encji Component może deklarować skierowane do dewelopera pokrętło values:, które szablon valuesMapping: encji Recipe przekazuje do renderowanego wyjścia o kształcie infra:. Deweloper wyraża intencję przez typowane pole values:; szablon Recipe przekazuje wynikową wartość do warstwy infrastruktury dostawcy, bez pisania przez dewelopera kodu infrastruktury. Przykład:
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"Most jest udokumentowany w inheritance-and-interface.md wraz z przykładami. Intencja architektoniczna (zadeklarowane pokrętło międzyfilarowe, które Recipe przekazuje dalej) działa w jednym kierunku — values: po stronie dewelopera płynie do renderowanego wyjścia po stronie Ops — i trafia do szablonów mapowania encji Recipe, a nie do samego schematu encji Component. Granica filaru pozostaje oznaczona drogowskazem: deweloper widzi values:, Recipe widzi zarówno values:, jak i infra:, a renderowane wyjście łączy je.
Międzyfilarowy akumulator inject
Potok .context.inject jest punktem scalania trzech źródeł obejmujących wiele filarów:
- Samowstrzykiwanie na poziomie encji Component (
component.inject) — pobiera ciągi z własnychvaluesi własnychprovideskomponentu. - Wstrzykiwanie z uses (
uses[].inject) — pobiera ciągi zprovidescelu. - Przechwycenia
injectMapping:w encji FeatureRecipe — pobierają ciągi z dowolnego z powyższych źródeł oraz z własnego ładunkuinfra:encji FeatureRecipe.
W chwili uruchomienia renderowania bazowego .context.inject.<mechanism>.<key> zawiera już wpisy ze wszystkich trzech źródeł. Akumulator jest z założenia międzyfilarowy — wpisy pochodzące z values, provides i infra trafiają do tej samej mapy .context.inject. Recipes korzystające z .context.inject widzą stan po scaleniu i nie muszą wiedzieć, który filar dostarczył który wpis.
Gramatykę wstrzykiwania i reguły kolizji opisano w topology-triad.md.
Międzyfilarowe powielanie ograniczeń
Pole występujące w dwóch filarach z różnymi warstwami walidacji może nieść zduplikowane ograniczenia. Kanoniczny przykład: numer portu zadeklarowany w usesSchema encji Component (walidowany przez JSON Schema, zakres min: 1, max: 65535) i ten sam numer portu użyty w polu services.<name>.ports.<port> encji Workload, dla którego spec.provider.workloadSchema wtyczki renderującej dostawcy może dodać regułę min: 1024 dla portów nieuprzywilejowanych. spec.provider.workloadSchema encji Plugin renderującej dostawcy opisuje, jak dostawca tłumaczy encję Workload, i oznacza dostawcę jako zdolnego do jej syntezy; niczego nie waliduje. Każda treść Workload jest walidowana względem schematu Workload platformy, niezależnie od dostawcy, więc ograniczenie zapisane tylko w workloadSchema — np. reguła portu min: 1024 — nie jest egzekwowane; aby odrzucić taką wartość, należy umieścić ograniczenie w schemacie encji Component lub w asercji.
Dołączenie Feature / izolacja filarów Component
Dołączenie Feature nie zapisuje do filarów nadrzędnej encji Component. Każda dołączona encja Feature niesie własny ładunek filarów (własny blok values: i własny blok infra:). FeatureRecipe syntetyzująca zasoby encji Feature odczytuje własny ładunek filarów niezależnie od ładunku encji Component. Izolacja dotyczy wejść: to, co odczytuje dołączenie, należy do niego, niezależnie od tego, co stanie się z tym, co zapisuje. Gdy dostawca celu zapisuje odrębne dokumenty, renderowane wyjście dołączenia leży obok wyjścia encji Component we własnym katalogu; gdy dostawca składa współtwórców granicy w jeden dokument, dołączenie współtworzy ten dokument tak jak Component, a każdy zasób nadal nosi własną tożsamość dołączenia, dzięki czemu pochodzenie poszczególnych elementów pozostaje czytelne.
Dwie konsekwencje dla autorów:
- Ustawienie
values:w dołączeniu Feature nie pojawia się w.valuesszablonuvaluesMapping:encji Component. Component widzi wyłącznie własne wartości. - Ładunek
infra:encji Feature nie trafia doinfra:encji Component. Każda dołączona encja Feature ma własne wymiarowanie fizyczne, ograniczone do zasobów tej encji Feature.
Izolacja wynika wprost z rozdzielenia odpowiedzialności w architekturze: Features to niezależni współtwórcy nakładani na Components za pomocą 5-warstwowego modelu cebuli. Powierzchnie dołączania i ich kolejność opisano w labels-and-annotations.md, „Feature attachment — five surfaces”.
Ta sama nazwa właściwości w obu filarach
Encja Component lub Feature, której spec.schema.values: i spec.schema.infra: deklarują tę samą nazwę właściwości — na poziomie głównym, na dowolnej głębokości zagnieżdżenia lub w obu miejscach — to częsty sygnał złego stylu autorskiego. Oba filary są z założenia odrębnymi przestrzeniami nazw (kompilator akceptuje nakładanie się), więc schemat przechodzi walidację, a renderowane wyjście jest poprawnie sformułowane. Problem jest poznawczy: czytelnicy i autorzy szablonów za każdym razem, gdy przeglądają schemat lub piszą względem niego szablon, napotykają pytanie „w którym filarze jest foo, które czytam?”.
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }Autorzy z zamierzonym nakładaniem się mają rzeczywisty powód, by zachować oba — np. mode oznaczające „tryb działania aplikacji” w values ("debug" / "production") i „tryb topologii wdrożenia” w infra ("standalone" / "clustered") ma odrębną semantykę, a nazwy po prostu się pokrywają. Autorzy z przypadkowym nakładaniem się (częstszy przypadek) zmieniają nazwę jednego wpisu.
Drugi zamierzony kształt to jedna dana, którą może dostarczyć każdy z autorów. Features biblioteki standardowej dotyczące poświadczeń, które przenoszą lokalizator wywołującego — core/referenced-secret, core/referenced-secret-set, core/secret-value i core/secret-provided — deklarują go w obu filarach pod jedną nazwą i w jednym kształcie, tak aby deweloper zapisał go w values albo operator w infra, a własna asercja każdej encji Feature odrzuca dołączenie, które zapisuje go w obu filarach lub w żadnym. Poniższe ostrzeżenie wymienia te cztery przy każdym ładowaniu, które do nich dociera; w ich przypadku informuje o kontrakcie, a nie o pomyłce.
Ładowanie katalogu emituje ostrzeżenie notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) dla każdej właściwości o tej samej nazwie, której nakładanie się kończy się liściem terminalnym po co najmniej jednej stronie. Właściwości o tej samej nazwie istniejące jako wspólne przestrzenie nazw porządkujące (oba filary mają obiekt o nazwie ingress z rozłącznymi podwłaściwościami) nie powodują ostrzeżenia; zgłaszane jest tylko nakładanie się liści. Ostrzeżenie ma charakter doradczy — kompilacja jest kontynuowana.
Poziomy walidacji filarów
Walidacja filarów odbywa się na trzech poziomach. Każdy poziom obejmuje inny aspekt; to samo pole może być walidowane przez więcej niż jeden poziom (zob. „Duplikacja ograniczeń między filarami” powyżej).
| Poziom | Co waliduje | Gdzie działa |
|---|---|---|
| 1 — koperta JSON Schema | Kształt strukturalny (które klucze są obecne, czy typy odpowiadają deklaracjom pól) | Rozwiązywanie, przy wczytaniu każdego pliku |
2 — schemat danego filaru (schema / featuresSchema / usesSchema) | Typowana treść danego filaru walidowana jako JSON Schema 2020-12 | Rozwiązywanie, po pomyślnej walidacji koperty |
| 3 — bramka możliwości providera | Treść encji Workload dopuszczana na podstawie możliwości trybu syntetyzowanego powiązanego providera, udokumentowanej przez spec.provider.workloadSchema pluginu renderującego providera | Renderowanie bazowe, po rozwiązaniu valuesMapping |
Tabela kształtów błędów dla czterech warstw oraz prefiksy błędów poszczególnych warstw znajdują się w validation-surface.md.
Mechanizmy wartości domyślnych
Wartości domyślne pojawiają się w korpusie za pośrednictwem kilku odrębnych mechanizmów. Autorzy napotykają słowo „default” w co najmniej pięciu kontekstach; poniższa tabela jest kanonicznym odniesieniem wskazującym, który mechanizm wytwarza wartość, gdy autor pozostawi pole puste.
| # | Mechanizm | Gdzie zapisywane | Wyzwalacz |
|---|---|---|---|
| 1 | JSON Schema default: (forma zwarta { default: <value> }) | Component / Feature schema:, Aggregate parameters: | Pole przechodzi walidację z wartością domyślną, gdy deweloper pominie klucz. W przypadku parametrów encji Aggregate scalanie parametrów wypełnia zadeklarowaną wartość domyślną przed uruchomieniem walidacji kontraktu (zob. templates/parameters-context.md). |
| 2 | Szablon Go optional .X `Y` <fallback> | Recipe valuesMapping:, treść Workload, szablony FeatureRecipe, ewaluator asercji | Wartość zastępcza uwzględniająca obecność — zwraca <fallback> tylko wtedy, gdy klucza nie ma w mapie; zapisane przez autora zero / pusta wartość / false pod kluczem zwraca tę zapisaną wartość. Kanoniczny po stronie Aggrega kształt wartości zastępczej dla nieobecnego pola. Zob. templates/sprig-functions.md. |
| 3 | Szablon Go | default <expr> | Recipe valuesMapping:, treść Workload, szablony FeatureRecipe | Potok wbudowany, który zadziała przy wartości „pustej” (sprawdzenie pustości w Sprig — zero, pusty ciąg, false, nil). Utożsamia brak w mapie z obecnością wartości zero/pustej/false. Odpowiedni dla semantyki nadpisania w konkretnym miejscu wywołania (wartość zastępcza powiązania różni się od wartości domyślnej pola na poziomie schematu), gdy to utożsamienie jest dopuszczalne. Nieodpowiedni dla wartości zastępczej nieobecnego pola, gdy zapisane zero / pusta wartość / false jest uprawnioną intencją — w takim przypadku należy użyć optional (mechanizm 2). |
| 4 | Funkcja Sprig default ({{ default <expr> .field }}) | Jak w 3 | Forma funkcyjna mechanizmu 3 z tym samym utożsamieniem pustości. |
| 5 | Wartość zastępcza w Recipe locals: | Szablon Recipe locals: | Wpis locals oblicza ciąg zawierający wartość domyślną, z którego korzysta reszta encji Recipe |
Zalecenia dotyczące umiejscowienia. Gdy wartość domyślna rzeczywiście jest częścią kontraktu typu (np. „ten port ma domyślnie wartość 5432, o ile deweloper jej nie nadpisze”), kanoniczny jest JSON Schema default: (mechanizm 1) — autouzupełnianie w IDE pokazuje wartość domyślną, narzędzia walidacji ją respektują, a kontrakt przenosi się wraz z encją katalogu Component / Feature LUB z deklaracją parametru encji Aggregate. Gdy szablon encji Recipe potrzebuje wartości zastępczej dla opcjonalnego klucza mapy, kanonicznym kształtem wartości zastępczej nieobecnego pola jest funkcja pomocnicza optional (mechanizm 2) — odróżnia ona zapisane zero / pustą wartość / false od braku. Szablon Go | default (mechanizm 3) jest zarezerwowany dla przypadku nadpisania w konkretnym miejscu wywołania, gdy utożsamienie wartości nieobecnych i fałszywych jest dopuszczalne; należy po niego sięgać tylko wtedy, gdy semantyka nadpisania jest wyraźną intencją.
Odsyłacze
inheritance-and-interface.md— mechanizmextends:, Interface Bindingimplements:, przekazywanie danych między filarami przez most schematów.topology-triad.md— mechanika topologicznaprovides,injectiuses.labels-and-annotations.md— słownictwo metadanych po stronie treści, odrębne od filarów danych (przedstawiona wyżej kanoniczna lista filarów nie obejmuje etykiet, adnotacji ani pól publikacji — należą one do słownictwa metadanych).publishing-surface.md— słownictwo metadanych po stronie publikacji, odrębne od filarów danych.validation-surface.md— cztery warstwy walidacji schematów, w tym opisane wyżej trzy poziomy walidacji filarów.templates/expansion-matrix.md— dostępność odczytów między filarami w poszczególnych miejscach szablonów oraz reguły samowystarczalności wprovides:isource:encji Recipe.examples/04-secrets.md— lista kontrolna dostarczania sekretów z sześcioma punktami styku.architecture/06-data-taxonomy-and-composition.md— kanoniczne ujęcie koncepcyjne pięciu strukturalnych słów kluczowych DSL.