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

Konwencje nazewnictwa

Ten rozdział omawia reguły nazewnictwa i wielkości liter obowiązujące w treściach tworzonych w Aggrega: wzorzec nazw instancji tworzonych przez użytkownika, zasady wielkości liter w nazwach pól w DSL, wielkość liter, której platforma używa w identyfikatorach definiowanych przez nią, a nie przez autora, oraz składnię komentarzy używaną w warstwie tworzenia YAML.

Nazwy instancji

Nazwy instancji tworzone przez użytkownika — klucze, które programista zapisuje dla komponentów, funkcji, agregatów, podsystemów, granic oraz gniazd uses i aliasów — pasują do jednego wzorca: ^[a-zA-Z0-9_-]+$. Poprawne są zarówno kebab-case (pii-filter, my-agent), jak i snake_case (openai_key, db_credentials); zespoły mogą przyjąć dowolną preferowaną konwencję.

Dozwolone znaki: znaki alfanumeryczne (a-z, A-Z, 0-9), łączniki (-) i podkreślenia (_). Żadne inne znaki nie są dozwolone.

Przykłady:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
WzorzecZakresPrzykłady
^[a-zA-Z0-9_-]+$Wszystkie nazwy instancji tworzone przez użytkownikaweb-server, openai_key, pii-filter

Wzorzec jest egzekwowany podczas rozwiązywania za pomocą patternProperties z JSON Schema.

Ile kosztuje nazwa komponentu i dlaczego wielkie litery kosztują więcej w niektórych środowiskach docelowych

Powyższy wzorzec określa, co można zapisać. Ile nazwa kosztuje, to osobna kwestia, zależna od środowiska docelowego, w którym komponent jest wdrażany — warto więc to wiedzieć przed wyborem nazwy, a nie dopiero wtedy, gdy kompilacja ją odrzuci.

Nazwa komponentu staje się tożsamością, którą oznaczany jest każdy emitowany przez niego zasób, a każde środowisko docelowe wyprowadza z tej tożsamości własne nazwy: instalator chartów wyprowadza nazwę wydania, orkiestrator kontenerów — nazwy usług. Środowisko docelowe, którego alfabet jest węższy niż wzorzec, nie może przenieść znaku, którego nie dopuszcza, a Aggrega nie zamieni po cichu takiego znaku na podobny — dwie nazwy, które autor potrafi odróżnić, nie mogą stać się jedną nazwą w klastrze. Dlatego znak niedopuszczany przez środowisko docelowe jest zapisywany jako sekwencja ucieczki, a sekwencja ucieczki jest dłuższa niż zastępowany znak.

Praktyczna konsekwencja: wielka litera jest darmowa w niektórych środowiskach docelowych, a kosztowna w innych.

  • W środowisku docelowym, którego nazwy dopuszczają wielkie litery — na przykład w pliku compose do orkiestracji kontenerów — PaymentsAPI jest przenoszone dokładnie tak, jak zostało zapisane, i kosztuje jedenaście znaków.
  • W środowisku docelowym, którego nazwy mogą zawierać tylko małe litery — w nazwie wydania instalatora chartów — każda wielka litera jest poprzedzana sekwencją ucieczki, a nazwa złożona z samych sześciu wielkich liter już przekracza to, co to środowisko akceptuje.

Istnieje drugi, poważniejszy efekt: sekwencja ucieczki zaczyna się od łącznika. Środowisko docelowe, które wymaga, aby nazwa zaczynała się od małej litery lub cyfry, odrzuci więc nazwę, której pierwszy znak jest przez nie niedopuszczany, niezależnie od tego, jak krótka jest reszta — żadne skracanie tego nie naprawi.

Zalecenia wynikają z tych dwóch efektów. Należy preferować małe litery i cyfry, z łącznikami między słowami, i zaczynać nazwę od małej litery. payments-api jest przenoszone bez zmian przez każde środowisko docelowe, dla którego Aggrega dostarcza dostawcę. payments_api jest przenoszone przez plik compose, ale nie przez środowisko docelowe helm, którego nazwy zasobów nie dopuszczają podkreślenia: obiekty Service, obciążenia i wydanie nazwane od komponentu otrzymują pisownię payments-zuapi. PaymentsAPI kosztuje tam jeszcze więcej. Encja Recipe publikująca adres takiego zasobu odczytuje pisownię własną środowiska docelowego, zamiast ją przewidywać — zob. templates/rendered-resource-names.md.

Cyfra na początku jest dozwolona w zapisie i nic nie kosztuje w pliku compose, ale środowisko docelowe helm ją odrzuca. Nazwa obiektu Service w Kubernetes musi zaczynać się od litery, a obiekty Service emitowane przez chart lub syntetyzowane obciążenie są nazywane od komponentu, więc komponent o nazwie 1cache zatrzymuje kompilację helm — odmowa wskazuje komponent i informuje, że nazwa obiektu Service musi zaczynać się od litery — zamiast renderować obiekty Service, które klaster by odrzucił.

Nic z tego nie jest regułą stosowaną przez kompilator z własnej inicjatywy — nie zna on reguł nazewnictwa żadnego środowiska docelowego i nie wymyśla żadnych limitów. Dostawca każdego środowiska docelowego odpowiada za własne nazwy, więc nazwa jest odrzucana tylko wtedy, gdy środowisko docelowe, w którym komponent jest faktycznie wdrażany, stwierdza, że nie może jej użyć, a odmowa zawiera powód podany przez to środowisko i wskazuje zapisany klucz spec.components. Nazwa poprawna w jednym środowisku docelowym i odrzucana w innym to oczekiwane zachowanie, a nie niespójność.

Nazwy składane przez samą Aggrega — na przykład tożsamość funkcji dołączonej na granicy — są traktowane odwrotnie: są skracane, aby zmieścić się w środowisku docelowym, zamiast być odrzucane, ponieważ składają się z części zapisanych w wielu miejscach i żaden pojedynczy autor nie widzi długości, jaką osiągają. Odrzucana jest tylko nazwa zapisana przez autora.

Kropka jako zarezerwowany separator ścieżki

Znak kropki (.) jest wyłączony ze wszystkich nazw instancji tworzonych przez użytkownika. Kropka pełni strukturalną funkcję separatora ścieżki generowanego przez kompilator w odwołaniach do komponentów między agregatami.

Gdy główna encja Aggregate importuje podagregat o nazwie data-layer zawierający komponent o nazwie main-db, kompilator tworzy spłaszczony bezwzględny identyfikator data-layer.main-db, łącząc kropką nazwę instancji agregatu i nazwę instancji komponentu. Ta ścieżka z kropką pojawia się w:

  • Celach uses dewelopera: target: data-layer.public_db — odwołanie do eksportowanego komponentu z zagnieżdżonego agregatu.
  • Własnej diagnostyce kompilacji: zatrzymanie lub ostrzeżenie dotyczące tego komponentu nazywa go jego ścieżką z kropką, więc odczytaną nazwę można wyszukać w swoich dokumentach.

Separator nie trafia do nazwy

Ścieżka z kropką jest adresem wewnątrz dokumentów i nie jest nazwą, którą zaakceptuje cel wdrożenia. Nazwa obiektu Service w Kubernetes w ogóle nie dopuszcza kropki; co gorsza, kropka w adresie klastra oddziela usługę od przestrzeni nazw, w której się znajduje, więc nazwa z kropką przekazana konsumentowi jako host zostałaby rozwiązana do innej usługi, zamiast zakończyć się błędem.

Dlatego separator jest zapisywany w postaci zakodowanej we wszystkich nazwach i etykietach, które kompilacja wyprowadza z tożsamości komponentu, i jest kodowany, a nie zastępowany: data-layer.main-db staje się data-layer-zdmain-db. Zastąpienie go znakiem, który cel akceptuje, pozwoliłoby dwóm różnym komponentom dojść do jednej nazwy — data-layer.main-db i komponentowi, który ktoś zapisał jako data-layer-main-db — a nazwa, do której dochodzą dwa komponenty, nie identyfikuje żadnego z nich.

Czego to dotyczy, a czego nie:

  • Dotyczy nazw i etykiet wyprowadzanych z tożsamości — metadata.name w zasobie syntetyzowanym przez Aggrega, etykiet aggrega.ai/component-id i app.kubernetes.io/name, selektorów, które do nich pasują, emitowanych nazw plików, {{ .context.instance_id }} oraz nazwy, którą provider wyprowadza dla siebie, na przykład nazwy release w helm. Zmieniają się razem, więc adres, który encja Recipe składa z klucza nazywającego zasób — .context.instance_id, gdy cel nazywa zasób według tożsamości, .context.rendered_name, gdy cel zgłasza własną nazwę — nadal wskazuje zasób emitowany przez kompilację.
  • Nie dotyczy nazwy zapisanej przez autora. Nazwa komponentu bez separatora wraca bajt w bajt, więc inaczej niż w dokumencie jest zapisany w wyniku tylko komponent wnoszony przez importowaną encję Aggregate.
  • Nie dotyczy nazw wewnątrz chartu lub fragmentu dostarczonego przez autora. Należą one do tego, kto je napisał, a nazwa przeniesiona z chartu zewnętrznego — nazwa zasobu niestandardowego w postaci <plural>.<group>, w której kropka jest dozwolona — jest emitowana dokładnie tak, jak zapisał ją ten chart.

🔴 Ostatni punkt ma konsekwencje dla tego, co powinna publikować encja Recipe, i najłatwiej tu o błąd. Własne szablony dostarczonego chartu nazywają swoje zasoby według tożsamości przekazanej im przez platformę — nazwy release zapisanej w alfabecie tej platformy, a nie w opisanym powyżej — a cel helm nazywa syntetyzowane przez siebie workloady według tej samej nazwy release. Dlatego dla wyniku renderowanego z dostarczonego źródła oraz dla workloadu syntetyzowanego w takim celu {{ .context.instance_id }} nie jest nazwą tych zasobów, a adres opublikowany na jego podstawie nie wskazuje niczego, ilekroć oba alfabety się różnią. Klucz zawierający nazwę platformy oraz to, które providery ją zgłaszają, opisano w templates/rendered-resource-names.md.

Kodowanie separatora kosztuje znaki, a nazwie o ograniczonej długości może ich zabraknąć. Separator jest zastępowany krótką sekwencją ucieczki, a nie pojedynczym znakiem, więc kwalifikowana tożsamość po zapisaniu jest nieco dłuższa niż w dokumentach. Ma to znaczenie tylko tam, gdzie wynikowa nazwa ma ograniczoną długość: cel renderujący komponent określa, jak długą wartość etykiety zaakceptuje, a gdy zapisana tożsamość by ją przekroczyła, kompilacja zatrzymuje się, zamiast emitować wartość, którą cel by odrzucił. Komunikat zatrzymania podaje długość, w której musi zmieścić się sama tożsamość — długość przed zakodowaniem, więc nazwa dobrana w tym limicie działa za pierwszym razem — a rozwiązaniem jest skrócenie części tworzonych przez autora: nazwy, którą dokument importujący nadaje podagregatowi, lub własnej nazwy komponentu w nim.

Separator jest zwykłym powodem, dla którego nazwa jest zapisywana dłużej, niż wygląda, ale nie jedynym. Dwie dozwolone postaci nazwy autora również nie mogą zostać przeniesione bez zmian, ponieważ ich pozostawienie uczyniłoby sekwencję ucieczki niejednoznaczną: nazwa kończąca się łącznikiem oraz nazwa, w której bezpośrednio po łączniku występuje z. Każda z nich jest kodowana w ten sam sposób, z tym samym kosztem. Każda inna nazwa autora wraca bajt w bajt, więc nie dotyczy to nazw zbudowanych z liter, cyfr, podkreśleń i łączników między słowami.

Nazwa gniazda we własnym bloku uses komponentu albo odpowiada kluczowi w usesSchema encji katalogu — zadeklarowanemu gniazdu — albo wskazuje własne gniazdo ad hoc programisty, które buduje się nawet w encji niedeklarującej w ogóle usesSchema; nazwa różniąca się od zadeklarowanego gniazda o jedną edycję powoduje ostrzeżenie podające obie pisownie. uses dla poszczególnych krawędzi w encji Release, a także odpowiednie ustawienie dołączenia encji Feature, może wskazywać wyłącznie gniazdo zadeklarowane przez encję, a każda inna nazwa kończy się błędem walidacji unknown-uses-socket.

Wielkość liter w nazwach pól

DSL oddziela YAML przeznaczony dla programistów (pisany przez ludzi) od wewnętrznych kontraktów kompilatora (konsumowanych przez szablony i narzędzia):

  • YAML dla programistów (camelCase): Wielowyrazowe nazwy pól w schematach Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest i Plugin używają camelCase. Przykłady: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Zgodne z konwencjami API Kubernetes.
  • Kontrakty wewnętrzne (snake_case): Wielowyrazowe nazwy pól w schemacie grafu IR i schemacie kontekstu szablonu używają snake_case. Przykłady widoczne dla autorów encji Recipe: instance_id (w .context.instance_id — tożsamość encji Recipe), inject_raw (w .inject_raw, filar najwyższego poziomu obok .inject, a nie klucz w .context — niezmieniony kontrakt wstrzykiwania), attachment_name (w kontekście dołączanej encji FeatureRecipe — określa slot, który wypełnia dołączenie, lub nazwę, pod którą zostało dołączone). Zgodne z konwencjami JSON API i spójne z generowaniem tagów struktur JSON w Go.
  • Pola jednowyrazowe: Małymi literami niezależnie od kontekstu. Przykłady: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

Programiści nie spotykają snake_case w pisanym przez siebie YAML, a autorzy szablonów nie spotykają camelCase w swoich szablonach Go. Rozszerzenia schematu stosują się do tych konwencji.

Trzy konwencje wielkości liter w jednej instrukcji

Pisanie encji Recipe rutynowo łączy wszystkie trzy konwencje wielkości liter w jednej instrukcji: pole DSL zdefiniowane w schemacie używa camelCase, nazwa instancji nadana przez użytkownika używa kebab-case lub snake_case, a odwołanie do kontekstu szablonu używa snake_case. Autorzy, którzy dostrzegają te przejścia jako odrębne konwencje, czytają wynikowy YAML bez trudu; autorzy próbujący sprowadzić je do jednej konwencji mają problem z granicami.

Kanoniczny przykład: szablon valuesMapping: encji Recipe odwołujący się do renderowanej instancji Component przez kontekst szablonu.

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

Trzy konwencje, jedna instrukcja:

  • valuesMapping — camelCase. Nazwa pola DSL, którą schemat definiuje dla szablonu mapowania encji Recipe. Camel, ponieważ YAML języka przeznaczony dla programistów stosuje konwencje API Kubernetes.
  • web-server (przywoływana pośrednio przez renderowany komponent) — kebab-case. Nazwa instancji nadana przez użytkownika w encji Aggregate; programista wybrał formę z łącznikami. Równie dobrze mogłaby to być web_server (snake_case); obie są poprawne według wzorca nazw instancji.
  • instance_id, image — snake_case. Nazwy pól w kontekście szablonu (.context.instance_id, .values.image). Snake, ponieważ graf IR i kontekst szablonu stosują konwencje JSON-API i są spójne z generowaniem tagów struktur JSON w Go.

Te trzy konwencje nie są wymienne. Autor encji Recipe, który napisze {{ .context.instanceId }} (camelCase), zatrzymuje kompilację: .context deklaruje swoje klucze, a instanceId nie jest jednym z nich, więc odwołanie zostaje odrzucone, zanim cokolwiek zostanie wyrenderowane, a diagnostyka wymienia klucze, które .context definiuje — zob. errors/fatal-halts.md „Template references a root the render context does not define (Szablon odwołuje się do korzenia, którego kontekst renderowania nie definiuje)”. Programista, który napisze web.server (z kropką), zostanie odrzucony przez wzorzec nazw instancji, ponieważ kropka jest zarezerwowana jako separator ścieżki. Cel tej dyscypliny: pamiętać o trzech konwencjach podczas czytania i pisania; polegać na granicach (miejscu w YAML lub szablonie), aby wiedzieć, która konwencja obowiązuje.

Identyfikatory definiowane przez platformę

Wszystko powyżej dotyczy nazw na powierzchni tworzenia — nazwy instancji wybieranej przez autora, pola schematu, które język definiuje do wypełnienia, klucza kontekstu szablonu, który się odczytuje. Dwa kolejne rejestry dotyczą identyfikatorów, które definiuje sama platforma, a użytkownik jedynie je odczytuje lub wpisuje. Są one rozdzielone, ponieważ pełnią różne zadania, a to zadanie decyduje o kształcie.

Rejestr opisowy: jednolicie kebab-case. Identyfikator w tym rejestrze mówi słowami, co nazywa, dzięki czemu można go odczytać i na jego podstawie działać bez sprawdzania czegokolwiek. Należą do niego flaga CLI, identyfikator reguły lintera publikacji, kod klasy diagnostyki oraz kod, pod którym zarejestrowano warunek zatrzymania.

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

Tam, gdzie klasa diagnostyki ma flagę wyciszającą, kod i flaga składają się z tych samych słów w tej samej kolejności — unsupported-field wycisza się flagą --no-unsupported-field-warnings — więc dopasowana klasa wskazuje, po którą flagę sięgnąć, bez żadnego tłumaczenia. Kod klasy to stabilna nazwa, którą narzędzia dopasowują, aby rozpoznać wynik bez parsowania tekstu komunikatu; brzmienie komunikatu może się poprawiać, kod się nie zmienia.

Rejestr krótkich kodów: litera E i cztery cyfry. Warunek zatrzymania ma również krótki kod — E0007 — i jest to jedyny identyfikator definiowany przez platformę, który nie jest w kebab-case. Powodem jest położenie: otwiera on każdą diagnostykę zatrzymania, obok kategorii, przed plikiem i wierszem, które za chwilę się przeczyta.

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

Kod opisowy nie może się tam znaleźć. Najdłuższy z nich sam wypełniłby wąski terminal, zanim pojawiłaby się lokalizacja wskazująca, gdzie szukać. Dlatego na początku stoi identyfikator dobrany pod kątem szerokości, a ten kompromis jest zamierzony: cztery cyfry nic nie mówią o warunku, i dlatego każdy krótki kod jest opublikowany obok warunku, który nazywa, oraz tekstu, który ten warunek wyświetla, w dokumentacji referencyjnej sentineli błędów. Krótki kod należy podać w zgłoszeniu, wpisać w wyszukiwarkę i tam go rozwinąć.

Oba rejestry nazywają te same warunki z dwóch stron i żaden nie zastępuje drugiego. Kod opisowy należy dopasowywać przy pisaniu narzędzia, które reaguje na warunek; krótki kod należy podawać w rozmowie z człowiekiem o warunku.

Występowanie kebab-case tutaj i w nazwach instancji nie jest kolizją. Wzorzec nazw instancji dotyczy tego, co wolno napisać — tam poprawne są zarówno kebab-case, jak i snake_case, a zespoły wybierają jedno z nich. Ten rejestr dotyczy tego, co platforma sama pisze, gdzie nie ma czego wybierać: użytkownik nigdy nie wybiera pisowni identyfikatora reguły lintera, a platforma nigdy nie wybiera pisowni nazwy komponentu użytkownika.

Nie zmienia to wielkości liter w polach. Tworzone pola schematu pozostają w camelCase, a klucze kontekstu szablonu w snake_case. Żaden z identyfikatorów tego rejestru nie jest polem na żadnej z tych powierzchni — są to krótkie, stabilne nazwy flagi, reguły lub klasy wyniku — więc to, że kod diagnostyki jest w kebab-case, nic nie mówi o pisowni pola schematu.

Dyscyplina sufiksów nazw ścieżek dokumentu

Część pól w całym języku przenosi wartości ścieżek dokumentu — ciągi wskazujące pozycję wewnątrz innego dokumentu (sekcję volumes wyrenderowanego obiektu Workload, wpis featuresSchema encji Component, warstwę mappings encji Manifest). Wartości stosują składnię RFC 6901 JSON Pointer — tokeny rozdzielone ukośnikami, identyfikujące ścieżkę w dokumencie docelowym.

RFC 6901 jest bazową gramatyką ścieżek dla każdej powierzchni ścieżek dokumentu w Aggrega. Kontrakt pluginów Wasm konsumuje dokumenty JSON Patch zgodne z RFC 6902, których ścieżki są wskaźnikami RFC 6901 (zgodnie z wyjściem JSONPatch roli label-transform w plugins/plugin-contract.md); inwentarz ciągów formatujących gramatyki URI wymienia RFC 6901 obok składni szablonów Go i funkcji pomocniczych Sprig (zgodnie z vocabulary/uri-grammar.md, „Format-string inventory”); eksporty .locals poszczególnych encji Recipe używają RFC 6901 do wskazywania pozycji w syntetyzowanych obiektach Workload, które pluginy Wasm Injector otrzymują w potoku pluginów przez ładunek with swojego kroku. Jedna gramatyka, wiele konsumujących ją powierzchni.

Dyscyplina sufiksów nazw rozróżnia dwie strony tworzenia tych wartości ścieżek za pomocą celowego podziału sufiksów, zgodnego z szerszą sekcją o wielkości liter w nazwach pól powyżej:

  • Pola schematu przenoszące wskaźniki RFC 6901 JSON Pointer używają sufiksu camelCase *Path. Pola te są częścią schematu YAML przeznaczonego dla programistów, więc stosują konwencję camelCase. Żaden schemat encji nie deklaruje takiego pola; ścieżki dokumentu zapisywane przez autora to klucze eksportu .locals opisane poniżej.
  • Klucze eksportu .locals przenoszące wskaźniki RFC 6901 JSON Pointer używają sufiksu snake_case *_path. Klucze te są częścią wewnętrznej powierzchni eksportu encji Recipe — odczytywane przez kolejne szablony tej samej encji Recipe oraz przez potok pluginów Wasm poprzez ładunek pipeline[].with, który odwołuje się do .locals — więc stosują konwencję snake_case. Przykłady:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" udostępnia pozycję tablicy volumes syntetyzowanego obiektu Workload.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" udostępnia pozycję tablicy containers.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" udostępnia natywną ścieżkę zasobu Terraform.
    • root_path — .locals.root_path: "/data" udostępnia ścieżkę główną, którą konsumuje potok renderera.

Dwie konwencje sufiksów odzwierciedlają dwupoziomową konwencję z sekcji o wielkości liter w nazwach pól: pola zdefiniowane przez schemat używają camelCase; identyfikatory tworzone przez użytkownika lub prywatne dla encji Recipe używają snake_case (lub kebab-case). Dyscyplina sufiksów *Path / *_path czyni gramatyczny charakter ścieżki widocznym na poziomie identyfikatora — czytelnik widzący którykolwiek z sufiksów wie, że wartość stosuje składnię RFC 6901, bez potrzeby sprawdzania samej wartości.

Przykład: Wasm Injector konsumujący eksporty *_path encji Recipe.

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

Klucze *_path są eksportami prywatnymi encji Recipe; wartości containers_path / volumes_path są ciągami RFC 6901 JSON Pointer. Plugin Injector konsumuje te ciągi, aby umieścić swoje wyjście JSONPatch względem AST wyrenderowanego obiektu Workload. Dołączenie sięga do nich przez własny filar .locals — nie istnieje pole .context.uses[].locals, więc konsument nie może odczytać zmiennych lokalnych swojego celu poprzez krawędź uses; przez krawędź przechodzi provides celu.

Szerszy inwentarz ciągów formatujących (składnia szablonów Go, funkcje Sprig, JSON Pointer obok wyrażeń regularnych SemVer i gramatyki selektorów etykiet) opisuje vocabulary/uri-grammar.md, „Format-string inventory”. Powierzchnię kontraktu pluginów Wasm, która konsumuje łatki RFC 6902 adresowane wskaźnikami RFC 6901, opisuje plugins/plugin-contract.md.

Składnia komentarzy

Znaki komentarza zależą od otaczającego języka:

  • Kontekst YAML (domyślna powierzchnia tworzenia każdej encji Aggrega): należy używać #
  • Kontekst szablonów Go (wewnątrz skalarów blokowych valuesMapping: w encji Recipe, skalarów blokowych injectMapping: w encji FeatureRecipe, wpisów mapowań w encji MappingLibrary, treści assertions: w blokach asercji): należy używać {{/* ... */}} dla komentarzy szablonu, które silnik szablonów rozpoznaje i usuwa podczas renderowania, lub # dla komentarzy na poziomie YAML poza treścią szablonu.

Schematy w formie zwartej w schema:, usesSchema:, featuresSchema: i parameters: są w całości w YAML; adnotacja description: dla poszczególnych pól jest udokumentowaną powierzchnią do dokumentowania pól w miejscu (port: { type: integer, description: "TCP listen port" }).