Kompozycja wejść encji Recipe — trzy rodzaje wejść, Workload, artefakty
Encja Recipe generuje pliki manifestów dla swojego docelowego dostawcy. Ten rozdział opisuje, w jaki sposób encje Recipes składają swoje wyjście z trzech ortogonalnych rodzajów wejść — pobieranych ze źródła, syntetyzowanych i artefaktów — jaką strukturę ma każdy rodzaj wejścia oraz który dostawca generuje które wyjście. Koncepcyjna rola encji Recipe (tworzonego przez zespół Ops szablonu tłumaczenia, który odwzorowuje intencję programisty na jednego fizycznego dostawcę) jest opisana w 04-entity-taxonomy.md; powierzchnia tworzenia encji Recipe na poziomie słów kluczowych jest opisana w ../language-reference/entities/recipe.md.
Uzasadnienie
Natywne narzędzie renderujące każdego dostawcy — Helm, Docker Compose — już wie, jak renderować manifesty natywne dla dostawcy. Zadaniem encji Recipe jest zadeklarowanie, CO te manifesty mają zawierać: jakie obrazy kontenerów, jakie porty, jakie zmienne środowiskowe, jakie wolumeny, jakie usługi, jakie limity zasobów.
Encja Recipe musi wyrażać więcej, niż może pomieścić stały zestaw kluczy (np. image, environment, ports, replicas) odwzorowany na Deployment i Service, w tym:
resources(żądania/limity CPU i pamięci)- Sond liveness, readiness ani startup
volumeMounts/volumesnodeSelector/affinity/tolerationsserviceAccount/securityContext- Podów wielokontenerowych, sidecarów
- Zasobów ConfigMap / Secret / PVC / CRD
- Usług typu innego niż ClusterIP (LoadBalancer, NodePort, Headless)
Warstwa abstrakcji musi opisywać pełny kształt obciążenia, a nie stały zestaw kluczy. Opisane poniżej trzy rodzaje wejść są właśnie tą abstrakcją: encja Recipe składa swój wynik addytywnie z ładowanego z zewnątrz chartu lub modułu (source:), abstrakcyjnej specyfikacji Workload, którą dostawca syntetyzuje w manifesty natywne dla dostawcy (workload:), oraz szablonowych manifestów natywnych dla dostawcy, które encja Recipe emituje bezpośrednio (artifacts:).
Trzy rodzaje wejść
Kompozycja przez dodawanie
Istnieją trzy sposoby wytworzenia natywnych plików manifestów dostawcy z encji Recipe; łączą się one przez dodawanie, a nie przez wzajemne wykluczanie:
source:— artefakt ładowany z zewnątrz (chart Helm, plik compose), który dostawca renderuje natywnie, przy czymvaluesMapping:dostarcza wartości nakładki.workload:— abstrakcyjna specyfikacja Workload (rodzaj należący do platformy), którą dostawca syntetyzuje do natywnych manifestów dostawcy. Pole przyjmuje wbudowany skalar blokowy YAML lub$import:wskazujący pojedynczy plik lokalny albo wpis biblioteki; wybór sposobu obsługi zależy od kształtu treści.artifacts:— mapa natywnych manifestów dostawcy, wbudowanych lub ładowanych przez$import:, przetwarzanych szablonami Go względem pełnego kontekstu filarów. Każdy wpis można zapisać jako wbudowany (wartością wpisu jest skalar blokowy) lub przez$import:wskazujący pojedynczy plik albo treść biblioteki.
Wszystkie trzy wytwarzają pliki, które kompilator zapisuje w katalogu wyjściowym granicy. Wszystkie trzy mogą współistnieć w jednej encji Recipe, z zastrzeżeniem poniższych reguł walidacji. Semantyka scalania działa wyłącznie na najwyższym poziomie: każdy rodzaj wejścia wytwarza kompletne pliki; pliki są emitowane obok siebie; kolizja nazw plików wyjściowych jest błędem krytycznym.
Opisowe nazwy trybów
Trzy „tryby” to słownictwo opisowe na potrzeby dokumentacji i diagnostyki. Autorzy encji Recipe nie deklarują trybu; piszą potrzebne im słowa kluczowe. Encję Recipe charakteryzuje jej dominujące wejście:
| Dominujące słowa kluczowe | Opisowa nazwa trybu |
|---|---|
source: + valuesMapping: (bez workload:, bez artefaktów) | sourced |
workload: (bez source:, bez artefaktów) | synthesized |
artifacts: (bez source:, bez workload:) | artifacts-only (nieformalnie: „inline”) |
| Dowolna kombinacja dwóch lub więcej | opisywana wprost (np. „sourced z artefaktami”, „synthesized z artefaktami”) |
Nie istnieje słowo kluczowe mode: ani typ wyliczeniowy. Tryb jest właściwością wynikającą z tego, które wejścia są obecne.
Kształt encji Recipe w skrócie
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: ... version: 1.0.0spec: capability: helm | compose | helm-chart | ... implements: core/...:1.0.0
locals: { ... } provides: { ... }
# ─── Sourced input (optional, paired) ─── source: ... valuesMapping: | # Go template → YAML/JSON overlay values # OR: valuesMapping: $import: ./mappings/api-server.tmpl # local file path # OR: valuesMapping: $import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ─── workload: | # Go template → YAML → parsed Workload # OR (single-source $import for whole-content load from a file or library): workload: $import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ─── artifacts: "filename.yaml": | # Inline Go template → manifest YAML "other.yaml": $import: ./artifacts/other.yaml # per-entry $import: for file or library contentKażde z powyższych pól jest akceptowane przez schemat Recipe, a kompilator obsługuje wszystkie trzy rodzaje wejść — renderowanie źródłowe, syntezę Workload i emisję artefaktów. Różni się obsługa w poszczególnych providerach — który provider renderuje który rodzaj wejścia — co opisuje tabela Provider Capability Matrix na końcu tego rozdziału.
Reguły walidacji podczas ładowania
Schemat Recipe i walidacja przy ładowaniu egzekwują następujące reguły kompozycji:
valuesMapping:wymagasource:. Bezsource:, na który można nałożyć wartości, nie ma czego zasilić zmapowanymi wartościami. Encja Recipe zvaluesMapping:i bezsource:powoduje błąd podczas ładowania. (source:bezvaluesMapping:jest dozwolone — chart lub moduł renderuje się z własnymi wartościami domyślnymi).workload:przyjmuje jedno źródło — wbudowane lub$import:, nie oba naraz. Encja Recipe określa Workload jako wbudowany skalar blokowy albo$import:wskazujący pojedynczy plik. Forma$import:ma jedno źródło zgodnie z ujednoliconym słownictwem importu plików; scalanie wielu źródeł nie jest obsługiwane wworkload:. Nieprawidłowy wybór formy powoduje błąd podczas ładowania.workload:wymaga providera zdolnego do syntezy. Obsługa syntezy jest właściwością samego providera, a nie żadnego zadeklarowanego pola. Encja Recipe zworkload:powiązana z providerem, który nie potrafi syntetyzować, jest odrzucana podczas renderowania węzła — przez bramkę możliwości providera (zob. Provider Capability Matrix) — z czytelną diagnostyką. Katalog biblioteki standardowej zgodnie z konwencją deklarujeworkloadSchemaw providerach zdolnych do syntezy jako udokumentowany kontrakt translacji, ale bramka opiera się na możliwościach zgłaszanych przez samego providera, a nie na obecności tego pola.- Musi być obecny co najmniej jeden rodzaj wejścia. Encja Recipe bez żadnego z
source:+valuesMapping:,workload:aniartifacts:nie wytwarza wyniku i powoduje błąd podczas ładowania. - Wpisy artefaktów wbudowane i
$import:mogą współistnieć. Encja Recipe może zadeklarować część wpisówartifacts:jako wbudowane, a inne przez dyrektywy$import:w poszczególnych wpisach. Klucz każdego wpisu nadaje nazwę jego własnemu wyjściu, więc wpisy obu form nigdy ze sobą nie kolidują (zob. Co nadaje nazwę każdemu plikowi wyjściowemu). - Kolizje nazw plików między rodzajami wejść są błędami podczas renderowania. Jeśli dwa rodzaje wejść encji Recipe — wynik renderowania ze źródła, wynik syntezy workloadu lub wynik emisji artefaktów — wytworzą plik o tej samej nazwie, kompilator zgłasza błąd krytyczny wskazujący wszystkie źródła. To sprawdzenie odbywa się po translacji Workload, dlatego następuje podczas renderowania, a nie podczas ładowania.
Rodzaj Workload
Własność i lokalizacja
Workload to rodzaj należący do platformy, dostępny pod apiVersion: aggrega.ai/v1beta1. Jego deklaracja w JSON Schema 2020-12 jest osadzana w pliku binarnym kompilatora podczas budowania; autorzy katalogów nie edytują schematu Workload ani nie tworzą samodzielnych plików YAML Workload jako encji katalogu. Gramatyka Workload jest używana wewnątrz pola workload: encji Recipe lub FeatureRecipe (inline albo przez $import: do pojedynczego pliku lub wpisu WorkloadLibrary) i nigdzie indziej.
Workload to rodzaj platformy i pojęcie kompilatora, a nie osobna encja w taksonomii encji. Encja Recipe jest encją tworzoną przez autora; Workload to kształt, jaki przyjmuje syntetyzowane wejście encji Recipe.
Jeden Workload na Recipe
Encja Recipe deklaruje co najwyżej jedno workload:. Workload reprezentuje pojedynczą jednostkę obliczeniową powiązaną z encją Component, którą ta encja Recipe implementuje. Encja FeatureRecipe podobnie deklaruje co najwyżej jedno własne workload: — jednostkę obliczeniową należącą do encji Feature, syntetyzowaną przez ten sam rodzaj Workload — zob. FeatureRecipe. Przypadki wymagające dodatkowych obciążeń pobocznych wyraża się przez:
artifacts:— dodatkowe manifesty obok obciążenia, w tej samej encji Recipe (inline lub przez$import:dla każdego wpisu).- Encje Features z generowaniem zasobów — przekrojowe obciążenia poboczne (np. sidecar kopii zapasowych dołączany do baz danych) deklarowane jako osobne encje katalogu, w których encja FeatureRecipe syntetyzuje własne
workload:(lub renderuje przezsource:/artifacts:). Generowanie zasobów w encji FeatureRecipe opisano w 14-extensibility.md.
Zachowuje to model jednej jednostki obliczeniowej na autora: encja Recipe syntetyzuje obciążenie encji Component; encja FeatureRecipe syntetyzuje własne.
Pełna powierzchnia
Zestaw pól Workload jest duży i stale rośnie. Zamiast powtarzać go tutaj, gdzie kopia zostawałaby w tyle za kontraktem, a nic by tego nie zgłaszało, ten rozdział wskazuje dwie powierzchnie, które opisują go w całości:
- Generowana dokumentacja schematu Workload — każde pole, jego typ, wartość domyślna i ograniczenia, generowane z opublikowanego JSON Schema i porównywane z nim przy każdym budowaniu, dzięki czemu nie może opisywać kształtu, którego kompilator nie akceptuje.
- Strona o tworzeniu Workload — wskazówki na poziomie pól: co oznacza każde pole, na co renderuje je każdy dostawca i których kombinacji budowanie odmawia.
Deklaracja JSON Schema 2020-12 encji Workload jest wiążąca i jest dostarczana osadzona w pliku binarnym kompilatora. Providery helm i compose syntetyzują workload: encji Recipe, inline lub ładowane przez $import:; obsługę dla poszczególnych providerów opisuje sekcja Provider Capability Matrix.
Integracja sekretów z featuresSchema
Blok containers.<name>.attachments w Workload odwołuje się do slotów zadeklarowanych przez featuresSchema encji Component; nie deklaruje nowych slotów. Powierzchnię tworzenia featuresSchema opisuje ../language-reference/entities/component.md.
Kontrakt walidacji:
- Każda wartość
attachments.<KEY>.frommusi odpowiadać nazwie slotu zadeklarowanej wfeaturesSchemaencji Component — lub, dla wpisu wskazującego połączenie przezconnection: <alias>, slotowi, który gniazdo tego połączenia deklaruje wusesSchema.<socket>.featuresSchema. Taki wpis jest przepisywany na nazwę, jaką załącznik połączenia przyjmuje w komponencie (<alias>.<slot>), zanim zostanie zastosowana którakolwiek z tych reguł, więc każda reguła poniżej odczytuje go tak samo jak wpis wskazujący własny slot encji Component. - Mechanizm dostarczania
as:(envlubfile) musi znajdować się na liście dozwolonych w tablicyinject:danego slotu. - Sloty oznaczone
inject: [](czarna skrzynka) wfeaturesSchemaencji Component nie mogą występować w blokachattachments:w Workload — te sloty są dostarczane przez wewnętrzne mechanizmy encji Recipe (np. przezexistingSecretw Helm), a nie przez ekspozycję w Workload.
Przykład:
# In the Componentspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipeworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected — root_password is blackboxSondy kondycji: intencja, nie mechanizm
Sondy Kubernetes i healthchecki Docker Compose mają różne kształty. Jeden abstrakcyjny kształt intencji przekłada się czysto na oba:
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Providers (providery) tłumaczą każdą intencję na swój natywny kształt:
| Intencja | Helm (K8s) | Compose |
|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" |
exec: [cmd] | exec.command: [cmd] | CMD [cmd] |
Rozwiązywanie portu dla http: bez jawnie podanego portu wybiera pierwszą alfabetycznie nazwę portu, którą kontener deklaruje w containers.<name>.ports, na obu celach. Kontener niedeklarujący żadnego nazwanego portu nie może mieć sondy HTTP, a budowanie zostaje przerwane ze wskazaniem sondy.
Compose degraduje sondy HTTP/TCP do poleceń powłoki healthcheck, a usługa compose ma tylko jeden healthcheck: gdy zadeklarowano więcej niż jedną sondę, tłumaczona jest jedna, a ostrzeżenie wymienia te pominięte.
Typy woluminów
Pięć typów woluminów; bez typów złożonych:
| Typ | Semantyka | K8s (helm) | Compose |
|---|---|---|---|
ephemeral | Tmpfs / emptyDir; ginie wraz z podem | emptyDir: { sizeLimit } | montowanie tmpfs: bez rozmiaru (ostrzeżenie zgłasza podany sizeLimit) |
configmap | Pliki konfiguracyjne tylko do odczytu | Odwołanie do woluminu ConfigMap | odwołanie configs: na poziomie usługi do konfiguracji najwyższego poziomu deklarowanej przez artifacts: encji Recipe |
secret | Pliki sekretów tylko do odczytu | Odwołanie do woluminu Secret | plik sekretu tylko do odczytu montowany przez bind mount |
persistent | Pojedynczy PVC; przetrwa restarty poda | Zasób PVC + volume.persistentVolumeClaim | nazwany wolumin |
persistentTemplate | PVC na replikę; towarzyszy form: stateful | StatefulSet.volumeClaimTemplates | nazwany wolumin (zdegradowany; emitowane ostrzeżenie) |
Compose nie potrafi wyrazić szablonów na replikę. Gdy persistentTemplate jest przekładany na compose, degraduje się do pojedynczego nazwanego woluminu współdzielonego przez wszystkie repliki, a ostrzeżenie zgłasza tę degradację. Wolumin persistentTemplate wymaga form: stateful; zadeklarowanie go w jakiejkolwiek innej formie przerywa budowanie.
Ekspozycje wielu usług
Każda usługa jest niezależną ekspozycją. Typowy wzorzec: usługa HTTP na porcie 8080 (ClusterIP wewnętrzny) + usługa metryk na porcie 9090 (ClusterIP) + punkt końcowy administracyjny na porcie 9901 (LoadBalancer):
services: http: type: ClusterIP ports: web: 8080 metrics: type: ClusterIP ports: prom: 9090 admin: type: LoadBalancer ports: admin: 9901Każda z nich staje się osobnym obiektem Kubernetes Service przy renderowaniu przez dostawcę helm, który zamiast tego przerywa działanie na wpisie Loopback. W compose usługi NodePort i LoadBalancer publikują swoje porty na każdym interfejsie hosta usługi compose, usługi Loopback tylko na adresie loopback hosta, a usługi ClusterIP i Headless nie publikują niczego.
Nazwy usług w wyjściu K8s są poprzedzane instance_id komponentu w celu zapewnienia unikalności. Nazwy portów muszą odpowiadać nazwom portów kontenera zadeklarowanym w containers.<name>.ports.
Kontrakt translacji po stronie encji Provider: workloadSchema
Encja Plugin renderująca dostawcę (pluginType: provider) deklaruje spec.provider.workloadSchema — deklarację w JSON Schema 2020-12 dokumentującą, jak pola Workload przekładają się na natywne wyjście tego dostawcy. Jest to samodokumentujący się kontrakt translacji. Powierzchnię tworzenia encji Plugin, w tym blok spec.provider, opisuje ../language-reference/entities/plugin.md.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: helm-renderer version: 1.0.0 pluginType: providerspec: abiVersion: v1beta1 provider: workloadSchema: | # how Workload translates to K8s manifests // Each Workload produces: 1 controller object chosen by workload.form // (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job) // + 1..N Services (one per workload.services entry) // + 1..N PVCs (one per workload.volumes.*.persistent entry) // + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source) // ...Pole workloadSchema przekazuje intencję translacji autorom katalogów i narzędziom IDE. Jest to udokumentowany kontrakt translacji, deklarowany zgodnie z konwencją w dostawcach, którzy syntetyzują — jednak obsługę syntezy określa sam dostawca, a nie obecność tego pola. Encja Recipe z workload: skierowana do dostawcy, który nie potrafi syntetyzować, jest odrzucana podczas renderowania węzła — przez bramkę możliwości dostawcy — z czytelnym błędem, niezależnie od tego, czy dostawca deklaruje workloadSchema.
Schemat encji Plugin deklaruje spec.provider.workloadSchema — jego treść jest kompilowana do JSON Schema 2020-12 podczas ładowania encji Plugin — a obsługa workload: po stronie encji Recipe jest dostępna. Obsługa syntezy jest egzekwowana w czasie renderowania przez bramkę możliwości dostawcy, opartą na możliwościach zgłaszanych przez powiązanego dostawcę; workloadSchema to udokumentowany kontrakt, który katalog biblioteki standardowej utrzymuje w zgodzie z tymi możliwościami, a nie samo wejście bramki. aggrega validate uruchomione dla całego katalogu dodatkowo wcześnie, przed budowaniem, wykrywa encję Recipe z workload: powiązaną z dostawcą, który nie syntetyzuje, o ile katalog zawiera encję Plugin tego dostawcy.
Zasoby pomocnicze znajdują się poza encją Workload
Specyfikacja encji Workload nie ma pola additionalResources, pola extras ani deklaracji inline ConfigMap/Secret/CRD. Workload modeluje wyłącznie kształt obciążenia: kontenery, woluminy, usługi, repliki, harmonogramowanie, kontekst bezpieczeństwa, konto usługi — wszystko, co opisuje, jak działa pojedyncza jednostka obliczeniowa.
Zasoby pomocnicze mają dwa uprawnione miejsca poza encją Workload:
- Features + FeatureRecipes — mechanizm dla zagadnień przekrojowych. ServiceMonitor dołączany do „dowolnego serwera z udostępnionymi metrykami” to
core/prometheus-exporterjako Feature. Zasób routingu, który publikuje serwer pod nazwą hosta, również jest encją Feature, a forma routingu decyduje, którą:core/public-ingresstam, gdzie cel uzgadnia Ingress,core/http-routetam, gdzie działa Gateway API — każda realizowana przez encję FeatureRecipe, którą Manifest wybiera dla danej encji Release. NetworkPolicy egzekwowana na wszystkich produkcyjnych obciążeniach to Feature, którą produkcyjna encja Release dołącza w obrębie całej granicy. Features składają się ortogonalnie i mogą być ponownie używane w wielu encjach Recipes. Opis generowania zasobów przez FeatureRecipe znajduje się w 14-extensibility.md. artifacts:na poziomie encji Recipe — dla zasobów, które należą do implementacji tej konkretnej encji Recipe i dla których nie warto tworzyć encji Feature. Jednorazowa rejestracja CRD, której Recipe potrzebuje. Specyficzny dla encji Recipe PodDisruptionBudget, który obowiązuje tylko wtedy, gdy ta Recipe jest używana. ConfigMap, do której odwołuje się Workload tej encji Recipe. Każdy wpis jest inline lub ładowany przez$import:; zob. poniższą sekcję o mechanizmie artefaktów.
Granica między encją Feature a artefaktem to konwencja społeczna. Jeśli zasób pomocniczy jest przekrojowy (dotyczy wielu encji Recipes lub jest dołączany warunkowo za pomocą selektorów), jest to Feature. Jeśli jest nieodłączny od tej jednej encji Recipe (Recipe nie może wykonać swojego zadania bez wyemitowania tego zasobu), jest to artefakt. Autorzy wybierają na podstawie semantyki ponownego użycia i dołączania; kompilator nie kontroluje tego wyboru.
Features i artefakty encji Recipe razem obejmują zasoby pomocnicze, których potrzebuje encja Recipe.
Mechanizm artefaktów
Artefakty wbudowane i ładowane z plików
Rodzaj wejścia artifacts emituje szablonowane, natywne dla dostawcy pliki manifestów bezpośrednio do wyjścia granicy, obok wyjścia renderowanego ze źródła lub syntetyzowanego z obciążenia. Autorzy deklarują go na dwa sposoby:
spec: artifacts: "servicemonitor.yaml": | apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: {{ .context.instance_id }}-monitor spec: endpoints: - port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml": $import: ./artifacts/networkpolicy.yaml "crd-registration.yaml": $import: ./artifacts/crd-registration.yamlŚcieżki $import: są względne wobec katalogu encji Recipe i muszą pozostać w jego obrębie, ponieważ każdy plik, który zawiera publikacja encji Recipe, pochodzi z tego katalogu — każdy plik wskazany przez import trafia do niej razem z nim — a plik spoza katalogu by nie trafił. Typowa konwencja umieszcza je w podkatalogu ./artifacts/, choć kompilator tego nie wymusza. Klucz mapy nadaje nazwę każdemu emitowanemu plikowi — następna sekcja opisuje, co to oznacza w każdej z trzech form.
Każdy wpis (wbudowany lub ładowany przez $import:) jest przetwarzany szablonem Go względem pełnego kontekstu szablonu przed wyemitowaniem do katalogu wyjściowego.
Co nadaje nazwę każdemu plikowi wyjściowemu
Kluczami mapy są nazwy wpisów, a klucz w każdej formie zapisu określa, co wpis emituje. Dla wpisu wbudowanego klucz jest nazwą pliku wyjściowego, użytą w zapisanej postaci:
artifacts: "configmap-config.yaml": | ... "pdb.yaml": | ...Tworzy configmap-config.yaml i pdb.yaml. Klucz ustala nazwę pliku; to, gdzie plik trafi, zależy od celu, co opisuje poniższa sekcja o emisji dla poszczególnych dostawców.
Dla wpisu z plikowym $import: klucz również jest nazwą pliku wyjściowego. Importowany plik dostarcza treść, ale nie nazwę, więc autor, który chce uzyskać określoną nazwę pliku wyjściowego, zapisuje ją jako klucz:
artifacts: "monitor.yaml": $import: ./artifacts/monitor.yaml "netpol.yaml": $import: ./artifacts/subdir/some-other-name.yamlTworzy .../monitor.yaml i .../netpol.yaml. Plik importowany przez drugi wpis nazywa się some-other-name.yaml i ta nazwa nie trafia do wyjścia — trafia klucz. Dwa wpisy importujące różne pliki o tej samej nazwie, ./extras/shared.yaml i ./overrides/shared.yaml, dają zatem dwa odrębne wyjścia, każde nazwane własnym kluczem.
Wpis z bibliotecznym $import:, który pobiera pakiet plików jako jedną całość, rozwija się w jedno wyjście na każdy plik pakietu, zagnieżdżone pod kluczem jako <key>/<filename>. Jeden klucz odpowiada wielu plikom, więc sam nie może ich nazwać: jest katalogiem, do którego trafiają pliki pakietu, a nie nazwą któregokolwiek z nich.
Ponieważ każda forma nazywa swoje wyjście kluczem, klucz jest na poziomie zapisu 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 niosą rozszerzenie oczekiwane przez odbiorcę, dzięki czemu klucz można bezpośrednio użyć jako nazwy pliku; alfabet nie zawiera / ani początkowej ., więc jeden klucz nigdy nie zapisze więcej niż jednego segmentu ścieżki i nigdy nie będzie segmentem katalogu nadrzędnego. Klucz spoza alfabetu nie przechodzi walidacji koperty przy ładowaniu przestrzeni roboczej, w aggrega validate oraz w diagnostyce edytora.
Dwa wyjścia artifacts: o tej samej nazwie pliku zatrzymują kompilację podczas renderowania węzła, niezależnie od form, które je utworzyły. Dwa wpisy jednej mapy artifacts: nigdy nie nazywają jednego wyjścia: klucz jest unikalny w obrębie dokumentu i jest pojedynczą nazwą pliku, więc nazwą wyjścia wpisu jednoplikowego jest jego klucz, a wszystkie wyjścia wpisu pakietowego leżą w katalogu nazwanym jego kluczem. Pierwszym segmentem każdej emitowanej ścieżki jest zatem klucz, który ją utworzył, a różne klucze pozostają różnymi nazwami wyjść. Zatrzymanie obejmuje przypadek przekraczający rodzaje wejścia — jedną nazwę pliku dostarczoną przez dwa z nich, np. szablon charta i wpis artefaktu, które oba tworzą servicemonitor.yaml — z diagnostyką wskazującą każde źródło.
Kontekst szablonu dla artefaktów
Szablony artefaktów mają dostęp do pełnego kontekstu filarów:
.values,.infra,.context.*,.locals,.provides,.features,.metadata— standardowe filary Aggrega opisane w 06-data-taxonomy-and-composition.md..workload— sparsowana specyfikacja encji Workload dla tej encji Recipe (jeśli istnieje). Pozwala artefaktom odwoływać się do wartości encji Workload bez duplikacji, np. ServiceMonitor odwołujący się do.workload.services.metrics.ports.prom..source— rozwiązana zawartość polasource:(jeśli istnieje).
Artefakty są obliczane po sparsowaniu encji Workload, więc .workload jest dostępne, gdy istnieje. Dla encji Recipes bez workload: .workload ma wartość nil; szablon próbujący go wyłuskać kończy się czytelnym błędem. Dla encji Recipes bez source: .source ma wartość nil z takim samym skutkiem.
Niezmiennik samowystarczalności
Artefakty muszą być samowystarczalne. Mogą odwoływać się wyłącznie do zadeklarowanych wejść encji Recipe: kontekstu filarów, własnej encji Workload encji Recipe (gdy istnieje) oraz własnej wartości source: encji Recipe. Nie mogą odwoływać się do:
- Wyjść innych encji Recipes w tej samej granicy.
- Zastanych zasobów Kubernetes, których encja Recipe nie zadeklarowała.
- Obiektów Secret, ConfigMap ani innych zasobów, których istnienie na zewnątrz jest zakładane (chyba że odwołanie następuje przez zadeklarowany filar).
Artefakt ConfigMap, do którego odwołuje się volumes.*.configmap.source encji Workload, musi być emitowany przez TĘ encję Recipe (przez artifacts: tworzące ten ConfigMap) lub przez encję Feature dołączoną do tego węzła. Zależności między encjami Recipe w obrębie granicy nie są obsługiwane.
Ten niezmiennik zachowuje wielokrotną używalność encji Recipe: encję Recipe można umieścić w dowolnym zestawieniu Aggregate + Release, które spełnia jej kontrakt filarów, bez ukrytych zależności.
Etykiety pochodzenia
Po translacji każdy emitowany plik nosi w swoich metadanych informacje o pochodzeniu aggrega.ai/* — niezależnie od tego, czy został wyrenderowany ze źródła, zsyntetyzowany z workloadu, czy wyemitowany z szablonu artefaktu. Każda powierzchnia emitująca stempluje je z jednego wspólnego zestawu builderów, więc ten sam plik zawsze nosi te same informacje o pochodzeniu bez względu na to, który rodzaj wejścia go wytworzył. Zestaw dzieli się według tego, czy wartość spełnia zestaw znaków dozwolony dla wartości etykiet Kubernetes: klucze bezpieczne dla etykiet są etykietami (można po nich wyszukiwać); klucze niespełniające tego zestawu znaków — recipe-uri (zawiera :), boundary-path (zagnieżdżona ścieżka zawiera /) i sync-wave (początkowy - ujemnej fali) — są adnotacjami, których wartości nie podlegają ograniczeniom. Wartość tożsamości, której build nie podporządkowuje regułom etykiet — nazwa agregatu, środowisko, nazwa dostawcy, wersje kompilatora i dostawcy — jest etykietą zapisaną w postaci, którą dopuszcza etykieta, a tam, gdzie ta postać różni się od wartości, dosłowna wartość jest także adnotacją pod tym samym kluczem (encja Aggregate o nazwie imported/flow otrzymuje etykietę imported-flow i adnotację imported/flow). Wszystkie pliki niosące wynik tej samej encji Recipe mają te same informacje o pochodzeniu:
metadata: labels: aggrega.ai/component-id: api # ... plus the recommended app.kubernetes.io/name label annotations: aggrega.ai/recipe-uri: api-server-helm:1.0.0 aggrega.ai/boundary-path: productionTen podział jest jednolity dla wszystkich trzech rodzajów wejścia. (Provider Compose nie ma pojęcia adnotacji, a wartości jego etykiet nie podlegają ograniczeniom, więc emituje cały zestaw jako etykiety usług). Stemplowanie pochodzenia w czasie kompilacji opisano w 11-governance-and-compliance.md.
Ponieważ provider stempluje pochodzenie tam, gdzie przenosi je jego własny format wyjściowy, provider, którego format nie oferuje takiego miejsca dla danego pliku, emituje ten plik bez zmian i to zgłasza. Przypadkiem, który należy znać, jest Compose: miejscem pochodzenia jest w nim blok labels: usługi, więc fragment artefaktu compose dostarczający tylko klucze najwyższego poziomu volumes:, configs: lub models: nie nosi informacji o pochodzeniu, a kompilacja emituje ostrzeżenie „skipped provenance label injection” (pominięto wstrzyknięcie etykiet pochodzenia) wskazujące artefakt. Dla fragmentu o takim kształcie to ostrzeżenie jest oczekiwane i nie świadczy o problemie — usługi emitowane przez ten sam komponent noszą pełny zestaw, a emitowane bajty w niczym się nie zmieniają. Wykluczona jest natomiast trzecia możliwość: plik opuszczający kompilację bez stempla i bez wskazania go.
Drugim przypadkiem, który należy znać, jest CloudFormation; różni się on tym, gdzie trafia informacja o pochodzeniu, a nie tym, czy w ogóle trafia. Szablon CloudFormation nie ma bloku metadanych na poziomie dokumentu, który podróżowałby razem z zasobem, więc informacja o pochodzeniu trafia do własnego atrybutu Metadata każdego zasobu, pod jeden klucz aggrega.ai/provenance zawierający cały zestaw:
"StoreBucket": { "Type": "AWS::S3::Bucket", "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/component-id": "store", "aggrega.ai/recipe-uri": "store-recipe:1.0.0", "aggrega.ai/boundary-path": "stack" } }}Z tego miejsca wynikają trzy właściwości. Atrybut Metadata jest dostępny w każdym zasobie niezależnie od jego typu, więc ostemplowany jest każdy zasób złożonego stosu — w tym wiele typów zasobów, które w ogóle nie przyjmują tagów i na których stempel oparty na tagach nie miałby miejsca. Stempel jest dodawany do tego, co autor zapisał w Metadata, zamiast to zastępować, więc własne wpisy autora pozostają obok niego. A ponieważ działa on na poziomie zasobu, a nie szablonu, stos składany z kilku komponentów nosi przy każdym zasobie jego własną tożsamość źródłową — jego komponent, jego encję Recipe i jego granicę — czego pojedynczy wpis dla całego szablonu nie mógłby wyrazić.
Cały zestaw podróżuje razem pod tym kluczem. Wartość Metadata to JSON bez ograniczeń, więc nie ma potrzeby dzielenia według zestawu znaków; dwa klucze, które odczytuje wyłącznie środowisko uruchomieniowe Kubernetes — standardowa zalecana nazwa etykiety oraz adnotacja kolejności wdrażania używana przez kontroler GitOps — są pomijane, ponieważ żaden z nich niczego w stosie nie nazywa. Zwykły wpis pochodzenia aggrega.ai/sync-wave pozostaje, ponieważ zapisuje falę zadeklarowaną przez komponent, a nie instruuje kontrolera.
Kształtem, który nie ma tu miejsca na stempel, jest szablon lub fragment niedeklarujący żadnego zasobu — taki, który dostarcza tylko Parameters, Mappings, Conditions lub Rules. Nie nosi on informacji o pochodzeniu, trafia do złożonego stosu z nienaruszoną własną treścią, a kompilacja emituje ostrzeżenie „skipped provenance injection” (pominięto wstrzyknięcie pochodzenia) wskazujące go. Podobnie jak w przypadku compose, ostrzeżenie to jest oczekiwane dla wkładu o takim kształcie: zasoby dostarczane gdzie indziej przez ten sam komponent noszą pełny zestaw, a emitowane bajty są takie same niezależnie od tego, czy cokolwiek ich nasłuchuje.
Semantyka artefaktów per Provider
Poniższa semantyka dla poszczególnych dostawców opisuje, jak każdy dostawca włącza artefakty do swojego natywnego wyjścia.
Dostawca helm: artefakty to dokumenty YAML Kubernetes zapisywane w katalogu nazwanym od komponentu, który je zadeklarował, wewnątrz katalogu wyjściowego zawierającego manifesty wyrenderowane z chartu i zsyntetyzowane z encji Workload. Powodem jest nazewnictwo: wyrenderowany lub zsyntetyzowany manifest jest nazywany przez dostawcę od komponentu, do którego należy, natomiast artefakt jest nazywany kluczem zapisanym przez autora, który nic nie mówi o tym, o jaki komponent chodzi — dwa komponenty powiązane z jedną encją Recipe zapisałyby więc jedną ścieżkę i żaden z autorów nie mógłby ich rozdzielić. Katalog nosi własną nazwę komponentu, dzięki czemu plik, który autor odczytuje w wyjściu, ma nazwę przez niego zapisaną, o jeden poziom niżej.
Operator, który chce innego układu, ma do dyspozycji szablon subDirectory: granicy, który przenosi każdy plik emitowany przez kontrybutora, a nie tylko artefakty. Zob. ../language-reference/path-template-variables.md.
Dostawca compose: artefakty to fragmenty compose. Klucze najwyższego poziomu (services:, volumes:, configs:, models:) są scalane z łączonym plikiem docker-compose.yaml danej granicy podczas etapu kompozycji granicy.
Dostawca helm-chart (przypadek szczególny): artefakty nie są zapisywane w katalogu wyjściowym jako samodzielne pliki — potokiem renderowania zarządza Helm. Zamiast tego dostawca helm-chart umieszcza każdy wpis artifacts: wewnątrz samego chartu, a forma, w jakiej wpis został zapisany, decyduje o tym, gdzie trafi. Każdy wpis jest NAJPIERW przetwarzany szablonami Go z kontekstem filarów Aggrega, przed jakimkolwiek umieszczeniem; od tego miejsca obie formy się rozchodzą. Wpis ładowany przez $import: jest plikiem szablonu sprzed Helma: jest wstrzykiwany do katalogu templates/ chartu PRZED renderowaniem przez Helm, więc Helm renderuje go razem z własnymi szablonami chartu źródłowego. Wbudowany skalar blokowy jest luźnym plikiem chartu: trafia do katalogu głównego chartu pod zapisanym kluczem, bez prefiksu templates/ i bez scalonych etykiet pochodzenia, dzięki czemu własne szablony chartu mogą go odczytać przez .Files.Get / .Files.Glob Helma — wzorzec ConfigMap z plików. Daje to dostawcy helm-chart mechanizm rozszerzeń równoważny temu, co artifacts: zapewnia zwykłemu dostawcy helm, przy zachowaniu modelu chartów Helma.
Wstrzyknięty plik trafia do boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — pliki pakietu są zagnieżdżone pod tym kluczem — więc leży obok szablonów chartu źródłowego, a Helm pobiera go podczas dalszego przebiegu renderowania. Wbudowany skalar blokowy trafia do boundaries/<bp>/charts/<nodeID>/<authored-key> — katalogu głównego chartu, o jeden poziom nad templates/ — ponieważ plik odczytywany przez .Files musi leżeć tam, gdzie chart go szuka, a plik umieszczony w templates/ zostałby wyrenderowany jako manifest. Obie formy są nazywane kluczem, pod którym je zapisano; różni je katalog, w którym umieszcza je dostawca.
Konwencja ograniczników helm-chart. Wstępny przebieg szablonów Aggrega dla wpisów artefaktów helm-chart, zarówno ładowanych przez $import:, jak i wbudowanych, używa ograniczników [[ ]] zamiast domyślnych {{ }}, aby własna składnia Helma {{ ... }} w pliku przetrwała nienaruszona do przebiegu renderowania Helma. Autorzy zapisują podstawienia po stronie Aggrega jako [[ .context.instance_id ]], [[ .values.name ]] itd.; podstawienia po stronie Helma pozostają jako {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} itd. Mieszanie obu par ograniczników w jednym pliku jest obsługiwanym sposobem pisania.
Pochodzenie a artefakty helm-chart. Pochodzenie jest scalane z metadata.labels i metadata.annotations (zgodnie z podziałem według zestawu znaków opisanym wyżej) dla plików ładowanych przez $import:, które przechodzą przez YAML w obie strony z zachowaniem tokenów Helma — plików używających wyłącznie kontekstu Aggrega [[ ]] lub mających {{ }} Helma tylko w pozycjach skalarów w cudzysłowie. Pliki ze strukturalnymi akcjami szablonów Helma ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} w pozycjach, w których emitują strukturę YAML, a nie liście skalarne) lub pliki z {{ ... }} bez cudzysłowu w pozycjach wartości nie przetrwają przejścia Aggrega przez YAML; kompilacja emituje ostrzeżenie „skipped provenance label injection” (pominięto wstrzyknięcie etykiet pochodzenia) wskazujące artefakt i przekazuje plik bez zmian. To ostrzeżenie jest oczekiwane dla każdego pliku artefaktu helm-chart ładowanego przez $import:, który używa strukturalnych akcji szablonów Helma lub podstawień wartości Helma bez cudzysłowu — jest to typowy przypadek w produkcyjnym pisaniu dla Helma, a nie przypadek brzegowy. Autorzy, którzy potrzebują etykiet pochodzenia w takich plikach, wstrzykują je przez nazwany szablon, który sami piszą we własnym _helpers.tpl chartu (na przykład szablon o nazwie aggrega.commonLabels), lub równoważny mechanizm po stronie Helma, a nie przez wstępne wstrzykiwanie Aggrega.
Kolizje nazw plików w katalogu głównym chartu. Artefakt ładowany przez $import:, którego zapisany klucz koliduje z nazwą pliku w katalogu głównym chartu (Chart.yaml, values.yaml, .helmignore itd.), nie jest wykrywany przez kontrolę kolizji nazw plików Aggrega — artefakt trafia do templates/<authored-key>, a plik katalogu głównego do katalogu głównego chartu, i prefiksowanie ścieżek sprawia, że z punktu widzenia Aggrega są różne. Autorzy unikają takich nazw kluczy; konsekwencją ich użycia jest to, że Helm widzi oba pliki (jeden w katalogu głównym chartu, jeden w templates/) i może nieoczekiwanie wyrenderować kopię z szablonów.
Dostawca terraform: artefakty to pliki konfiguracji Terraform, emitowane dosłownie do własnego katalogu komponentu w drzewie modules/ granicy. HCL (main.tf) jest ergonomicznym domyślnym wyborem, a Terraform JSON (.tf.json) jest akceptowany równoważnie; żaden nie jest transpilowany ani przeformatowywany. Konfiguracja główna granicy deklaruje ten komponent jako blok module, którego source wskazuje ten katalog, dzięki czemu cała granica pozostaje jednym grafem zależności; jest to ten sam katalog, który zajmują pliki dołączonego modułu, więc encja Recipe deklarująca zarówno source:, jak i artifacts: zapisuje je obok siebie. Pochodzenie jest przenoszone jako początkowy blok komentarza Terraform; gdy komponent dostarcza treść JSON, która nie ma składni komentarzy, każda treść jest emitowana bez zmian, a pochodzenie trafia do towarzyszącego pliku .tf zawierającego wyłącznie komentarz, obok nich, więc znacznik nigdy nie jest powielany w obu. Zob. stronę dostawcy terraform.
Dostawca cloudformation: artefakty to fragmenty stosu — zasoby, które dostarcza jeden komponent, a nie cały szablon. Dostawca normalizuje każdy fragment do czysto JSON-owych funkcji wewnętrznych w formie długiej i scala go z pojedynczym stosem złożonym dla danego katalogu wyjściowego, w którym zasoby łączą się w jedną mapę Resources, a provides komponentu pojawiają się jako Outputs stosu pod nazwami ograniczonymi do publikującego komponentu. To, które z pozostałych sekcji najwyższego poziomu fragmentu przetrwają składanie, opisano w sekcji Co scalony dokument przenosi z artifacts:. Zob. stronę dostawcy cloudformation.
Zakres granicy: pliki dla wspólnego wyniku granicy
Mechanizm artefaktów ma drugi zakres. Wszystko, co opisano powyżej, jest zapisywane w miejscu własnym komponentu w wyniku jego granicy; spec.boundary.artifacts w encji Recipe to ta sama mapa — te same trzy formy, ta sama reguła przekształcania klucza w nazwę pliku, ten sam kontekst szablonu — zapisywana natomiast jednokrotnie dla granicy jako całości. Istnieje ona dla pliku, który środowisko docelowe odczytuje raz dla wszystkiego, co wdraża granica, i którego nie może pomieścić miejsce własne żadnego komponentu: dokumentacja Terraform mówi, że moduł przeznaczony do wywoływania nie może zawierać bloków provider, a modułu, który je zawiera, nie można wywołać z depends_on, count ani for_each, dlatego konfiguracja dostawcy należy do konfiguracji głównej granicy, a nie do modułu komponentu.
Gdzie trafia plik. Do katalogu zawierającego złożony wynik grupy dyspozycji, obok plików, które zapisuje tam własne składanie dostawcy — w przypadku terraform obok konfiguracji głównej. Kompilator ewaluuje każdy wpis raz dla każdego komponentu renderowanego przez encję Recipe, w kontekście tego komponentu, i sam zapisuje plik: dostawca nie otrzymuje żadnego z tych plików i nic nie jest w nich oznaczane, by wskazać, z którego komponentu pochodzą, ponieważ plik należy do każdego współtwórcy, który go zadeklarował.
Jak spotykają się współtwórcy. Pliki zadeklarowane przez wszystkich współtwórców jednej grupy dyspozycji są scalane według nazwy. Jedna nazwa zadeklarowana z identycznymi bajtami daje jeden plik; jedna nazwa zadeklarowana z różnymi bajtami albo nazwa, którą zapisuje samo składanie dostawcy, zatrzymuje kompilację ze wskazaniem pliku i każdego współtwórcy — tak samo jak odmowa, którą napotykają dwaj współtwórcy zapisujący jedną ścieżkę wyjściową. Konfigurację dostawcy potrzebną dwóm encjom Recipes zapisują więc obie pod jedną nazwą, a kompilacja sprawdza, czy są zgodne.
Kto to akceptuje. To, czy plik umieszczony obok złożonego wyniku granicy cokolwiek znaczy, jest właściwością środowiska docelowego dostawcy, jest to więc deklaracja samego dostawcy, odczytywana z jego własnej deklaracji tak jak jego rodzaje wejść. Encja Recipe deklarująca ten blok dla dostawcy, który go nie deklaruje, jest odrzucana, zanim cokolwiek zostanie wyrenderowane. Poniższa tabela zawiera tę deklarację w ostatniej kolumnie; spośród dostawców dystrybuowanych z kompilatorem składa ją terraform.
Czym artefakty nie są
Trzy rozróżnienia strukturalne:
Nie działają między dostawcami w obrębie jednej encji Recipe. Encja Recipe deklaruje dokładnie jedno capability: na początku swojego spec. Wszystko, co produkuje encja Recipe — wynik renderowany ze źródła, wynik syntetyzowany z workloadu i emitowane artefakty — jest w natywnym formacie tego dostawcy. Artefakty encji Recipe dla helm zawierają YAML Kubernetes. Artefakty encji Recipe dla compose zawierają fragmenty compose. Encja Recipe jest kierowana do jednego dostawcy; każdy wynik jest w natywnym formacie tego dostawcy.
Kompozycja wielu dostawców odbywa się na poziomie encji Release. Granice zawierają komponenty różnych dostawców; współtwórcy każdego dostawcy na ewaluowanej ścieżce granicy są dysponowani i składani niezależnie dla każdej pary (ścieżka, dostawca). Encja Release z komponentami kierowanymi odpowiednio do helm, helm-chart i compose może umieścić wszystkie trzy w jednej granicy; grupowanie dyspozycji dzieli je według dostawcy, współtwórcy każdego dostawcy trafiają do własnego złożonego wyniku pod ścieżką granicy, a operator tworzy koordynację między dostawcami za pomocą wybranej przez siebie struktury granic. Koordynacja między dostawcami należy do autora encji Release.
Nie są encjami Recipes w encjach Recipes. Artefakty nie ładują ani nie komponują innych encji Recipes. Są to wbudowane manifesty (lub ścieżki plików do wbudowanych manifestów), szablonowane filarami tej encji Recipe i emitowane do wyniku tej encji Recipe. Ponowne użycie encji Recipe odbywa się za pomocą trzech mechanizmów: extends: encji Component (encja Recipe napisana dla bazowej encji Component obsługuje każdą encję Component, która ją rozszerza; dziedziczone są metadane i schematy, a nie pliki wynikowe — sama encja Recipe nie deklaruje extends:); płaskie mapowanie URI w encji Manifest (ta sama encja Component może być rozwiązywana do różnych encji Recipes w różnych katalogach — zob. ../language-reference/entities/manifest.md); oraz Features + FeatureRecipes (zagadnienia przekrojowe dołączane ortogonalnie).
Nie są warstwą spajającą między encjami Recipe. Artefakty nie mogą odwoływać się do nazw, zasobów ani stanu, których encja Recipe sama nie zadeklarowała. Artefakt ConfigMap, do którego odwołuje się encja Workload tej encji Recipe, musi być emitowany przez tę encję Recipe. Artefakt oczekujący zewnętrznie przygotowanego obiektu Secret musi uzyskać nazwę tego obiektu przez filar .features — z rozwiązanych provides dołączenia, które go emituje — a nie zakładać, że istnieje. Jest to niezmiennik samowystarczalności (opisany powyżej) ujęty z perspektywy tworzenia artefaktów: każda encja Recipe emituje pliki w jednym formacie, stosowane przez jedno narzędzie, do katalogu wynikowego jednej granicy.
Macierz możliwości Provider
Każdy dostawca deklaruje, które rodzaje wejścia renderuje; centralna bramka rodzajów wejścia przyjmuje obsługiwane kombinacje i odrzuca pozostałe z jednolitą diagnostyką w chwili renderowania węzła. Możliwość jest właściwością dostawcy, a nie encji Recipe — dostawca renderuje podzbiór trzech rodzajów. Kolumna artifacts: odróżnia artefakty dołączane obok głównego wejścia ze źródła lub syntetyzowanego od samodzielnej encji Recipe zawierającej wyłącznie artefakty (bez source: i bez workload:). Dwie ostatnie kolumny to deklaracje dostawcy, że respektuje omits: oraz że przyjmuje pliki, które encja Recipe dodaje do wspólnego wyjścia swojej granicy w boundary.artifacts: (powyżej); żadna z nich nie jest rodzajem wejścia.
Każdą kolumnę należy czytać osobno. Wiersz mówi, które rodzaje dostawca renderuje, brane pojedynczo. Nie mówi, że dwa zaznaczone rodzaje można zadeklarować razem. Ponieważ rodzaje składają się przez dodawanie, każdy zadeklarowany rodzaj jest przekazywany i emitowany osobno, więc para może zostać odrzucona z powodu, którego nie pokazuje żadna kolumna — najczęściej dlatego, że oba rodzaje tworzą plik o tej samej nazwie wyjściowej. Kombinacje faktycznie przyjmowane przez każdego dostawcę opisano w sekcji Co dokładnie przyjmuje każdy dostawca.
| Provider | source: + valuesMapping: | workload: | artifacts: (obok) | tylko artefakty (samodzielnie) | omits: | boundary.artifacts: |
|---|---|---|---|---|---|---|
| helm | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| compose | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| helm-chart | ✅ | ❌ | ✅ szablonowane z ogranicznikami [[ ]] | ❌ | ❌ | ❌ |
| terraform | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| cloudformation | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
Ta tabela obejmuje dostawców dystrybuowanych z kompilatorem. Dostawca dostarczany osobno deklaruje w ten sam sposób przyjmowane rodzaje wejścia, to, czy respektuje omits:, oraz to, czy przyjmuje boundary.artifacts:, a kompilator odczytuje tę deklarację tą samą drogą — nie jest tu wymieniony, ponieważ opublikowana strona nie może wyliczyć dostawców, których nigdy nie widziała.
Komórki oznaczone ✅ są renderowane; ❌ oznacza odmowę wynikającą z możliwości dostawcy, zgłaszaną przez bramkę. Fragmenty compose poszczególnych węzłów są scalane według ścieżki składania, więc granice współdzielące directory: współdzielą jeden plik.
Co dokładnie przyjmuje każdy dostawca
helm — każda kombinacja. source: + valuesMapping:, workload:, artifacts:, dowolne dwa z nich lub wszystkie trzy. Jest to jedyny dostawca dystrybuowany z kompilatorem, który nie odrzuca żadnej kombinacji, a powodem jest sposób nazywania wyjścia: każdy emitowany plik nosi nazwę zasobu, który zawiera, więc wyrenderowane manifesty chartu i manifesty syntetyzowanej encji Workload nigdy nie trafiają pod jedną nazwę. Encja Recipe deklarująca wszystkie trzy emituje pliki chartu, pliki encji Workload i pliki artefaktów obok siebie w katalogu wyjściowym granicy.
compose — każda kombinacja poza dwiema, w których source: i workload: występują razem. Każdy rodzaj osobno się buduje, a artifacts: może towarzyszyć każdemu z nich. source: z workload: nie da się zbudować, podobnie jak wszystkich trzech razem; sekcja Dlaczego compose nie może połączyć źródła z workloadem wyjaśnia dlaczego — nie jest to odmowa wynikająca z możliwości.
helm-chart — source: + valuesMapping:, samodzielnie lub z artifacts: obok. Nic więcej. Nie syntetyzuje workload: i nie ma formy wyłącznie z artefaktami: encja Recipe, której jedynym rodzajem wejścia jest artifacts:, zatrzymuje budowanie. Powodem jest miejsce, w którym ten dostawca umieszcza artefakt — wewnątrz własnego chartu komponentu — więc encja Recipe bez source: nie zostawia mu chartu, w którym mógłby go umieścić.
terraform — trzy kształty: samo source: + valuesMapping:, samo artifacts: albo oba razem. Nie syntetyzuje workload:.
cloudformation — te same trzy kształty co terraform, z tym samym jedynym wykluczeniem. Samo source: + valuesMapping:, samo artifacts: albo oba razem; bez workload:.
Jak wygląda odrzucony rodzaj wejścia
Encja Recipe deklarująca rodzaj wejścia, którego powiązany z nią dostawca nie renderuje, zatrzymuje budowanie w chwili renderowania węzła, i to niezależnie od tego, co jeszcze deklaruje obok tego rodzaju — połączenie workload: z source:, które dostawca potrafi wyrenderować, nie przeprowadza workloadu. Komunikat o zatrzymaniu podaje dostawcę, rodzaj, którego nie potrafi wyrenderować, oraz rodzaje, które renderuje:
[CATALOG_ERROR E0265] instance unit provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesizedOdmowa dla formy wyłącznie z artefaktami brzmi analogicznie i nazywa tę formę: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 to identyfikator, który należy zapisać, gdy to zatrzymanie trzeba trwale nazwać — w bramce ciągłej integracji, zgłoszeniu lub runbooku; tabela wszystkich warunków go rozwiązuje.
Dlaczego compose nie może połączyć źródła z workloadem
Dostawca compose tworzy jeden fragment na komponent i nadaje mu nazwę komponentu. Renderowanie ze źródła i synteza encji Workload tworzą fragment tego komponentu pod tą jedną nazwą, więc encja Recipe deklarująca oba tworzy dwa pliki o tej samej nazwie, a budowanie zatrzymuje się na kolizji:
[CATALOG_ERROR E0211] instance unit rendering node "unit" caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")Nazwa fragmentu pochodzi z identyfikatora samego komponentu i nie ma dla niej żadnej powierzchni autorskiej, więc żadna zmiana treści encji Recipe nie pozwala uniknąć kolizji. Zatrzymanie jest właściwością pary, a nie któregokolwiek z rodzajów — compose renderuje źródło i compose syntetyzuje encję Workload, więc tabela słusznie zaznacza oba. Aby użyć obu kształtów dla jednego komponentu w compose, należy rozdzielić je na dwa komponenty albo włączyć treść źródła do encji Workload.
Co scalony dokument przenosi z artifacts:
Dwa providery scalają swoich kontrybutorów w jeden dokument na ścieżkę złożenia: compose w jeden plik docker-compose.yaml, cloudformation w jeden szablon stosu. Scalony dokument może przenosić tylko te sekcje, które modeluje jego asembler, więc zaznaczenie w kolumnie artifacts: mówi, gdzie zostaje umieszczona zawartość fragmentu, a nie, że zachowuje się każdy klucz wewnątrz fragmentu.
compose przenosi z fragmentu artefaktu services:, volumes:, configs: i models: wraz z jego kluczami rozszerzeń z prefiksem x-. Fragment deklarujący na najwyższym poziomie cokolwiek innego zatrzymuje kompilację, wskazując klucz — networks:, ponieważ sieci są wyprowadzane dla każdej granicy, a nie gromadzone od kontrybutorów, a także blok secrets: czy klucz name: najwyższego poziomu. Strona providera compose podaje reguły scalania dla poszczególnych kluczy oraz alternatywę dla routingu między sieciami.
cloudformation przenosi Resources, Outputs, Parameters, Mappings, Conditions, Metadata i Rules, a Transform buduje z sekcji każdego kontrybutora. Transformacje są łączone w kolejności, którą dokumentuje CloudFormation, przy czym Globals z SAM przechodzą razem z transformacją, która je odczytuje, a transformacja, która zmieniłaby sposób wdrażania zawartości innego kontrybutora, zatrzymuje kompilację, podając jej nazwę. Description nie jest przenoszony, a kompilacja to zgłasza: emituje ostrzeżenie o nieobsługiwanym polu, wskazujące sekcję i komponent, podobnie jak dla każdego innego klucza najwyższego poziomu, którego stos nie przenosi, więc nic nie jest pomijane po cichu. Ostrzeżenie ma charakter informacyjny — wyemitowany szablon jest bajt w bajt taki sam, jaki byłby bez niego, a --no-unsupported-field-warnings wycisza tę klasę ostrzeżeń. Outputs jest przenoszony pod nazwą, którą provider zawęża do wnoszącego go komponentu, więc dwa komponenty wnoszące do jednego stosu wyjście o tej samej nazwie zachowują je osobno. Sekcje najwyższego poziomu w złożonym stosie omawia każdą sekcję po kolei.
Pozostali trzej dostawcy nie scalają, więc żaden klucz artefaktu nie jest narażony na odrzucenie przez asembler. helm niczego nie składa: manifesty każdego komponentu trafiają do katalogu wyjściowego granicy w niezmienionej postaci. terraform i helm-chart zagnieżdżają — pliki każdego komponentu trafiają do osobnego katalogu, katalogu modułu Terraform lub subchartu, a dokument główny na poziomie granicy się do nich odwołuje — więc wpis artefaktu jest umieszczany jako cały plik, a nie wczytywany do wspólnego dokumentu. Gdzie trafia wpis artefaktu helm-chart i dlaczego jego para ograniczników jest inna, opisano w sekcji Per-Provider Artifact Semantics.