MappingLibrary
MappingLibrary to encja katalogu przechowująca fragmenty szablonów Go wielokrotnego użytku. Encje Recipes i FeatureRecipes, które współdzielą cały dokument valuesMapping: — wartości, które kilka encji Recipes korzystających z tego samego chartu jako źródła przekazuje mu każda z osobna — deklarują go raz w bibliotece i odwołują się do niego w momencie użycia za pomocą dyrektywy valuesMapping: { $import: ... }. Encja biblioteki należy do poziomu 3: jest opcjonalna, dla katalogów, które potrzebują ponownego wykorzystania mapowań między encjami Recipe. Katalogi bez powtarzającej się treści szablonów obywają się bez żadnej encji MappingLibrary.
Rola encji MappingLibrary
Architekci platformy tworzą encje MappingLibraries, aby scentralizować fragmenty szablonów Go, które powtarzają się w encjach Recipes i FeatureRecipes katalogu. Biblioteka nie jest wdrażalną instrukcją budowania; jest przestrzenią nazw definicji. Autorzy encji Recipe i FeatureRecipe odwołują się do wpisów biblioteki za pomocą dyrektywy $import:, zapisanej raz i używanej wszędzie tam, gdzie import zostaje rozwiązany.
Podział na „bibliotekę” i „konsumenta” jest zamierzony. Encje Recipes kodują instrukcje budowania (source, valuesMapping, artifacts). Encje FeatureRecipes kodują dołączane zachowania. Encje MappingLibraries kodują wyłącznie fragmenty szablonów — treść szablonów Go, którą inne encje wykorzystują w czasie renderowania. Rozdzielenie tych trzech ról pozwala każdemu rodzajowi encji rozwijać się we własnym tempie; autorzy, którzy nie potrzebują współdzielonej treści szablonów, nigdy nie mają do czynienia z encją biblioteki.
Koperta encji
Encja MappingLibrary ma standardową kopertę katalogu. apiVersion: aggrega.ai/v1beta1 i kind: MappingLibrary oznaczają rodzaj encji; metadata.name jest identyfikatorem w notacji PascalCase; metadata.version stosuje ścisłe wersjonowanie semantyczne. Zawartość biblioteki znajduje się pod spec.mappings — wymaganą mapą, która musi deklarować co najmniej jeden wpis.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Wpis jest ewaluowany przez własny silnik szablonów korzystającej z niego encji Recipe, w kontekście renderowania tej encji Recipe, więc odczytuje te same filary pisane małymi literami, które odczytuje własne valuesMapping: encji Recipe — .values, .infra, .context i pozostałe — i używa tych samych funkcji, takich jak uwzględniający obecność pomocnik optional dla nieobecnego klucza. .Values, zapis Helma dla wartości chartu, nie jest korzeniem definiowanym przez ten kontekst: wpis, który go odczytuje, zatrzymuje kompilację, wskazując odwołanie.
Tworzenie wpisów mapowania
Każdy wpis mapowania to fragment szablonu Go zapisany jako łańcuch YAML. Fragment jest nieprzezroczysty dla koperty encji — kompilator przechowuje łańcuch dosłownie podczas ładowania encji MappingLibrary i parsuje go w chwili użycia, gdy encja Recipe lub FeatureRecipe importuje wpis przez valuesMapping: { $import: ... }. Import zastępuje całe valuesMapping: encji Recipe — mapa $import: nie zawiera innych kluczy — więc wpis jest kompletnym dokumentem wartości, a nie fragmentem wklejanym do niego.
Krótkie fragmenty mieszczą się w jednym wierszu:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Fragmenty wielowierszowe używają skalara YAML w stylu dosłownym (|), dzięki czemu znaki nowego wiersza i wcięcia zachowują się w obie strony:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}Wewnątrz fragmentów dostępny jest pełny słownik kompozycji szablonów Go: {{ define "name" }}...{{ end }} deklaruje bloki wielokrotnego użytku w obrębie jednej biblioteki; {{ template "name" . }} je wywołuje; potoki i funkcje są obsługiwane zgodnie ze standardowym pakietem Go text/template.
Jeden tryb tworzenia
MappingLibrary udostępnia jeden tryb tworzenia: szablony Go. spec nie przyjmuje równoległej powierzchni tworzenia i nie ma furtki zwiększającej ekspresywność na poziomie biblioteki.
Powodem jest jednolitość powierzchni użycia. Recipes i FeatureRecipes w całości opierają się na szablonach Go, a ich własna treść jest ewaluowana przez ten sam silnik szablonów Go, który rozwiązuje importowany wpis, więc wpis czyta się dokładnie tak jak własny tekst encji Recipe, a autorzy uczą się jednego modelu ewaluacji. Słownictwo kompozycji szablonów Go — {{ define }} i {{ template }} w obrębie biblioteki oraz dyrektywa $import: w momencie użycia — zapewnia bloki wielokrotnego użytku i sparametryzowane wywołania, których potrzebuje biblioteka.
Autorzy potrzebujący ekspresywności wykraczającej poza to, co oferuje słownictwo kompozycji szablonów Go, komponują na wyższym poziomie — za pomocą encji Components lub Features, które opakowują wpisy biblioteki własną, merytoryczną zmiennością — zamiast sięgać po równoległy język tworzenia wewnątrz samej encji MappingLibrary.
Konwencje nazewnictwa
Nazwy bibliotek i klucze wpisów mapowań stosują PascalCase. JSON Schema koperty encji wymusza tę konwencję w dwóch miejscach za pomocą ograniczeń wzorca:
metadata.namepasuje do^[A-Z][A-Za-z0-9]*$.- Klucze mapy
spec.mappingspasują do tego samego wzorca za pośrednictwempropertyNames.
Encja MappingLibrary z kluczem w spec.mappings niezgodnym z PascalCase nie przechodzi walidacji koperty podczas ładowania przestrzeni roboczej. To wymuszenie ma istotne znaczenie: klucze wpisów mapowań pojawiają się we fragmencie odwołania #/mappings/<name>; klucze niezgodne z PascalCase rozprzestrzeniałyby się przez każdego konsumenta importującego dany wpis.
Jednolite nazewnictwo zapewnia czytelność fragmentu #/mappings/<name>: #/mappings/ProbeBlock jest zrozumiałe na pierwszy rzut oka.
Odwoływanie się do wpisów biblioteki
Autorzy encji Recipe i FeatureRecipe odwołują się do wpisu mapowania wewnątrz bloku valuesMapping: { $import: ... } za pomocą jego tożsamości opartej na samej nazwie:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"Fragment #/mappings/<name> wybiera wpis i odróżnia odwołanie do mapowania od fragmentu #/schemas/<name> encji SchemaLibrary. Odwołanie korzysta z tego samego modelu tożsamości opartej na samej nazwie co $ref: w SchemaLibrary — <Library>#/mappings/<name>, bez hosta rejestru. Wersję dostarcza plik blokady danej encji Release (nazwa + wersja + skrót treści); autor może zadeklarować opcjonalną minimalną wersję jako <Library>:<version>#/mappings/<name> (separatorem wersji jest :, zgodnie z mapowaniami recipe/feature i przypięciem w pliku blokady), a fizyczna lokalizacja jest wiązana w momencie rozwiązywania.
Kompozycja między bibliotekami
Wpis encji MappingLibrary może być przekierowaniem $import: na poziomie korzenia pola: pierwszym tokenem jego treści jest $import: <Library>#/mappings/<entry>, co zastępuje cały wpis zawartością wpisu, do którego się odwołuje — jest to ponowne użycie przez tożsamość, a nie szablonowanie w miejscu. Przekierowanie jest rozwiązywane w momencie konsumpcji (podczas renderowania encji Recipe), a nie przy ładowaniu encji MappingLibrary, i to rekurencyjnie — importowany wpis sam może być przekierowaniem $import: na poziomie korzenia pola. $import: działa wyłącznie na całych wpisach; nie jest funkcją szablonu używaną w środku fragmentu. Aby składać tekst szablonu wewnątrz pojedynczego fragmentu, należy użyć szablonów Go define / template.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsBiblioteki mogą swobodnie odwoływać się do siebie nawzajem. Łańcuch, który zapętla się sam na siebie, zatrzymuje się, gdy renderuje się korzystająca z niego encja Recipe, z diagnostyką wskazującą każdy krok cyklu.
Umiejscowienie w poziomach
MappingLibrary należy do poziomu 3 w modelu dokumentacji poziomów encji — jest opcjonalna, przeznaczona dla katalogów, które potrzebują ponownego użycia mapowań między encjami Recipe. Katalogi bez powtarzającej się treści szablonów nie zawierają żadnej encji MappingLibrary; oznaczenie poziomu sygnalizuje „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji po dokumentacji, a nie możliwości. Kompilator traktuje MappingLibrary jednakowo z pozostałymi rodzajami encji katalogu: ta sama walidacja koperty przy ładowaniu przestrzeni roboczej, ten sam potok publikacji OCI w czasie wydania.
Ten rodzaj biblioteki naturalnie łączy się z SchemaLibrary na poziomie katalogu — SchemaLibrary przechowuje definicje schematów wielokrotnego użytku; MappingLibrary przechowuje fragmenty szablonów wielokrotnego użytku. Katalogi, które potrzebują obu, zawierają obie; katalogi, które nie potrzebują żadnej, nie zawierają żadnej.
Czym MappingLibrary nie jest
Kilka częstych nieporozumień, którym warto zapobiec:
-
Nie zastępuje wbudowanego
valuesMapping:. Większość encji Recipes zawiera prostą treśćvaluesMapping:, którą najlepiej tworzyć bezpośrednio na miejscu — encja Recipe pozostaje samowystarczalna, a autor czyta treść mapowania razem z resztą encji Recipe. MappingLibrary pomaga wtedy, gdy TEN SAM fragment pojawia się w wielu encjach Recipes; w przypadku jednorazowych mapowań właściwym wyborem jest tworzenie ich na miejscu. -
Nie jest miejscem na treść schematów. Definicje schematów (JSON Schema 2020-12) należą do encji SchemaLibrary; fragmenty szablonów należą tutaj. Rodzaje bibliotek dzielą się według typu treści, a nie według wzorca ponownego użycia.
-
Nie zapewnia parametrycznego ponownego użycia wykraczającego poza mechanizmy szablonów Go. Autorzy potrzebujący zmienności parametrycznej używają w wpisach biblioteki mechanizmów
{{ define }}+{{ template arg }}szablonów Go albo komponują encje Components / Features, które opakowują wpisy biblioteki własną zmiennością. Sama encja biblioteki nie dostarcza żadnych mechanizmów pomocników parametrycznych (brak blokutemplatesanalogicznego do pomocników parametrycznychspec.templatesencji SchemaLibrary); słownictwo kompozycji szablonów Go pokrywa ten sam przypadek użycia.