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

Recipe

Koncepcyjna rola encji Recipe (tworzonego przez zespół Ops szablonu translacji, który odwzorowuje intencję dewelopera na format fizyczny) jest opisana w architecture/04-entity-taxonomy.md. Ta strona omawia powierzchnię tworzenia encji Recipe — wskaźnik (source), mapper (valuesMapping:), natywne wsparcie IaC oraz przykłady.

Architektura encji Recipe: wskaźniki i mapery

Recipe pełni dokładnie dwie funkcje:

  1. Wskaźnik (source): wskazuje kompilatorowi dokładnie, gdzie znajduje się kod infrastruktury.
  2. Maper (valuesMapping): wstrzykuje abstrakcyjny kontekst Aggrega do konkretnych zmiennych, których oczekuje bazowy kod. Pole jest pojedynczą powierzchnią szablonu Go z trzema trybami tworzenia — wbudowany skalar blokowy, plikowy $import: lub biblioteczny $import: — wybieranymi na podstawie kształtu treści. Zobacz niżej Pole valuesMapping — trzy tryby tworzenia.

Ponieważ Recipe odpowiada ściśle 1:1 jednej możliwości renderowania, ta możliwość (spec.capability) jest jawnie deklarowana na poziomie głównym, dzięki czemu kompilator Go wie dokładnie, który dalszy plugin renderujący Wasm wywołać.

spec.implements deklaruje, jaki typ komponentu z katalogu Recipe może implementować. Kompilator używa go do weryfikacji mapowań w Manifest (implements zmapowanej Recipe musi odpowiadać zmapowanemu typowi) oraz do podpowiadania kandydatów — receptur wymienianych w diagnostyce braku mapowania i umieszczanych najwyżej w uzupełnianiu w edytorze. Nigdy nie rozstrzyga o kompilacji: mapowanie w Manifest jest jawnym wyborem wdrożeniowym użytkownika, przypiętym w pliku blokady. Recipe, której implements jest bez wersji, dokładne lub jest zakresem zgodnym w obrębie wersji głównej, nadal jedynie oferuje się dla danego typu; wybór przypina użytkownik. FeatureRecipe.spec.implements pełni identyczną rolę dla typów funkcji.

A. Schematy źródeł sterowane przez Wasm

Aby uprzedzenia związane z implementacją nie trafiały do kompilatora, blok source nie jest stałym zestawem pól infrastruktury. Pole source obsługuje dwa formaty:

  • Uniwersalny ciąg znaków (szybko i czysto): najlepszy dla ścieżek lokalnych, artefaktów OCI i repozytoriów Git. Kompilator wywnioskowuje metodę pobierania z prefiksu i sufiksu ciągu (./src, https://github.com/example/module.git, oci://...): URL kończący się na .git albo zapisany z git:// lub ssh:// to repozytorium Git pobierane z domyślnej gałęzi, a URL https://, który nie wskazuje ani repozytorium, ani chartu .tgz, ani fragmentu .yaml, jest odrzucany jako niejednoznaczny.
  • Otwarty obiekt strukturalny: otwarty słownik (additionalProperties: true), którego klucze definiuje provider i które są udostępniane szablonom encji Recipe jako .source.* (na przykład .source.chart). Założeniem projektu jest, aby gniazdo WebAssembly każdego providera definiowało i walidowało własny kształt źródła (np. registry/chart/appVersion dla Helm).

Co rozstrzyga rdzeń. Żaden dostawca nie waliduje własnych kluczy źródła. Źródło pobierane jest rozstrzygane przez wbudowaną tożsamość, której kind wybiera mechanizm rozstrzygania — helm-oci-chart, helm-https-chart, compose-https-fragment oraz git-repository. Źródło przeznaczone do pobrania musi zawierać kind i url; to, która dalsza współrzędna wybiera treść, zależy od rodzaju. Rodzaje chartów i fragmentów przyjmują version i przypinają ją tak, jak została zapisana. git-repository przyjmuje ref — tag, gałąź lub commit — oraz opcjonalnie module_subdir, wskazujący katalog w repozytorium będący artefaktem; ponieważ tylko commit wskazuje treść, której nie można przepiąć, odwołanie jest rozstrzygane w czasie blokowania, a plik blokady zapisuje zarówno odwołanie w postaci napisanej przez autora, jak i commit, na który zostało rozstrzygnięte. Wartość module_subdir, która w zapisanej postaci wychodzi ponad repozytorium — ukośnik wsteczny liczy się jako separator — jest odrzucana, zanim cokolwiek zostanie pobrane. Repozytorium jest archiwizowane z własnego checkoutu: zatwierdzone w nim dowiązanie symboliczne jest archiwizowane jako plik lub katalog, na który wskazuje, jeśli leży on wewnątrz repozytorium, a dowiązanie prowadzące poza nie zatrzymuje pobieranie, wskazując dowiązanie po jego miejscu w repozytorium. Źródło strukturalne, którego url: wskazuje ścieżkę w systemie plików, nie jest pobierane: jest odczytywane z dysku na tych samych zasadach co sam ciąg ścieżki, przy czym względny url: jest zakotwiczony w katalogu zawierającym plik encji, który go deklaruje. Źródło strukturalne pomijające kind/url również nie jest pobierane, a jeśli pobranie było zamierzone, kompilacja zatrzymuje się głośno na etapie schodzenia po źródłach w czasie blokowania, zamiast po cichu rozstrzygnąć się do niczego. Treść zawsze jest przypinana z wyprzedzeniem; kompilator nigdy nie pobiera bieżącego stanu środowiska uruchomieniowego.

Co jest przypinane obok encji Recipe. Dla pobieranego źródła, którego kind, url, chart, module_subdir, version i ref są zapisane wprost, a nie szablonowane, aggrega pin zapisuje skrót tego, co pobrało, w entity.lock — pliku w katalogu encji Recipe, który należy zatwierdzić obok niej. Przypinanie jest krokiem autora encji Recipe i nie wymaga encji Release; pull nad encją Recipe, której lock nie zapisuje przypięcia, zatrzymuje się i je wskazuje, chyba że pull ma wykonać ten sam krok. Kompilacja porównuje ten skrót ze skrótem zapisanym dla tego samego źródła w pliku lockfile encji Release i zatrzymuje się, gdy się różnią — z wyjątkiem źródła zapisanego przy gitowym ref:, którego wiersz jest zapisywany przy commicie, na który rozwiązano ref, i nie jest porównywany. Pobierane źródło, którego współrzędne są wypełniane z szablonu, jest zamiast tego przypinane dla każdej encji Release osobno, w jej pliku lockfile. Źródło wskazujące katalog lub plik obok encji Recipe nie jest pobierane: aggrega pin zapisuje po jednym skrócie dla każdego pliku, który wnosi do tego, co zawiera publikacja encji Recipe — każdego pliku w katalogu encji Recipe, w przypadku źródła zapisanego jako szablon — a gdy lock je zapisze, kompilacja porównuje z nimi źródło, zanim odczyta je provider, i zatrzymuje się na pliku dodanym, zmienionym lub usuniętym od czasu przypięcia — z E0305 albo najpierw z E0130, jeśli lockfile encji Release, zapisany przed zmianą, rejestruje encję Recipe według tego, co zawiera. Lock bez przypięcia dla takiego źródła nie daje kompilacji niczego do porównania, a pull lub publikacja, która nie przypina, odrzuca je. Sam plik encji Recipe nigdy nie jest zapisywany. aggrega pull opisuje ten plik i sposób reagowania na każde zatrzymanie.

spec.capability może zawierać przypięcie wersji w formach, które przyjmuje implements — dokładnej (helm:<version>) lub zakresu z daszkiem (helm:^<version>) — wybierające, która wersja pluginu dostawcy renderuje encję Recipe; przypięcie, którego nie spełnia żadna dostępna wersja, zatrzymuje kompilację. Bez przypięcia (spec.capability: "helm") renderuje najwyższa dostępna wersja. Dostępne wersje to te, które pokazuje aggrega plugin list: dostawcy wbudowani w aggrega mają wersję samego kompilatora. Przypięcie nie jest częścią nazwy encji Recipe: encja Manifest mapuje encję Recipe deklarującą capability: "compose:1.2.3" jako compose/<name>:<version>, dokładnie tak jak nieprzypiętą, a zmiana przypięcia nigdy nie zmienia jej nazwy; wartość mapowania zapisująca przypięcie w nazwie (compose:1.2.3/<name>:<version>) jest odrzucana jako błędnie sformułowana referencja recipe (E0095), zanim cokolwiek zostanie wyszukane.

Model myślowy: spec.capability określa żądany format wyjściowy (np. helm, terraform, compose); kompilator rozwiązuje go na plugin Wasm renderujący ten format (np. provider/helm). Użytkownik deklaruje format; Aggrega wiąże narzędzie.

B. Wstrzykiwanie kontekstu: semantyczna warstwa mapowania

Aby kompilator nie wykonywał niebezpiecznych, niedeterministycznych głębokich scaleń między wieloma środowiskami, Recipe dopuszcza dla swojej warstwy mapowania tylko jedno źródło prawdy.

Inżynierowie Ops tworzą treść mapowania, która tłumaczy abstrakcyjny kontekst, zanim zostanie uruchomiony plugin renderujący Wasm. Językiem mapowania jest szablon Go (text/template + Sprig); biblioteka Sprig jest wstępnie zarejestrowana; standardowe akcje define i template są obsługiwane, a include nie jest zarejestrowane.

Nazwa polaZakres i faza wykonaniaNajlepszy przypadek użycia
injectMapping (tylko FeatureRecipe)Przechwycenie przed renderowaniem. Ewaluowane w pamięci Go przed bazową encją Recipe. Natywnie scala głęboko swój słownik wyjściowy ściśle ponad potokiem .context.inject wywołującego. Celowo nieobecne w schemacie bazowej encji Recipe — uzasadnienie architektoniczne opisuje entities/featurerecipe.Chirurgiczne przepisywanie wstrzykniętych zmiennych env lub formatowanie nazw FQDN dla wywołującego bez potrzeby użycia Wasm JSONPatch.
valuesMappingRenderowanie bazowe (Go template). Ewaluowane w celu zmapowania zmiennych do bazowego chartu/modułu infrastruktury source. Jedno pole, trzy tryby tworzenia (inline, plik $import:, biblioteka $import:). Mechanizm rozdziału opisano w podsekcji poniżej.Mapowanie standardowych zmiennych (takich jak liczba replik czy tagi obrazów) na chart Helm bezpośrednio w YAML encji Recipe lub odwołanie do współdzielonego szablonu przez $import: w celu ponownego użycia między encjami Recipe.

Uwaga: injectMapping występuje wyłącznie w encjach FeatureRecipes i oddziela przechwytywanie zmiennych od valuesMapping. Pole valuesMapping bazowej encji Recipe nieświadomie konsumuje przepisane ciągi .context.inject wygenerowane przez bloki injectMapping encji FeatureRecipe, więc oba pozostają rozdzielone.

Klucz, który valuesMapping zapisuje jako null, trafia do providera jako null, a to, co się z nim tam dzieje, określa provider, dlatego opisuje to strona każdego providera: helm usuwa wartość domyślną chartu dla tego klucza, helm-chart zapisuje go w wartościach chartu nadrzędnego, compose zapisuje go w pliku compose, terraform zapisuje go jako argument modułu null, a cloudformation go odrzuca.

Pole valuesMapping — trzy tryby tworzenia

Pole valuesMapping: encji Recipe to jedna powierzchnia szablonu Go, która przyjmuje trzy tryby rozdziału. Kompilator wybiera tryb na podstawie kształtu zawartości pola; adnotacja $mode: nie jest potrzebna.

Tryb 1: szablon Go inline (skalar blokowy YAML). Wartością pola jest ciąg zapisany w formie skalara blokowego YAML |:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

Tryb inline to typowa forma tworzenia dla encji Recipes, których treść mapowania jest mała lub średnia (poniżej ok. 50 wierszy). Treść szablonu znajduje się inline wraz z resztą koperty encji Recipe; zawartość encji Recipe jest samowystarczalna.

Tryb 2: plikowy $import:. Wartością pola jest mapa zawierająca wyłącznie klucz $import: ze ścieżką do pliku lokalnego:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

Kompilator wczytuje zawartość pliku (szablon Go), renderuje ją względem standardowego kontekstu szablonu encji Recipe i traktuje wynik jako wyjście mapowania. Ścieżki są rozwiązywane względem katalogu encji Recipe — ścieżka względna jest zakotwiczona w katalogu zawierającym plik recipe.yaml, który ją deklaruje, a nie w katalogu, z którego uruchomiono build — i musi pozostać wewnątrz tego katalogu, jak wyjaśnia sekcja Ścieżki treści pozostają wewnątrz własnego katalogu encji Recipe. Tryb pliku pasuje do średniej i dużej treści mapowania (ok. 50+ wierszy) oraz do wzorców przeglądu, w których zmiany mapowania pojawiają się jako osobne różnice plików.

Tryb 3: biblioteczny $import:. Wartością pola jest mapa zawierająca wyłącznie klucz $import: z odwołaniem tożsamościowym w postaci samej nazwy do wpisu encji MappingLibrary:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

Kompilator rozwiązuje odwołanie względem rozwiązanego zbioru encji MappingLibrary (lokalny katalog plus biblioteki przypięte w pliku lockfile), wczytuje zawartość wpisu i traktuje ją jako wyjście mapowania; wpis, którego treść sama jest polem-korzeniem $import:, jest rozwiązywany rekurencyjnie. Odwołanie nie zawiera hosta rejestru — nazwa biblioteki jest rozwiązywana według tożsamości, a wersja pochodzi z pliku lockfile danej encji Release, z opcjonalnym dolnym ograniczeniem wersji :<version> (<Library>:<version>#/mappings/<entry>). Zawartość biblioteki korzysta ze standardowego kontekstu szablonu encji Recipe. Tryb biblioteki pasuje do ponownego użycia między encjami Recipe — wzorców mapowania powtarzających się w wielu encjach Recipes (wiele encji Recipes magazynów danych współdzielących logikę pomocniczą; wiele encji Recipes providera Helm współdzielących wzorce szablonów podów). Encja MappingLibrary zapewnia wersjonowanie, przypinanie w pliku lockfile i prezentację w interfejsie huba.

Reguły rozdziału. Kompilator przechodzi po węźle YAML i wybiera tryb według kształtu zawartości:

  1. Jeśli węzeł jest skalarem tekstowym, wybierany jest tryb inline (tryb 1).
  2. W przeciwnym razie węzeł jest mapą; sprawdzana jest obecność klucza $import:.
  3. Jeśli wartość $import: jest odwołaniem do biblioteki w postaci samej nazwy (<Library>#/mappings/<Entry>, opcjonalnie z ograniczeniem :<version>), wybierany jest tryb biblioteki (tryb 3).
  4. W przeciwnym razie (ścieżka do pliku lokalnego) wybierany jest tryb pliku (tryb 2).
  5. Każdy inny kształt (mapa bez klucza $import:, mapa z dodatkowymi kluczami poza $import: itp.) powoduje błąd w czasie budowania.

Tylko jednoźródłowy $import:. $import: przyjmuje jedno źródło. Scalanie wielu źródeł nie jest obsługiwane w valuesMapping:. Recipe, która musi złożyć wiele fragmentów mapowania, używa wpisu encji MappingLibrary z wewnętrzną kompozycją szablonu Go define / template, pliku lokalnego z dyrektywami szablonu Go template wywołującymi pliki sąsiednie lub kompozycji inline dla krótkiej treści. Encję biblioteki opisuje entities/mappinglibrary, szersze rozróżnienie $ref: / $import: opisuje vocabulary/cross-document-ref.

Pochodzenie. Komunikaty o błędach renderowania szablonów wskazują odpowiednie pochodzenie dla każdego trybu: szablony inline wskazują plik:wiersz encji Recipe, w którym zaczyna się skalar blokowy; importy plików wskazują zawartość importowanego pliku; importy bibliotek wskazują pozycję źródłową wpisu encji MappingLibrary, a kanonicznym wskaźnikiem dla stabilnych odwołań jest tożsamość biblioteki bez hosta (<Library>#/mappings/<entry>) — host rejestru w odwołaniu jest odrzucany, więc fizyczna lokalizacja nigdy nie trafia do wskaźnika.

C. Natywna obsługa IaC

Zespół Ops wnoszący własną infrastrukturę jako kod trzyma ją we własnym katalogu encji Recipe — w katalogu modułu lub szablonu, takim jak ./src, wskazanym przez source: — albo pobiera ją za pomocą strukturalnego source: (moduł Terraform z jego repozytorium git, z kind: git-repository), albo zapisuje ją jako szablonowe treści pod artifacts:. Warstwa mapowania (valuesMapping: — inline, import pliku lub import z biblioteki) dostarcza temu kodowi abstrakcyjny kontekst, a dostawca emituje wynik we własnym formacie celu; żaden język konfiguracji nie jest konwertowany na inny:

  1. Terraform: moduł jest dołączany plik po pliku, a napisana treść jest emitowana dokładnie tak, jak została zapisana, zarówno natywny HCL (main.tf), jak i Terraform JSON (.tf.json) — CLI terraform odczytuje oba. Konfiguracja główna granicy, aggrega.modules.tf, wywołuje katalog każdego komponentu jako blok module, a wynik valuesMapping: modułu ze źródła staje się argumentami tego bloku. Zob. dostawca terraform.
  2. CloudFormation: szablon ze źródła, YAML lub JSON, oraz fragmenty zasobów, które pisze encja Recipe, są normalizowane do długiej formy JSON i scalane w jeden szablon stosu na granicę, przy czym wynik valuesMapping: wypełnia parametry deklarowane przez szablon ze źródła. Zob. dostawca cloudformation.

Wartość, która istnieje dopiero po zastosowaniu infrastruktury, pozostaje wskaźnikiem rozwiązywanym przez cel — interpolacją Terraform ${ ... }, Ref lub Fn::GetAtt CloudFormation — i nigdy nie jest ewaluowana w czasie kompilacji.

Przykład A: zdalny chart Helm (mapowanie inline i kontrakt locals)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

Przykład B: lokalny moduł Terraform (mapowanie z pliku)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

Przykład C: konkretny Component Recipe (wiąże infrastrukturę) Ops mapuje ogólny interfejs na fizyczną rzeczywistość. (W tym miejscu wiązane są szczegóły sieci L4 — albo zakodowane na stałe, albo, jak port proxy poniżej, pobrane z bloku infra, który wypełnia encja Release).

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Dyscyplina nazewnictwa zasobów chmurowych.

Recipes emitujące nazwy zasobów chmurowych — nazwy bucketów S3, identyfikatory baz danych RDS, nazwy ról IAM, nazwy stosów CloudFormation oraz każde inne pole, którego wartość zajmuje globalną przestrzeń nazw u dostawcy chmury — muszą wpleść {{ .metadata.release_name }} i/lub {{ .context.instance_id }} w renderowaną nazwę, aby uniknąć kolizji, gdy ten sam Recipe działa w wielu Releases lub instancjach komponentów. Kanonicznym wzorcem jest bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" z przykładu B.

Dyscyplina ta obowiązuje wszędzie tam, gdzie nazwę ogranicza jedna globalna przestrzeń nazw. Nazwy bucketów AWS S3 współdzielą globalną przestrzeń nazw we wszystkich kontach w regionie; dwie encje Release tego samego Aggregate (prod-billing i staging-billing) nie mogą obie wdrożyć bucketów o nazwie customer-data — drugie wdrożenie kończy się niepowodzeniem w czasie działania, odrzucone po stronie AWS. Wplecenie release_name rozróżnia encję Release; wplecenie context.instance_id rozróżnia instancje komponentu; wplecenie obu rozróżnia komponent w obrębie każdej encji Release.

Co kompilator sprawdza, a czego nie. Kompilator nie przegląda wyników valuesMapping: pod kątem pól z nazwami zasobów chmurowych pozbawionych tych interpolacji. Dyscyplinę tę utrzymują autorzy Recipe (którzy wiedzą, które pola nazywają globalnie unikalne zasoby u docelowego providera) oraz recenzenci (którzy wychwytują wzorce nienazwanych zasobów podczas przeglądu PR). Plugin lintera mógłby oznaczać Recipes, których wyniki valuesMapping: odwołują się do pól z nazwami zasobów chmurowych bez interpolacji release_name / instance_id; gniazdo lintera jest dostępne i działa przez aggrega lint (zob. plugins/plugin-contract.md „Placement criterion: the linter socket vs the governance verdict roles”), a żadna z reguł lintera publikacji tego nie sprawdza.

Ta dyscyplina jest jedną z kilku umów społecznych utrzymywanych przez konwencję — dyscypliną autorską, której autorzy uczą się z dokumentacji, a nie z egzekwowania przez kompilator. Pełną listę konwencji oraz uzasadnienie architektoniczne klasyfikacji każdej umowy zawiera vocabulary/social-contracts.md.

Szablony w polu source. Pole source encji Recipe samo w sobie jest powierzchnią szablonów. Oba kształty pola source przyjmują szablony Go: postać uniwersalnego ciągu znaków

source: "{{ optional .infra `module_path` \"./src\" }}"

oraz forma obiektu strukturalnego (każde podpole o wartości tekstowej jest ewaluowane jako szablon; podpola nietekstowe przechodzą bez zmian). To, co szablon źródła może odczytać, zależy od tego, czy źródło wskazuje zdalny artefakt. Współrzędna zdalnego źródła — version, chart, ref i module_subdir bloku strukturalnego wskazującego rejestr, repozytorium chartów lub repozytorium git — jest ewaluowana, gdy aggrega pull rozwiązuje artefakt w celu jego przypięcia, wyłącznie względem .values, .infra i .locals, z własnymi helperami Aggrega (optional, capitalizedWords i index) i bez żadnych funkcji Sprig. .context nie należy do tej powierzchni, więc to, który artefakt zostanie przypięty dla komponentu, zależy od przekazanych mu wartości i infra, a nigdy od nazwy jego instancji. Ewaluowane są tam te wpisy locals:, które odczytują te pola, oraz te, które z kolei odczytuje taki wpis: wpis, którego nie odczytuje żadne pole źródła, nie jest ewaluowany podczas rozwiązywania źródła, więc lokalna wartość potrzebna tylko przy renderowaniu — wywołująca funkcję Sprig lub odczytująca .context.instance_id — nie wpływa na przypinanie i jest ewaluowana podczas renderowania węzła. Jeśli pole odczytuje .locals w sposób niewskazujący konkretnego wpisu, np. {{ index .locals "version" }}, ewaluowane są wszystkie wpisy. Źródło wskazujące ścieżkę w obszarze roboczym, jak powyższe, nie jest rozwiązywane na potrzeby przypinania: jego szablon jest ewaluowany podczas renderowania węzła, względem tego samego samowystarczalnego kontekstu co locals w Recipe — .context.instance_id, .values, .infra i .locals, czyli cały rozwiązany blok węzła — dlatego dopuszcza i odrzuca te same korzenie odwołań co wpis locals:, z jedną różnicą na jego korzyść: może odczytać dowolny wpis zadeklarowany w bloku, nie tylko wpisy powyżej. Zdalna współrzędna również może odczytać dowolny wpis zadeklarowany w bloku. .provides nie należy do żadnego z tych kontekstów, a szablon źródła sięgający po provides własnego węzła zatrzymuje budowanie i wskazuje błędne odwołanie. Jest to stała właściwość tej powierzchni, a nie luka czekająca na dalsze prace — wartości lokalne węzła są rozwiązywane przed jego provides, aby provides: mógł odczytywać .locals, a szablon źródła odczytuje te same rozwiązane wartości lokalne zamiast sięgać naprzód po provides. Odwołania do .context.inject i .context.uses są zabronione z tych samych względów samowystarczalności; URI źródła musi zostać rozwiązany, zanim potok topologii zostanie wypełniony i zanim cokolwiek dalej załaduje treść chartu, modułu lub artefaktu, na który wskazuje URI. Pełne reguły dostępności i uzasadnienie zabronionych odwołań zawiera wiersz nr 5 macierzy rozwijania szablonów. Kanonicznym zastosowaniem jest udostępnione przez Component nadpisanie infra.source_version przekazywane do pola wersji źródła — zob. entities/component „The infra Pillar” — dzięki czemu katalog nie musi ponownie publikować encji Recipe przy każdym zgodnym podniesieniu wersji upstream.

Wykaz schematów pola source. Pole source: przyjmuje w schemacie kilka wariantów kształtu. Obsługa każdego wariantu w czasie działania zależy od providera; poniższa tabela dokumentuje, co robi każdy kształt.

KształtPrzykładStatus
Goła względna ścieżka systemu plikówsource: "./charts/postgres"available — każdy dostępny provider (helm, helm-chart, compose, terraform, cloudformation) przyjmuje gołą ścieżkę systemu plików jako ciąg znaków.
Goła bezwzględna ścieżka systemu plikówsource: "/abs/path/to/chart"accepted but blocked — schemat ją przyjmuje, a każde polecenie odczytujące Recipe ją odrzuca: ścieżka bezwzględna wskazuje miejsce na maszynie, na której ją zapisano, a nie treść w katalogu samego Recipe, więc nie przeniosłaby się razem z Recipe. Należy przenieść chart do katalogu Recipe i wskazać go względem niego; zob. Ścieżki treści pozostają w katalogu samego Recipe.
Pusty ciąg znakówsource: ""accepted but blocked — schemat przyjmuje pusty ciąg znaków, a każde polecenie ładujące encję Recipe odrzuca go podczas jej odczytu, ponieważ pusty ciąg nie wskazuje żadnego z dwóch trybów. Odmowa wskazuje niejednoznaczność wraz z dwoma wyjściami z niej: pominąć pole dla trybu bez źródła albo podać rzeczywistą ścieżkę lub URI dla trybu ze źródłem. aggrega validate <recipe-file> zgłasza go dla encji Recipe, a aggrega pull, aggrega build i aggrega validate --release zgłaszają go dla encji Release, która dociera do encji Recipe. Zob. errors/fatal-halts.md „Recipe source: is an empty string (Pole source w Recipe jest pustym ciągiem znaków)”.
Obiekt strukturalny, którego url: zawiera schemat transportusource: { url: "oci://…/mariadb", version: "25.0.8" }available — wbudowany mechanizm rozwiązywania źródeł odczytuje formę {kind, url, version, chart, ref, module_subdir} (schemat w url: wybiera rodzaj — oci:// → chart OCI, https://….tgz → archiwum chartu, katalog główny repozytorium https:// w parze z chart: → chart z repozytorium — albo rodzaj można wskazać przez kind:), pobiera i przypina artefakt podczas aggrega pull, a build wypakowuje go z pamięci podręcznej. Lokalne dołączenie chartu do repozytorium jest obsługiwane jako alternatywa i nie jest wymagane. Schemat akceptuje otwarty obiekt strukturalny. Zob. providers/helm.md „Zestaw kluczy source:”.
Obiekt strukturalny, którego url: wskazuje ścieżkę w systemie plikówsource: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — url: bez schematu transportowego wskazuje ścieżkę, więc nic nie jest pobierane ani przypinane; build odczytuje zawartość z dysku. Względny url: jest zakotwiczony w katalogu zawierającym recipe.yaml, który go deklaruje, a taki, który opuszcza ten katalog — łącznie z bezwzględnym — jest odrzucany: to samo odczytanie, które obowiązuje dwa powyższe wiersze z samą ścieżką, a kształt zapisu niczego tu nie zmienia. O tym, skąd odczytywana jest zawartość, decyduje wyłącznie url:; pozostałe pola wybierają, co zostałoby pobrane, i nadal trafiają do szablonów encji Recipe jako .source.*.
URI OCI (oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — docelowy projekt dystrybucji katalogów. Obecny trójpoziomowy mechanizm rozwiązywania (pliki wskazywane przez encję Release ścieżką, katalogi przestrzeni roboczej, zdalny rejestr OCI) opisano w architecture/13-catalog-and-registry.md; mechanizm rozwiązywania na poziomie encji obsługuje URI OCI przez tę kaskadę, ale forma OCI pola source: w poszczególnych encjach Recipe nie jest obecnie podłączona w providerach.
Inne schematy URL (https://, git+https:// itp.)(przykładowo)planned — opisane jako zamierzenie projektowe w planie rozwoju wymiennych źródeł w architekturze; obecnie brak obsługi w providerach.

Jak zakotwiczana jest ścieżka source:. Zakotwiczanie dotyczy ścieżek w systemie plików i niczego innego, niezależnie od tego, który z dwóch kształtów niesie ścieżkę. Ścieżka względna jest zakotwiczona w katalogu zawierającym recipe.yaml, który ją deklaruje, a ścieżka opuszczająca ten katalog — łącznie ze ścieżką bezwzględną — jest odrzucana, jak wyjaśnia sekcja Ścieżki do zawartości pozostają w katalogu encji Recipe. Odwołanie ze schematem transportowym — oci://, https://, http://, git://, ssh://, git+ssh:// lub dowolne odwołanie kończące się na .git — wskazuje coś do pobrania, a nie ścieżkę, więc jest przekazywane dokładnie w zapisanej postaci i nigdy nie jest łączone z katalogiem.

W kształcie strukturalnym ścieżką jest pole url: i odczytuje się je tak samo: względny url: jest zakotwiczony w katalogu zawierającym recipe.yaml, taki, który opuszcza ten katalog, jest odrzucany, a taki ze schematem transportowym jest pobierany. Każde inne pole strukturalnego source: jest przekazywane bez zmian, łącznie z polami zdefiniowanymi przez providera.

source: zapisane jako szablon jest zakotwiczane względem wartości, którą szablon wytwarza, a nie względem tekstu samego szablonu. Szablon niczego nie wskazuje, dopóki nie zostanie obliczony, więc powyższe odczytanie stosuje się do jego wyniku: wynik będący ścieżką względną jest zakotwiczony w katalogu zawierającym recipe.yaml, wynik opuszczający ten katalog — łącznie ze ścieżką bezwzględną — zatrzymuje build, a wynik ze schematem transportowym jest przekazywany i pobierany. Szablon może więc wytworzyć dowolny z kształtów z powyższego zestawienia, a każdy jest traktowany dokładnie tak, jak ta sama wartość zapisana dosłownie; różnica dotyczy tylko momentu, w którym można ocenić ścieżkę — dla szablonu jest to chwila obliczenia go przez build, a nie odczytu encji Recipe.

Szablon, który nic nie wytwarza — pusty wynik — pozostawia encję Recipe bez źródła, czyli w trybie bez źródła. Różni się to od samodzielnego zapisania source: "", które nie wskazuje żadnego trybu i jest odrzucane; zob. odpowiedni wiersz zestawienia powyżej.

Ten wykaz jest kanonicznym źródłem informacji o tym, co autorzy mogą umieścić w source:; jego etykiety to te, które definiuje 10-status.md.

Ścieżki treści pozostają w katalogu własnym encji Recipe

Treść encji Recipe znajduje się w jej własnym katalogu, ponieważ stamtąd pobierany jest każdy plik, który zawiera jej publikacja. Każda ścieżka, którą Recipe zapisuje dla przenoszonej treści — jej source:, czy to jako sama ścieżka, czy jako url: postaci strukturalnej, oraz każdy plik importowany przez $import: we wpisach valuesMapping:, workload: i artifacts: — jest odczytywana względem katalogu zawierającego recipe.yaml i musi w nim pozostać. Te same ścieżki wyznaczają też zawartość publikacji: wskazane przez nie pliki są przenoszone razem z encją Recipe, a nic innego z jej katalogu nie jest (zob. aggrega push). Ścieżka wychodząca poza katalog wskazuje plik, który nie zostałby przeniesiony z encją Recipe, więc nie będzie go u odbiorcy, a zapisany dla niego pin poświadczałby bajty, których odbiorca nie może uzyskać.

Poza katalog wychodzą dwa rodzaje ścieżek i oba są odrzucane:

  • ścieżka wychodząca ponad katalog, np. ../shared/charts/app;
  • ścieżka bezwzględna, np. /opt/charts/app, która wskazuje miejsce na maszynie, na której ją zapisano.

Ścieżka, która wychodzi w górę i wraca do środka, jest zwykłą ścieżką wewnątrz katalogu: ./charts/../values.tmpl wskazuje plik values.tmpl obok encji Recipe. Oceniane jest to, gdzie ścieżka trafia, mierzone od katalogu encji Recipe bez wychodzenia z niego — dlatego wyjście na zewnątrz, które w drodze powrotnej ponownie podaje nazwę katalogu, np. ../1.0.0/values.tmpl zapisane w katalogu o nazwie 1.0.0, również jest odrzucane. Nazwa samego katalogu nie jest przenoszona: opublikowana encja Recipe jest odczytywana z katalogu nazwanego przez pamięć podręczną odbiorcy, gdzie ta nazwa niczego nie wskazuje.

Gdzie następuje odrzucenie. Każde polecenie, które odczytuje encję Recipe, odrzuca taką ścieżkę w chwili jej odczytu, zanim cokolwiek zostanie pobrane, wyrenderowane lub opublikowane: aggrega validate, zarówno dla katalogu, jak i dla pliku samej encji Recipe, aggrega pull, aggrega build, aggrega pin i aggrega push. source: zapisane jako szablon niczego nie wskazuje, dopóki budowanie go nie obliczy, więc szablon zwracający ścieżkę spoza katalogu jest odrzucany przez budowanie, w chwili gdy wartość powstaje. Zatrzymanie to A path names content outside the entity’s own directory (Ścieżka wskazuje treść spoza własnego katalogu encji) i podaje zapisaną ścieżkę.

Co zrobić zamiast tego. Należy umieścić plik w katalogu encji Recipe lub w katalogu pod nim i podać go względem encji Recipe: ./charts/app, ./extras/netpol.yaml. Chart używany przez kilka encji Recipes kopiuje się do katalogu każdej z nich, ponieważ każda encja Recipe jest publikowana osobno; treść mapowania, workloadu lub artefaktu współdzielona przez kilka encji Recipes należy do encji MappingLibrary, WorkloadLibrary lub ArtifactLibrary, do której każda encja Recipe odwołuje się przez tożsamość.

Dlaczego encja Release jest inna. Release wskazuje inne encje — swoją encję Aggregate, swoją encję Manifest, encję Release, którą rozszerza — i nigdy nie jest publikowana, więc nic, co odczytuje, nigdzie nie jest przenoszone. Te odwołania oraz plik importowany przez jej parameters: są odczytywane tak, jak zostały zapisane, dzięki czemu jedna encja Aggregate może być współdzielona przez warianty encji Release w podkatalogach. Zob. entities/release.md.

To samo ograniczenie dotyczy encji FeatureRecipe oraz każdego schematu importowanego przez encję Component lub Feature.

Pole workload: — syntetyzowany rodzaj wejścia

Recipe.spec.workload: deklaruje treść Workload, którą kompilator syntetyzuje w natywne zasoby providera. Jest to jeden z trzech rodzajów wejścia, które Recipe może zadeklarować, obok source: (renderowanie ze źródła) i artifacts: (pomocnicze manifesty). U każdego providera musi być obecny co najmniej jeden z trzech; usługa, której kompilacja nie udostępnia, deklaruje workload: z form: reference.

Pole przyjmuje trzy tryby tworzenia — wbudowany skalar blokowy, plikowy $import: lub biblioteczny $import:. Kompilator rozpoznaje tryb po kształcie zawartości pola; adnotacja $mode: nie jest potrzebna.

Tryb 1: wbudowany (skalar łańcucha szablonu Go). Wartością jest skalar blokowy YAML, którego wynik parsuje się jako aggrega.ai/v1beta1 Workload:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Pola encji Workload znajdują się w korzeniu dokumentu — nie ma opakowania spec: — a containers: oraz ports: każdego kontenera są mapami kluczowanymi nazwami, a nie sekwencjami, z zachowaniem kolejności nadanej przez autora. Provider tłumaczy ten kształt na własną natywną formę, więc wpis mapy kontenerów pojawia się w wyrenderowanym wyniku helm jako element containers[] nazwany jego kluczem; tworzonym kształtem jest mapa, a nie wyrenderowana lista.

Tryb 2: plikowy $import:. Wartością jest mapa z jednym kluczem $import: wskazującym lokalny plik szablonu Go:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

Rozwiązywanie ścieżek działa tak samo jak w valuesMapping:: ścieżka względna jest zakotwiczona w katalogu zawierającym recipe.yaml, który ją deklaruje, a nie w katalogu, z którego wywołano build, i musi pozostać wewnątrz tego katalogu. Zaimportowana treść jest szablonem Go wykonywanym w kontekście renderowania encji Recipe, dokładnie tak jak treść wbudowana.

Tryb 3: biblioteczny $import:. Wartością jest mapa z jednym kluczem $import: zawierającym odwołanie do tożsamości w postaci samej nazwy, wskazujące wpis w encji WorkloadLibrary:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

To fragment #/workloads/ wybiera wpis Workload i to on odróżnia to odwołanie od formy #/mappings/, której używa valuesMapping: — ta adresuje wpis MappingLibrary i nie wskazuje treści Workload. Odwołanie nie zawiera hosta rejestru, rozwiązana wersja pochodzi z lockfile danej encji Release, opcjonalny próg wersji minimalnej :<version> można zadeklarować jako <Library>:<version>#/workloads/<Entry>, a wpis, którego treść sama jest $import: w korzeniu pola, rozwiązuje się rekurencyjnie. Zaimportowana treść jest szablonem Go wykonywanym w kontekście renderowania korzystającej z niej encji Recipe, więc .values, .infra i .features trafiają do niej dokładnie tak jak do treści wbudowanej. Encję biblioteki i pełną gramatykę odwołań opisuje entities/workloadlibrary.

Docelowy provider musi obsługiwać syntezę (katalog biblioteki standardowej zgodnie z konwencją deklaruje workloadSchema dla takich providerów); wskazanie providera, który nie potrafi syntetyzować, jest odrzucane podczas renderowania węzła z diagnostyką możliwości providera — opartą na możliwościach providera, a nie na obecności workloadSchema. Pełną gramatykę encji Workload, pola przekazywane bez zmian w kształcie K8s oraz zachowanie tłumaczenia dla poszczególnych providerów opisuje entities/workload.md. Szerszy model trzech rodzajów wejścia oraz asembler, który scala syntezę z wyjściem renderowanym ze źródła i artefaktami, opisuje architecture/16-recipe-input-composition.md.

Dostarczanie własnych wartości komponentu do własnego obrazu programisty. Zgodnie z konwencją katalogu biblioteki standardowej od encji Recipe uruchamiającej obraz budowany przez programistę oczekuje się dostarczenia wszystkiego, co rozwiązały bloki inject: programisty, z .context.inject; może ona też dostarczać własne wartości komponentu pod nazwami wybranymi przez siebie. Gdy encja Component deklaruje spec.inject, nazwy wybiera własny blok programisty, a .context.self_inject wskazuje encji Recipe tę jedną własną wartość, którą odczytuje szablon każdego wpisu — values.<key> dla wpisu odczytującego dokładnie jedną własną wartość i nic poza nią. Konwencja katalogu biblioteki standardowej polega na traktowaniu nazw, jakie encja Recipe nadaje tym wartościom, jako domyślnych, a nie jako kontraktu, który kod programisty musi odczytywać, i na dostarczaniu wartości pod jej domyślną nazwą tylko wtedy, gdy żaden wpis się na nią nie mapuje; katalog firmowy może wybrać inaczej. Kontrakt kontekstu szablonów podaje dokładne reguły tej mapy oraz pełny przykład szablonu.

Pole artifacts: — manifesty pomocnicze

Recipe.spec.artifacts: to mapa nazw wpisów → definicji treści artefaktów, której wpisy emitują dodatkowe pliki manifestów obok głównego wyniku encji Recipe, renderowanego ze źródła lub syntetyzowanego. Jest to jeden z trzech rodzajów wejścia (ze źródła / syntetyzowany / artefakty) — Recipe może zadeklarować samo artifacts: albo razem z workload: i/lub source:.

Wartość każdego wpisu ma jeden z trzech trybów, rozróżnianych po kształcie treści, analogicznie do workload: — treść inline, plikowy $import: lub bibliotekowy $import:. Kompilator rozróżnia tryb po kształcie treści wartości; adnotacja $mode: nie jest potrzebna. We wszystkich trzech trybach klucz mapy nazywa to, co wpis emituje: w dwóch trybach jednoplikowych jest to nazwa pliku wyjściowego, a w trybie pakietu — katalog, w którym zagnieżdżane są pliki pakietu. Ponieważ klucz nazywa wynik, jest ograniczony do tego, czym może być pojedyncza nazwa pliku: na początku litera lub cyfra, dalej litery, cyfry, kropki, myślniki i podkreślenia. Kropki zachowują rozszerzenie, które klucz zgodnie z konwencją zawiera — main.tf, template.yaml, serviceaccount.yaml — natomiast alfabet nie dopuszcza /, przez który klucz nazywałby ścieżkę zamiast pliku, ani początkowej ., więc klucz nigdy nie może być segmentem katalogu nadrzędnego. Klucz spoza tego alfabetu nie przechodzi walidacji koperty przy wczytywaniu przestrzeni roboczej, w aggrega validate oraz w diagnostyce edytora.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

Tryb 1: inline (skalar tekstowy z szablonem Go). Wartość jest skalarem blokowym, a klucz mapy jest nazwą pliku wyjściowego, użytą dosłownie — pierwszy wpis powyżej emituje extra-configmap.yaml.

Tryb 2: plikowy $import:. Wartość jest mapą z jednym kluczem $import: wskazującym lokalny plik szablonu Go, a klucz mapy jest nazwą pliku wyjściowego, dokładnie jak w trybie 1. Importowany plik dostarcza treść, a nie nazwę. Drugi wpis powyżej ma klucz network-policy.yaml i emituje network-policy.yaml, mimo że importowany plik nazywa się network-policy.tmpl. Autor, który chce uzyskać określoną nazwę pliku wyjściowego, zapisuje ją więc jako klucz, a dwa wpisy importujące różne pliki o tej samej nazwie — ./extras/shared.yaml i ./overrides/shared.yaml — to dwa odrębne wyniki. Rozwiązywanie ścieżek działa tak samo jak w valuesMapping: i workload:: ścieżka względna jest zakotwiczona w katalogu zawierającym recipe.yaml, który ją deklaruje, a nie w katalogu, z którego wywołano budowanie, i musi pozostać wewnątrz tego katalogu.

Tryb 3: bibliotekowy $import:. Wartość jest mapą z jednym kluczem $import: zawierającym referencję tożsamości w postaci samej nazwy do pakietu ArtifactLibrary, <Library>#/artifacts/<name>. Pakiet to zbiór plików importowanych jako jedna całość, więc jeden wpis rozwija się w jeden wynik na każdy plik pakietu, każdy zagnieżdżony pod kluczem mapy jako <key>/<filename> — klucz nazywa miejsce użycia i jest katalogiem, do którego trafiają te pliki, a nie nazwą któregokolwiek z nich. Trzeci wpis powyżej ma klucz operator-support; jeśli PlatformArtifacts#/artifacts/OperatorSupport deklaruje crd.yaml i rbac.yaml, ten jeden wpis emituje operator-support/crd.yaml i operator-support/rbac.yaml. Referencja nie zawiera hosta rejestru — forma oci://… z hostem jest odrzucana — rozwiązana wersja pochodzi z pliku blokady danej encji Release, a opcjonalny próg minimalnej wersji :<version> można zadeklarować jako <Library>:<version>#/artifacts/<name>. Encję biblioteki i pełną gramatykę referencji opisuje entities/artifactlibrary.

Plikowy $import: jest przypinany obok encji Recipe. aggrega pin zapisuje skrót bajtów każdego importowanego pliku w entity.lock w katalogu encji Recipe, pod kluczem mapy wpisu, a aggrega build ponownie oblicza skrót pliku i zatrzymuje się z [CATALOG_ERROR E0026], gdy przestaje on się zgadzać — albo wcześniej z E0130, gdy plik blokady encji Release, zapisany przed edycją, rejestruje Recipe według tego, co zawiera — więc plik edytowany po przypięciu nigdy nie zostanie wyrenderowany bez weryfikacji. Jeśli zmiana była zamierzona, należy uruchomić aggrega pin dla encji Recipe, aby zapisać nowy skrót; w przeciwnym razie należy przywrócić plik. Wpis inline jest częścią pliku encji Recipe, a wpis bibliotekowy jest przypięty przez wersję biblioteki zapisaną w pliku blokady, więc żaden z nich nie ma własnego przypięcia. Plik opisuje aggrega pull.

Szablon każdego wpisu artefaktu jest wartościowany w tym samym kontekście szablonu co valuesMapping:, niezależnie od trybu, który dostarczył jego treść. Dwa wyniki o tej samej nazwie pliku zatrzymują budowanie podczas renderowania węzła. Dwa wpisy jednej mapy artifacts: nie mogą nazwać jednego wyniku: klucz mapy jest unikatowy w obrębie dokumentu i określa jedną nazwę pliku, więc wynikiem wpisu jednoplikowego jest jego klucz, a pliki wpisu pakietowego leżą w katalogu nazwanym jego kluczem — pierwszym segmentem każdej ścieżki emitowanej przez wpis jest klucz, który ją wytworzył, więc różne klucze pozostają różnymi nazwami wyników bez względu na nazwy importowanych plików. Zatrzymanie dotyczy jednej nazwy pliku dostarczonej przez dwa różne rodzaje wejścia — szablon chartu i wpis artefaktu, które oba tworzą servicemonitor.yaml — i jest zgłaszane dla tej encji Recipe z diagnostyką wskazującą każde źródło.

Zastosowania. artifacts: to miejsce na zasoby pomocnicze, których główny chart lub moduł nie tworzy: NetworkPolicy towarzyszący obciążeniu, HPA sparowany z Deployment, pomocniczy ConfigMap zależny od instance_id. Przekrojowe zasoby pomocnicze, które dotyczą wielu komponentów (np. sidecar kopii zapasowych dołączany do każdego magazynu danych), należą do generowania zasobów w encji FeatureRecipe, a nie do artifacts: w poszczególnych encjach Recipe — powierzchnię rozszerzeń FeatureRecipe opisuje entities/featurerecipe.md.

Blok boundary: — pliki dla wspólnego wyniku granicy

Większość encji Recipes nigdy tego nie potrzebuje. Wszystko inne, co zapisuje encja Recipe, należy do jej własnego komponentu: provider umieszcza to w miejscu tego komponentu w wyniku granicy. Niektóre pliki należą jednak do granicy jako całości — jest to plik, który cel odczytuje jednokrotnie dla wszystkiego, co granica wdraża. Typowym przypadkiem jest konfiguracja providera w Terraform: dokumentacja Terraform zaleca, by bloki provider nie znajdowały się w module wywoływanym przez inną konfigurację, a modułu zawierającego własny taki blok nie można wywołać z depends_on, count ani for_each. spec.boundary.artifacts to miejsce, w którym encja Recipe zapisuje taki plik.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

Blok to artifacts: w drugim zakresie. Jego jedynym elementem jest artifacts, który ma dokładnie taki sam kształt jak własne pole artifacts: encji Recipe: te same trzy tryby — treść inline, plikowy $import: oraz bibliotekowy $import:, którego pliki są zagnieżdżane pod kluczem wpisu jako <key>/<filename> — ta sama zasada odwzorowania klucza na nazwę pliku i ten sam alfabet klucza, a także ten sam kontekst szablonu, więc wpis odczytuje .values, .infra, .locals i pozostałe dokładnie tak, jak robi to wpis pola artifacts:. Blok wymaga co najmniej jednego wpisu, a każdy inny element pod boundary: jest odrzucany przy wczytywaniu encji Recipe. Encja FeatureRecipe nie ma takiego bloku.

Gdzie zapisywany jest plik. Jednokrotnie, w katalogu zawierającym złożony wynik granicy, obok plików zapisywanych tam przez własne składanie providera — w przypadku terraform obok konfiguracji głównej aggrega.modules.tf, a nie wewnątrz modułu komponentu. Provider nie otrzymuje żadnego z tych plików: kompilator sam je ewaluuje i zapisuje, nie umieszcza w nich żadnej informacji o tym, z którego komponentu pochodzą, ponieważ plik należy do każdego komponentu, który go zadeklarował. Wpis, którego szablon renderuje się do pustej treści, nie zapisuje żadnego pliku.

Jak spotyka się wielu współtwórców. Każdy wpis jest ewaluowany dla każdego komponentu, który encja Recipe renderuje w granicy, a pliki zadeklarowane przez wszystkich współtwórców granicy są scalane według nazwy. Jedna nazwa ewaluowana do tych samych bajtów — przez dwa komponenty powiązane z jedną encją Recipe lub przez dwie encje Recipes konfigurujące jednego providera identycznie — to jeden plik. Jedna nazwa ewaluowana do różnych bajtów zatrzymuje budowanie z podaniem pliku i wszystkich współtwórców, ponieważ żaden pojedynczy plik nie jest tym, co wszyscy zapisali; tak samo dzieje się w przypadku nazwy zapisywanej przez własne składanie providera, takiej jak aggrega.modules.tf. Oba przypadki to kolizja złożonego wyniku. Dwie encje Recipes konfigurujące jednego providera pod dwiema różnymi nazwami plików nie są scalane — zapisywany jest każdy plik — a duplikat konfiguracji zgłasza wówczas cel, dlatego encje Recipes, które mają współdzielić konfigurację providera, współdzielą nazwę jej pliku, zgodnie z konwencją nazwaną od konfigurowanego providera.

Które providery to akceptują. To, czy plik umieszczony obok złożonego wyniku granicy ma jakiekolwiek znaczenie, jest właściwością celu providera, dlatego stanowi część własnej deklaracji providera. Encja Recipe deklarująca ten blok, której provider go nie akceptuje, jest odrzucana, zanim cokolwiek zostanie wyrenderowane, niezależnie od tego, do czego renderują się jej wpisy; zob. The provider does not support boundary artifacts (Provider nie obsługuje artefaktów granicy). Tabela możliwości przedstawia deklarację każdego providera.

Providerboundary.artifacts:
terraformAkceptowane. Każdy plik jest zapisywany obok konfiguracji głównej granicy, którą Terraform odczytuje razem ze wszystkimi innymi plikami konfiguracyjnymi w tym katalogu.
helm, compose, helm-chart, cloudformationOdrzucane, zanim cokolwiek zostanie wyrenderowane.

Plikowy $import: jest tu przypinany tak samo jak plik importowany przez wpis pola artifacts:. Blokada encji zapisuje jego skrót na tej samej liście artifactDigests, pod boundary/<key> zamiast pod samym kluczem, dzięki czemu wpisy obu bloków zapisane pod tym samym kluczem są przypinane osobno. Krok przypinania go zapisuje, operacja pull, która nie przypina, zatrzymuje się, gdy przypięcia brakuje lub przestało ono pasować, a kompilacja odrzuca plik zmieniony od czasu przypięcia dokładnie tak, jak odrzuca plik pola artifacts:.

Pole outputLabels: — etykiety deklarowane przez autora na renderowanym wyniku

Recipe.spec.outputLabels: to mapa klucz etykiety → wartość, którą provider nanosi na każdy obiekt powstający w renderowanym wyniku encji Recipe. To właściwe miejsce dla cechy realizacji — właściwości tego, jak konkretna encja Recipe realizuje komponent, w odróżnieniu od tego, czym komponent jest. Weźmy pamięć masową, z której korzysta realizacja, zapisaną poniżej przykładowym kluczem example.io/storage-backing: encja Recipe dla Helm montująca PersistentVolumeClaim i encja Recipe dla Compose montująca nazwany wolumen realizują ten sam komponent za pomocą różnych mechanizmów, więc niosą różne outputLabels, a narzędzia w dalszej części łańcucha (alokacja kosztów, polityki, inwentaryzacja) mogą je rozróżnić na emitowanych zasobach. Klucz jest przykładowy — example.io/ to przykładowa przestrzeń nazw, a katalog dobiera klucze odczytywane przez jego własne narzędzia.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

Etykiety wyjściowe podróżują tą samą ścieżką co stałe etykiety pochodzenia kompilacji: są scalane ze zbiorem etykiet nanoszonym przez każdą emitującą powierzchnię, więc trafiają wszędzie tam, gdzie trafia informacja o pochodzeniu. Różni je własność — klucze pochodzenia należą do kompilatora, a outputLabels należą do autora encji Recipe.

Własnej etykiety tożsamości komponentu nie wpisuje się tutaj — to konwencja katalogu, a nie reguła egzekwowana przez kompilator. Klucze określające, czym komponent jest, a nie jak realizuje go jedna encja Recipe — jego kategoria poznawcza, typ operacyjny, etykiety możliwości dla poszczególnych ról, kto obsługuje zasób bazowy, klasa licencyjna tego, co opakowuje — deklaruje się w metadata.labels encji Component; osie opisuje entities/component, sekcja „The Semantic Label Taxonomy”. Encja Recipe nanosi jeden z nich na swój renderowany wynik, wymieniając klucz w opisanym niżej outputComponentLabels:, a nie wpisując tutaj klucza i wartości. Powodem jest to, że wpis dosłowny to druga kopia wartości, którą komponent już posiada, a druga kopia może być niezgodna z pierwszą: autor encji Recipe może wpisać jedną postawę na węźle, którego encja Component deklaruje inną, przekazując odbiorcy w dalszej części łańcucha coś, czego graf nie mówi. Wpis promowany kopiuje przez referencję, więc nie ma drugiej kopii, która mogłaby się rozjechać. Rdzeń przyjmuje to, co zostanie wpisane, z zastrzeżeniem opisanej niżej reguły zarezerwowanych przestrzeni nazw; konwencję podtrzymują autorzy katalogów.

Zarezerwowane przestrzenie nazw. Przestrzenie nazw aggrega.ai/ i app.kubernetes.io/ są zarezerwowane dla natywnych informacji o pochodzeniu platformy. Encja Recipe deklarująca klucz outputLabels z którymkolwiek z tych prefiksów jest odrzucana przy wczytywaniu z czytelnym błędem katalogu wskazującym błędny klucz. Każdy inny klucz jest akceptowany. Poza tym rdzeń nie kontroluje klucza ani wartości — za klucz lub wartość nieprawidłowe dla powierzchni etykiet docelowego silnika odpowiada autor, a odrzuca je środowisko uruchomieniowe w dalszej części łańcucha; poza regułą zarezerwowanych przestrzeni nazw kompilator nie ingeruje.

Prezentacja w poszczególnych providerach. Każdy provider przenosi etykiety na własną powierzchnię wyjściową:

  • helm, synteza workloadu — zarówno w metadata.labels obiektu, jak i w metadata.labels szablonu poda, zgodnie z miejscem, w którym synteza umieszcza informacje o pochodzeniu.
  • helm, renderowanie źródła i artefakty — w metadata.labels obiektu.
  • compose — w mapie labels: każdej usługi.
  • terraform — jako tagi poszczególnych zasobów w strukturalnie adresowalnych treściach artefaktów .tf.json, w miarę możliwości: blok zasobu, który już deklaruje mapę tags (AWS/azurerm) lub labels (Google), otrzymuje tam etykiety wyjściowe, klucz zadeklarowany przez autora nigdy nie jest nadpisywany, a zasób bez takiego atrybutu pozostaje nietknięty (atrybut nigdy nie jest wymyślany). Treści w natywnym HCL (main.tf, *.tf) i dołączone moduły są emitowane dosłownie i nie zawierają wstrzykniętych tagów. Informacje o pochodzeniu dla Terraform nadal są przenoszone w towarzyszącym pliku komentarzy, oddzielnie od ścieżki tagów.

Etykiety wyjściowe są wyłącznie etykietami; nie ma osobnej powierzchni adnotacji wyjściowych. outputLabels deklaruje autor encji Recipe (warstwa realizacji tworzona przez zespół operacyjny), a nie encja Aggregate — opisuje ono realizację, nigdy tożsamość w abstrakcyjnym grafie programisty.

Pole outputComponentLabels: — promowanie własnych etykiet komponentu

Recipe.spec.outputComponentLabels: to lista kluczy etykiet, a nie par klucz-wartość. Dla każdego wskazanego klucza provider nanosi ten klucz na wyrenderowany wynik z wartością, jaką klucz ma w renderowanej instancji komponentu. Tam, gdzie outputLabels podaje wartość, outputComponentLabels wskazuje, skąd wartość ma zostać odczytana.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

Jeśli encja Component ma w metadata.labels deklarację component.aggrega.ai/hosting: managed, każdy obiekt, który ta encja Recipe renderuje dla tego komponentu, ma etykietę component.aggrega.ai/hosting: managed. Po powiązaniu tej samej encji Recipe z komponentem deklarującym self-hosted obiekty tego komponentu mają zamiast tego wartość self-hosted — jedna encja Recipe, jeden nazwany klucz, wartość zależna od komponentu.

Promowanie odbywa się przez referencję i właśnie o to chodzi. Wartość jest odczytywana z komponentu przy każdym renderowaniu wyniku, więc nie może rozjechać się z tożsamością, z której pochodzi: nie ma drugiej kopii, którą trzeba aktualizować, gdy zmienia się etykieta komponentu. Dosłowny wpis outputLabels powtarzający etykietę komponentu jest taką drugą kopią, a obie przestają się zgadzać w chwili, gdy którakolwiek się zmieni. Dlatego outputLabels należy stosować, gdy wartość jest cechą sposobu, w jaki ta encja Recipe realizuje komponent, a outputComponentLabels — gdy wartość już istnieje w komponencie, a wyrenderowany wynik również powinien ją zawierać.

Promowany klucz trafia dokładnie na tę samą powierzchnię co klucz dosłowny — opisane wyżej udostępnianie w poszczególnych providerach stosuje się bez zmian i żaden provider nie odróżnia klucza promowanego od klucza zapisanego na miejscu.

Zarezerwowane przestrzenie nazw. Przestrzenie nazw aggrega.ai/ i app.kubernetes.io/ są zarezerwowane dla natywnej dla platformy informacji o pochodzeniu, a promowany klucz z którymkolwiek z tych prefiksów jest odrzucany przy wczytywaniu z błędem katalogu wskazującym klucz i pole, w którym występuje. Sprawdzany jest sam prefiks: klucz taki jak component.aggrega.ai/hosting należy do własnej przestrzeni nazw, a nie do zarezerwowanego korzenia, i może być promowany.

Klucz należy do jednego bloku albo do drugiego. Zadeklarowanie tego samego klucza zarówno w outputLabels, jak i w outputComponentLabels jest odrzucane przy wczytywaniu, więc każdy naniesiony klucz ma jedno źródło — albo dosłowną wartość zapisaną w encji Recipe, albo własną etykietę komponentu, nigdy oba.

Promowany klucz, którego komponent nie deklaruje, niczego nie nanosi. Budowanie jest kontynuowane i emituje ostrzeżenie wskazujące węzeł, encję Recipe i brakujący klucz. Jest to zamierzone: encja Recipe powiązana z komponentami o różnych zestawach etykiet nadal się renderuje, a rozbieżność jest zgłaszana zamiast przerywać budowanie.

Komponenty o jednej postawie — konwencja, nie reguła. Promowanie przenosi dowolną wartość deklarowaną przez komponent, a kompilator tej wartości nie interpretuje. Komponent, którego etykieta tożsamości zawiera symbol zastępczy oznaczający „różnie”, promuje więc ten symbol na każdy obiekt dla niego renderowany. Gdy komponent rzeczywiście ma więcej niż jedną postawę, konwencja katalogu biblioteki standardowej przewiduje, że każda encja Recipe podaje postawę własnej realizacji przez klucz outputLabels należący do tej encji Recipe, a nie przez klucz tożsamości komponentu, który ta sama konwencja kieruje zamiast tego przez outputComponentLabels: — albo nie nanosi niczego. Te dwa klucze odpowiadają na różne pytania i żaden nie zastępuje drugiego: klucz tożsamości mówi, czym jest komponent we wszystkich realizacjach, a klucz należący do encji Recipe mówi, co robi ta jedna realizacja. Jest to konwencja katalogu przestrzegana przez jego autorów, a nie ograniczenie egzekwowane przez kompilator.

Blok locals:

Recipe.spec.locals: to prywatny stan operacyjny (Private Ops State) — mapa nazwanych łańcuchów szablonów Go, których wyrenderowany wynik udostępnia mapę .locals.* późniejszym szablonom encji Recipe. Jest to przestrzeń robocza do jednokrotnego obliczenia fizycznych realiów (docelowych kontenerów, ścieżek JSON, wyprowadzonych nazw hostów) i ponownego ich użycia w provides:, source:, valuesMapping:, workload:, artifacts:, assertions: oraz w ładunkach pipeline[].with bez ponownego obliczania. Wyrenderowany wynik każdego wpisu jest zapisywany bez początkowych i końcowych białych znaków.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals: nigdy nie jest udostępniany wywołującym — komponenty podrzędne korzystające z tej encji Recipe przez uses: widzą tylko provides:. Własne szablony provides:, source:, valuesMapping:, workload:, artifacts:, assertions: i pipeline[].with encji Recipe widzą rozwiązaną mapę .locals.*. Wartości poszczególnych kluczy mogą być zwykłymi łańcuchami lub szablonami Go; kompilator rozwiązuje cały blok w preambule locals, przed provides: danego węzła, dzięki czemu każdy późniejszy szablon widzi stabilne, rozwiązane wartości.

Każdy wpis jest ewaluowany względem samodzielnego, lokalnego dla węzła kontekstu: .context.instance_id, .values, .infra oraz już rozwiązanych wpisów tego samego bloku. Wpis lokalny nie może odczytać .provides — ten filar nie jest dostępny na tej powierzchni, a wpis, który po niego sięga, powoduje zatrzymanie. Nie może też odczytać .context.rendered_name, czyli nazwy, jaką provider taki jak helm nadaje zasobom renderowanym dla węzła, dlatego wpis lokalny nazywający jeden z tych zasobów zawiera tylko część występującą po tej nazwie, tak jak secret_target_db_password powyżej, a szablon zapisujący pełną nazwę łączy obie części.

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:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

Łańcuchowanie działa tylko w dół. Gdy jeden wpis odczytuje inny, kolejność wpisów decyduje o powodzeniu kompilacji: przeniesienie db_identifier poniżej secret_target powoduje zatrzymanie kompilacji. Kompilator nigdy nie sortuje ani nie zmienia kolejności bloku, aby rozwiązać odwołanie, więc zapisana kolejność jest kontraktem — zmiana kolejności w bloku locals: jest zmianą zachowania, a nie kosmetyczną.

Dwa rodzaje zatrzymania rozróżniają dwa błędy, jakie może popełnić autor, ponieważ naprawia się je inaczej:

  • Odwołanie do wpisu, który blok definiuje później, powoduje zatrzymanie wskazujące błąd 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, powoduje zatrzymanie wskazujące ten klucz; należy poprawić pisownię.

Sprawdzenie obejmuje aliasy bloku. Klucz osiągnięty przez kropkę ponownie wiązaną w treści with .locals lub przez zmienną powiązaną z .locals jest sprawdzany na dokładnie tych samych zasadach co zapis bezpośredni: {{ with .locals }}{{ .nope }}{{ end }} i {{ $l := .locals }}{{ $l.nope }} powodują zatrzymanie wskazujące .locals.nope, tak samo jak {{ .locals.nope }}, i tak samo {{ (.locals).nope }} oraz {{ ($.locals).nope }}, ponieważ nawiasy zwracają sam blok i nic więcej. Jeden zapis omija sprawdzenie: klucz osiągnięty przez wywołanie, którego wyniku tekst szablonu nie może nazwać — {{ index .locals "nope" }} lub {{ (default dict .locals).nope }} — ponieważ to, co zwraca takie wywołanie, rozstrzyga się podczas wykonania szablonu, a nie na podstawie zapisu. Brakujący klucz odczytany jako pole z wyniku takiego wywołania nie powoduje zatrzymania i renderuje dosłowny tekst <no value> zamiast pustej wartości. Brakujący klucz osiągnięty przez index powoduje zatrzymanie wskazujące klucz, ponieważ index zatrzymuje się na każdej powierzchni szablonów, gdy odczytywana mapa nie zawiera żądanego klucza — jest to inny komunikat niż w tym sprawdzeniu, opisany w errors/fatal-halts.md pod nagłówkiem „A template indexes a map with a key the map does not hold (Szablon indeksuje mapę kluczem, którego mapa nie zawiera)”. Dlatego index pozostaje sposobem na osiągnięcie klucza, którego nazwa jest sama obliczana, np. {{ index .locals (printf "secret_target_%s" .values.slot) }}, a obliczona nazwa, której blok nie deklaruje, jest nadal zgłaszana z podaniem klucza.

provides: odczytuje .locals i otrzymuje rozwiązane wartości, ponieważ zmienne lokalne węzła są rozwiązywane przed jego provides. Szablon provides: odwołujący się do klucza, którego blok locals nie deklaruje, zatrzymuje kompilację. Oznacza to, że wartość potrzebna zarówno wpisowi provides:, jak i artefaktowi jest definiowana raz, w locals:, i odczytywana z obu miejsc.

Odpowiednik w publicznym API opisano poniżej w sekcji Blok provides: (publiczne API). Powierzchnia FeatureRecipe podlega tym samym regułom — zob. entities/featurerecipe.md, „Blok locals:”.

Blok provides:

Recipe.spec.provides: to Publiczne API dla programistów — mapa nazwa → ciąg szablonu Go, deklarująca wartości, które ten Recipe dostarcza do potoków .context.inject i .context.uses wywołujących znajdujących się niżej w łańcuchu. Kompilator ewaluuje szablony provides: na etapie ewaluacji provides (samodzielnie, w dowolnej kolejności); klucze inject wywołujących są rozwiązywane względem tych wartości na etapie hydratacji inject.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

Szablon każdego wpisu jest ewaluowany względem samodzielnej powierzchni ewaluacji provides — .context.instance_id, .context.rendered_name (gdy provider węzła ją zgłasza), .values, .infra, rozwiązanej mapy .locals węzła oraz tekstu statycznego. Przestrzeń nazw, w której umieszczono węzeł, nie jest na niej dostępna, więc publikowany host jej nie zawiera: konsument w innej przestrzeni nazw kwalifikuje go po swojej stronie. .locals jest na niej dostępna, ponieważ zmienne lokalne węzła są rozwiązywane w preambule tego samego etapu, przed jego provides; szablon provides odwołujący się do klucza, którego blok locals nie deklaruje, zatrzymuje kompilację. Oddzielenie ewaluacji provides od hydratacji inject ma kluczowe znaczenie: provides: encji Recipe nie może odwoływać się do stanu żadnego wywołującego, ponieważ wywołujący nie są jeszcze rozwiązani, gdy przebiega ewaluacja provides — provides: jest samodzielny zgodnie z niezmiennikiem architektury. Wywołujący odczytują następnie te wartości przez .context.uses.<alias>.provides.<provided-name> we własnych szablonach — udostępniane nazwy są zagnieżdżone pod provides na krawędzi, obok pozostałych pól krawędzi. Wywołujący, który deklaruje na krawędzi listę dozwolonych inject:, sięga po te same wartości zamiast tego przez swój potok .context.inject.

Klucze provides: są częścią powierzchni kontraktu encji Recipe. Zmiana nazwy lub usunięcie klucza jest zmianą niekompatybilną dla każdego wywołującego, który polega na starej nazwie; wersja interfejsu implements: powinna odzwierciedlać ewolucję kontraktu. Semantykę kaskadowego rozwiązywania, kontrakt potoku inject oraz przykłady obejmujące routing między przestrzeniami nazw i między regionami opisują architecture/06-data-taxonomy-and-composition.md §3 i templates/expansion-matrix.md.

Odczytywanie wartości publikowanych przez dołączenie

Encja Recipe odczytuje encje Features dołączone do swojego komponentu pod .features.<instance-name>, a encje Features z poświadczeniami pod .features.<slot>. Oba mają ten sam kształt dołączenia — .type, .values, .infra, .provides — więc dołączenie odczytuje się tak samo niezależnie od tego, która mapa je przechowuje; różni je to, co dołączenie wytwarza.

.provides to opublikowane wyjście dołączenia, rozwiązywane z encji FeatureRecipe z nim powiązanej. Jest to odpowiednik opisanego wyżej bloku provides:, widziany od strony konsumenta: tak jak encja Recipe publikuje wartości dla swoich wywołujących, tak dołączenie publikuje je dla swojego komponentu-hosta.

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

Odczytanie opublikowanej wartości zamiast ponownego wyliczania jej z tych samych wejść values/infra stanowi różnicę między jednym określeniem nazwy a dwoma, które mogą się rozejść. Pełny opis kształtu, pole po polu, wraz z regułami dostępności, znajduje się w templates/template-context-contract.md.

Dołączenie zapisane na jednym z połączeń komponentu — poświadczenie, które komponent przedstawia jednemu celowi — odczytuje się w tym samym kształcie pod tym połączeniem, pod .context.uses.<alias>.features.<slot>, i nigdy nie znajduje się ono wśród .features. Encja Recipe łącząca się z kilkoma celami odczytuje poświadczenie każdego celu pod aliasem tego celu, a pętla po .features, która wybiera dołączenia według typu, napotyka tylko własne dołączenia komponentu:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

Kształt oraz kolejność, w jakiej szablon iteruje po połączeniach, opisano w sekcji Dołączenia połączenia.

Pole pipeline:

Recipe.spec.pipeline: to sekwencyjna tablica kroków potoku Wasm, które działają po renderowaniu na zbiorze wyrenderowanych dokumentów, a każdy zwraca poprawki RFC 6902 i efekty uboczne. Każdy wpis deklaruje id (identyfikator kroku: litery, cyfry i podkreślenia), plugin (encję Plugin, którą uruchamia krok, zawężoną jej typem pluginu — pipeline-step/<name>, opcjonalnie z wersją; goła referencja .wasm lub artefaktu jest odrzucana), function (eksport wtyczki do wywołania), opcjonalne ciało szablonu Go with: dostarczające ładunek wtyczki oraz opcjonalny szablon Go when:, który określa, czy krok zostanie wykonany — wynik fałszywy pomija krok jako przejście bez zmian, pozostawiając zbiór dokumentów niezmieniony. Bramka when:, jej niezależność od optional: oraz reguła prawdziwości są w pełni opisane w entities/featurerecipe.md, w sekcji „Kroki warunkowe — when:”:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

Kompilator wykonuje kroki pipeline: bazowej encji Recipe w zadeklarowanej kolejności, w ten sam sposób, w jaki wykonuje pipeline: encji FeatureRecipe: dla każdego kroku uruchamia wskazany plugin Wasm na wyrenderowanym wyniku, stosuje zwrócone operacje JSON Patch do adresowanych dokumentów i emituje efekty uboczne kroku. Pole pipeline: encji FeatureRecipe ma ten sam kształt schematu i to samo wykonanie — zob. entities/featurerecipe.md, sekcja „Authoring Contract”, oraz Status języka, gdzie opisano stan wykonania każdej powierzchni.

Mechanika pola odzwierciedla semantykę encji FeatureRecipe: sekwencyjne wartościowanie w zadeklarowanej kolejności, operacje JSON Patch stosowane do wyrenderowanych dokumentów, efekty uboczne emitowane obok nich oraz błędy zgłaszane z informacją o pochodzeniu wskazującą na krok, który je spowodował. Krok, którego warunek when: daje wynik fałszywy, jest pomijany jako przejście bez zmian, a zbiór dokumentów pozostaje niezmieniony dla następnego kroku.

Blok assertions:

Recipe.spec.assertions: to opcjonalna mapa nazwanych reguł wyrażających niezmienniki implementacyjne encji Recipe — reguły międzypolowe, które obowiązują przy konkretnym chartcie lub module, z którego Recipe pobiera źródło. Każdy klucz jest identyfikatorem reguły, który pojawia się w komunikacie o niepowodzeniu; każda wartość jest treścią szablonu Go. W odróżnieniu od asercji encji Component (które wyrażają niezmienniki na poziomie kontraktu niezależnie od tego, która Recipe zostanie powiązana), asercje encji Recipe są właściwościami konkretnej wybranej implementacji.

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

Powyższa reguła jest specyficzna dla chartu Bitnami 20.x; nie ma zastosowania, jeśli powiązana zostanie inna Recipe dla MariaDB. Reguły z kontraktu na poziomie encji Component nadal obowiązują równolegle i są ewaluowane we wcześniejszej fazie potoku.

Asercje encji Recipe są ewaluowane po powiązaniu encji Recipe i przed renderowaniem, gdy locals i provides każdego węzła są już rozwiązane. Kontekst szablonu zawiera .provides, .locals i .recipe.source encji Recipe, a oprócz nich pola instancji encji (.values, .infra, .uses, .features). .uses i .features mają tam węższe kształty właściwe dla asercji, a nie kształty szablonu encji Recipe: wpis połączenia zawiera jego cel i alias, labels celu, własne values połączenia oraz zapisane na nim w features dołączenia, ale nic z tego, co cel publikuje; z kolei wpis dołączenia, zarówno własnego dla komponentu, jak i należącego do połączenia, zawiera jego type, resolved_version i values, ale ani jego infra, ani provides — FeatureRecipe dołączenia nie ma jeszcze rozwiązanych provides w chwili uruchomienia asercji. Odwołanie do .features.<name>.provides zatrzymuje więc kompilację, a odczyt uwzględniający obecność zwraca dla niego wartość zastępczą. Pełną gramatykę tworzenia, podział odpowiedzialności między regułami na poziomie kontraktu i na poziomie implementacji oraz przykłady opisano w templates/assertions-block.md.

Pole omits: — pomijanie wyrenderowanych dokumentów źródła

Większość encji Recipe nigdy tego nie potrzebuje. Pole służy źródłu przyjmowanemu takim, jakie jest — najczęściej chartowi pobranemu z rejestru — które renderuje dokument, którego encja Release nie może dostarczyć: na przykład Secret generowany przez chart od nowa przy każdym renderowaniu, przez co dwie kompilacje się różnią, a po zastosowaniu nadpisuje on Secret dostarczony przez operatora. Pobranego chartu się nie edytuje i żadna reguła ignorowania do niego nie sięga, dlatego omits: jest sposobem, w jaki encja Recipe pomija taki dokument w kompilacji. Pobrany plik compose to ten sam przypadek: może zawierać usługę, wolumen lub konfigurację, których encja Release nie może mieć, a nakładka valuesMapping: może je zmienić, ale nigdy usunąć. Podobnie pobrany szablon CloudFormation, który może deklarować zasób, którego encja Release nie może utworzyć: valuesMapping: może wypełnić zadeklarowane w nim parametry, ale nigdy nie usunie żadnego z jego zasobów.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

Co obejmuje. Tylko to, co renderuje source:. Pole workload: i wpisy artifacts: nigdy nie są filtrowane: pisze się je w encji Recipe, więc niechcianego tam dokumentu po prostu się nie pisze. Klucz wymaga source:; dokument łamiący tę regułę jest odrzucany przy wczytywaniu, z podaniem reguły.

Wpis. Każdy wpis określa, co pominąć, za pomocą trzech pól, a czwarte decyduje, czy wpis ma zastosowanie. To, co określają pierwsze trzy, wyrażone jest we własnym słownictwie providera dotyczącym tego, co renderuje jego źródło, opisanym dla każdego providera w tabeli poniżej:

  • kind — rodzaj tego, co renderuje źródło: dla chartu rodzaj wyrenderowanego dokumentu — Secret, ConfigMap, Deployment; dla pliku compose service, volume lub config; dla szablonu CloudFormation Type zasobu — AWS::S3::Bucket. Nie ma związku z polem kind: strukturalnego source:, które określa sposób pobierania źródła.
  • name — jego nazwa: metadata.name dokumentu; klucz jednostki compose w services:, volumes: lub configs:; logiczny identyfikator zasobu CloudFormation, czyli jego klucz w Resources.
  • namespace (opcjonalne) — przestrzeń nazw, w której znajduje się dokument, dla providera, którego wynik ma przestrzenie nazw. Bez tego pola wpis wskazuje rodzaj i nazwę w dowolnej przestrzeni nazw; namespace, który renderuje się do pustej wartości, traktowany jest jak nieobecny.
  • when (opcjonalne) — czy wpis ma zastosowanie w tej kompilacji. Jest obliczane jako pierwsze i odczytywane według tej samej reguły co when: kroku potoku: wynik fałszywy odrzuca wpis, więc jego pozostałe pola nie są obliczane, a on sam nie jest ani przekazywany providerowi, ani sprawdzany, natomiast nieobecne lub puste when: go zachowuje.

kind i name są wymagane, a wpis zawierający jakiekolwiek inne pole jest odrzucany przy wczytywaniu encji Recipe.

Każda wartość jest szablonem, obliczanym w tym samym kontekście co valuesMapping:. Kontekst ten zawiera .context.rendered_name, nazwę, którą provider nadaje zasobom węzła i od której chart zazwyczaj je nazywa, więc wpis może wskazać dokument dokładnie tak, jak nazwie go chart. Szablon, którego nie da się wyrenderować, zatrzymuje kompilację tak samo jak błędny szablon valuesMapping:.

Każdy obowiązujący wpis musi coś pominąć. Provider raportuje, ile jednostek pominął każdy wpis, a wpis, który niczego nie pominął, zatrzymuje kompilację z podaniem wpisu; zob. An omits entry left out nothing the source rendered (Wpis omits nie pominął niczego, co wyrenderowało źródło). Zwykłą przyczyną jest aktualizacja źródła, która zmienia nazwę dokumentu lub go usuwa, a zatrzymanie sprawia, że dokument o zmienionej nazwie nie trafi niezauważony do wyniku. Aby pomijać dokument tylko czasami, należy wyrazić to za pomocą when:, zamiast polegać na nieobecności dokumentu.

Źródło nadal renderuje się w całości. Filtrowany jest tylko jego wynik: każdy szablon chartu nadal się wykonuje, więc błędny szablon nadal przerywa kompilację, a pominięty dokument jest renderowany, a następnie odrzucany. Po odrzuceniu nie trafia do niczego, co kompilacja robi później — do żadnego emitowanego pliku, żadnego porównania nazw z nazwami innych komponentów, żadnego faktu o renderowaniu odczytywanego przez Feature ani niczego przekazywanego krokowi potoku.

Encja Release sięga do klucza przez infra i parameters. Klucz należy do encji Recipe, więc encja Release nie może go zapisać. Może jednak decydować, co robi wpis: szablony wpisu odczytują infra wypełniane przez encję Release, a dostarczane przez nią parameters trafiają do .values encji Recipe wszędzie tam, gdzie kieruje je encja Aggregate. Encja Release może więc włączać lub wyłączać wpis za pomocą when:, jak robi to drugi wpis powyżej, albo decydować, co on wskazuje.

Za to, co się pomija, odpowiada autor. Nic w kompilacji nie wie, do czego służy dokument. Pominięcie dokumentu, od którego reszta chartu zależy w czasie działania — Secretu montowanego przez Deployment, ServiceAccount, z którym działa pod — daje wynik, który kompiluje się bez błędów, a następnie zawodzi przy zastosowaniu, chyba że ten dokument zapewnia coś innego zastosowanego obok. W przypadku pliku compose i szablonu CloudFormation kompilacja to sprawdza, ponieważ każdy z nich określa własne odwołania: to, co pozostało, a nadal wskazuje pominiętą jednostkę — usługa wskazująca pominiętą usługę, zasób lub wyjście wskazujące pominięty zasób — zatrzymuje kompilację, jak opisuje tabela poniżej.

Którzy providerzy to obsługują. Pominięcie dokumentu może wykonać tylko provider, ponieważ tylko provider wie, co renderuje jego źródło, więc to, czy provider obsługuje ten klucz, jest częścią jego własnej deklaracji. Encja Recipe deklarująca omits:, której provider go nie obsługuje, jest odrzucana, zanim cokolwiek zostanie wyrenderowane, niezależnie od tego, do czego renderują się when: jej wpisów; zob. The provider does not support omits (Provider nie obsługuje omits).

Provideromits:
helmObsługiwane. Wpis wskazuje dokument renderowany przez chart — z szablonu lub z jego katalogu crds/ — za pomocą własnego kind dokumentu, metadata.name oraz, jeśli wpis ją podaje, przestrzeni nazw, w której dokument się znajduje. Zob. helm → Tryb ze źródłem.
composeObsługiwane. Wpis wskazuje service, volume lub config pliku compose ze źródła za pomocą jego klucza w services:, volumes: lub configs:, dopasowywanego po scaleniu valuesMapping: z plikiem, i nie podaje przestrzeni nazw: wpis wskazujący inny rodzaj lub przestrzeń nazw zatrzymuje kompilację podczas renderowania komponentu. Plik, w którym to, co pozostało, nadal wskazuje pominiętą jednostkę — przez depends_on, links, volumes_from, tryb sieci lub przestrzeni nazw service:, extends, kontekst budowania albo wpis volumes: lub configs: — zatrzymuje kompilację z podaniem każdego odwołania. Zob. compose → Tryb ze źródłem.
cloudformationObsługiwane. Wpis wskazuje zasób szablonu ze źródła za pomocą jego Type i logicznego identyfikatora, w każdym szablonie źródła katalogowego, i nie podaje przestrzeni nazw: wpis, który ją zawiera, zatrzymuje kompilację podczas renderowania komponentu. Szablon, w którym to, co pozostało, nadal wskazuje pominięty zasób — przez Ref, Fn::GetAtt, DependsOn lub zmienną Fn::Sub — zatrzymuje kompilację z podaniem każdego odwołania. Zob. cloudformation → Pomijanie zasobów szablonu ze źródła.
helm-chart, terraformOdrzucane: provider przekazuje swoje źródło do wyrenderowania w chwili wdrożenia, więc w czasie kompilacji nie istnieje żaden dokument do pominięcia. W przypadku lokalnego chartu lub modułu zamiast tego jego plik pomija wiersz w .aggregaignore obok encji Recipe.

Ten sam klucz zapisuje się w encji FeatureRecipe; zob. entities/featurerecipe.md.

Przykład — pominięty Secret generowany przez pobrany chart, zatrzymanie z powodu braku determinizmu, na które ten sam chart trafia bez wpisu, oraz zatrzymanie przy wpisie, który niczego nie dopasowuje, każde z rzeczywistej kompilacji — zob. ai-gateway-own-webhook-certificate.