Provider helm-chart
Provider helm-chart generuje spakowany parasolowy chart Helm (umbrella chart) dla każdej ścieżki złożenia. Podczas gdy provider helm emituje płaski YAML Kubernetes do bezpośredniego użycia w GitOps, helm-chart emituje szkielet chartu — parasolowy Chart.yaml + values.yaml oraz jeden sub-chart na każdy współtworzący węzeł — który narzędzia dalszego etapu mogą zainstalować przez helm install lub dołączyć do repozytorium w celu dalszego dostosowania do poszczególnych środowisk. Provider składa wynik dla każdej pary (path, provider): każdy węzeł powiązany z encją Recipe dla helm-chart wnosi swój wkład do chartu parasolowego w ścieżce będącej wynikiem połączenia obliczonego directory: granicy z subDirectory: danego komponentu. Dwie granice, których obliczona ścieżka jest taka sama, scalają się w jeden chart parasolowy, który wymienia każdy współtworzący element jako zależność typu sub-chart.
Szablony wykresu podrzędnego skopiowane z wykresu źródłowego niosą to, co zapisał ich autor: wartość syncWave: <integer> granicy, helm.sh/hook-weight na hooku i etykiety pochodzenia Aggrega trafiają do nich tylko tam, gdzie zapisuje je sam wykres. To provider helm nadaje argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" i etykiety pochodzenia każdemu renderowanemu zasobowi. Artefakt ładowany przez $import:, który ten provider dodaje do wykresu podrzędnego, niesie etykiety pochodzenia i adnotację argocd.argoproj.io/sync-wave, ale nie helm.sh/hook-weight (zob. „Reguła wstrzykiwania artifacts:” poniżej). ArgoCD odczytuje adnotację sync-wave, a Helm odczytuje wagę hooka.
Ta strona jest dokumentacją referencyjną dla autorów korzystających z providera helm-chart. Podział na helm i helm-chart opisuje sekcja Providers strony Status; model składania danych wejściowych wspólny dla providerów opisuje architecture/16-recipe-input-composition.md.
Obsługiwane rodzaje wejścia
Provider helm-chart przyjmuje dwa rodzaje danych wejściowych:
- Tryb ze źródłem. Encja Recipe z
source: <chart-path>wskazuje katalog chartu Helm na dysku. Chart jest kopiowany do struktury umbrella jako sub-chart, dosłownie, z wyjątkiem własnej nazwy chartu (name) — zob. „Nazwa chartu, którą przejmuje umbrella”; na poziomie pojedynczego węzła nie jest wykonywane żadne renderowanie ani szablonowanie. Rolą Aggrega jest kompozycja (składanie umbrella z węzłów granicy), a nie ewaluacja szablonów. - Tryb
artifacts:ładowanych przez$import:. Encja Recipe z wpisamiartifacts:zapisanymi jako$import:dla każdego wpisu deklaruje dodatkowe pliki szablonów, które provider helm-chart wstrzykuje do katalogutemplates/sub-chartu po skopiowaniu chartu źródłowego. Każdy plik jest wstępnie szablonowany względem kontekstu szablonów Aggrega z użyciem ograniczników[[ ]](zob. „Reguła wstrzykiwaniaartifacts:” poniżej), dzięki czemu szablonowanie Helm{{ }}w tym samym pliku przetrwa do późniejszego renderowania przezhelm install.
Encja Recipe kierowana do helm-chart, która deklaruje workload:, jest odrzucana przed renderowaniem, z tą samą odmową, jaką każdy provider zgłasza dla niezadeklarowanego przez siebie rodzaju wejścia — wskazuje ona rodzaj obsługiwany przez tego providera i kieruje autora do providera, który syntetyzuje:
provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (provider nie obsługuje rodzaju wejścia węzła (węzeł „api”). Provider „helm-chart” nie obsługuje syntetyzowanych recipes (ten provider obsługuje: sourced); należy zadeklarować jeden z obsługiwanych rodzajów wejścia albo wybrać jako cel providera obsługującego syntezę)
Ten podział jest celowy: synteza obciążeń (przekładanie abstrakcyjnej encji Workload na zasoby Kubernetes) należy wyłącznie do providera helm. Rolą helm-chart jest kompozycja umbrella + sub-chart dla chartów, które autor już przygotował.
Encja Recipe kierowana do helm-chart może też deklarować wpisy artifacts: z treścią inline (wpisy, których wartością jest skalar blokowy niosący treść pliku bezpośrednio w encji Recipe, a nie odwołanie ładowane przez $import:). Wpis z treścią inline trafia do katalogu głównego sub-chartu pod swoim zapisanym kluczem — bez prefiksu templates/ i bez wplatania pochodzenia. Własne szablony chartu odczytują taki luźny plik przez .Files.Get / .Files.Glob Helma (kanoniczny wzorzec ConfigMap z plików), więc plik w katalogu głównym chartu jest prawidłowym, pełnoprawnym kształtem, a nie błędem.
Obie formy są ewaluowane z ogranicznikami Aggrega [[ ]] przed umieszczeniem, więc treść w każdej z nich może odczytywać kontekst filarów encji Recipe; {{ }} w każdej z nich pozostaje nietknięte i staje się dyrektywą Helm w czasie późniejszego helm install. Formy różnią się tym, gdzie trafia plik i czy dołączane jest do niego pochodzenie:
- Wpis ładowany przez
$import:jest plikiem szablonu: po ewaluacji (zob. „Reguła wstrzykiwaniaartifacts:” poniżej) jest wstrzykiwany do katalogutemplates/sub-chartu z dołączonym pochodzeniem, więc Helm renderuje go jako manifest obok własnych szablonów chartu. - Wpis z treścią inline jest luźnym plikiem danych: po ewaluacji trafia do katalogu głównego chartu, bez zmian względem wyniku ewaluacji i bez dołączonego pochodzenia, do użycia przez
.Files.
Reguła wstrzykiwania artifacts:
Gdy Recipe dla helm-chart deklaruje wpisy artifacts: za pomocą $import: w poszczególnych wpisach, każda wartość $import: jest ścieżką do pliku szablonu rozwiązywaną względem własnego katalogu Recipe (katalogu zawierającego plik YAML encji Recipe na dysku). Provider:
- Odczytuje zawartość każdego pliku.
- Wstępnie przetwarza zawartość jako szablon z ogranicznikami Aggrega
[[ ]]względem kontekstu szablonów encji Recipe (tego samego kontekstu, względem którego wyliczane jestvaluesMapping:encji Recipe).{{ }}w zawartości pliku pozostaje nietknięte — staje się dyrektywami szablonów Helm w momenciehelm install. - Zapisuje każdy plik do
charts/<instance-id>/templates/<authored-key>pod ścieżką zestawienia umbrella; pliki pakietu są zagnieżdżane pod tym kluczem. Klucz, pod którym wpis został zapisany, nadaje nazwę plikowi; ścieżka$import:wybiera jego zawartość i nie wnosi niczego do nazwy, więc struktura katalogów w obrębie tej ścieżki nigdy nie trafia do wyniku.
Kluczowym szczegółem jest dyscyplina podwójnych ograniczników [[ ]] / {{ }}. Typowy plik artefaktu ładowany przez $import: może łączyć interpolację w czasie działania Aggrega (np. [[ .values.image ]]) z interpolacją w czasie działania Helm (np. {{ .Release.Namespace }}). Każda para ograniczników działa w swojej własnej fazie: Aggrega rozwiązuje [[ ]] w czasie kompilacji, zanim plik trafi na miejsce; Helm rozwiązuje {{ }} w czasie instalacji, po dostarczeniu umbrella.
Kolizje nazw plików między szablonami źródłowego charta a artefaktami wstrzykiwanymi przez $import: zgłaszają CATALOG_ERROR — diagnostyka wskazuje kolidującą ścieżkę wyjściową, na przykład templates/cm.yaml, oraz dwa rodzaje wejścia, które ją wytworzyły. Autorzy rozwiązują kolizję, zmieniając nazwę klucza artefaktu lub własnego szablonu charta.
Zestaw kluczy source:
Pole source: providera helm-chart wskazuje chart i przyjmuje oba kształty, jakie przyjmuje pole source:, odczytywane dokładnie tak, jak opisuje to zestaw kluczy source: providera helm: gołą ścieżkę w systemie plików w postaci łańcucha oraz obiekt strukturalny, którego url: zawiera lokalizację. Gdy url: wskazuje ścieżkę w systemie plików, nic nie jest pobierane, a chart jest odczytywany z dysku; gdy zawiera schemat transportu — na przykład oci://… z kind: helm-oci-chart — aggrega pull pobiera i przypina chart, a kompilacja kopiuje go z pamięci podręcznej do parasola jako sub-chart, na tych samych zasadach co chart odczytany z dysku.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Chart pod ścieżką źródłową musi zawierać poprawny plik Chart.yaml w katalogu głównym; jego brak powoduje czytelny błąd, zanim rozpocznie się kopiowanie. Układ katalogów chartu jest zachowywany podczas kopiowania — templates/, values.yaml, Chart.yaml i wszystkie inne pliki są obecne w katalogu sub-chartu po złożeniu. Każdy plik trafia na miejsce z bajtami w takiej postaci, w jakiej zostały zapisane, łącznie z komentarzami, kolejnością kluczy i cudzysłowami; jedynym wyjątkiem jest pole name we własnym pliku Chart.yaml chartu, które ustawia parasol — zob. „Nazwa chartu, którą zarządza parasol”.
Oba sposoby niewskazania chartu są odrzucane, a te dwa odrzucenia pochodzą z
różnych miejsc — warto o tym wiedzieć, ponieważ tylko jedno z nich zmienia się po zmianie
capability. Pole source:, które jest obecne, a mimo to niczego nie deklaruje, jest odrzucane przez
kompilator, zanim uruchomi się jakikolwiek provider, więc wynik jest taki sam niezależnie od tego,
które capability wskazuje encja Recipe; diagnostyka zaleca pominięcie pola w trybie
bez źródła lub podanie niepustej ścieżki. Całkowite pominięcie source: jest
poprawnym zapisem — w ten sposób encja Recipe żąda trybu bez źródła — i jest tu odrzucane,
ponieważ helm-chart deklaruje wyłącznie rodzaj wejścia ze źródłem, więc kompilator
odrzuca tę kombinację tym samym komunikatem, jaki podaje dla każdego capability, od którego żąda się
rodzaju wejścia, którego ono nie deklaruje. Własna dla helm-chart jest deklaracja, a nie
własne odrzucenie: dla zasobów Kubernetes generowanych z bloku workload:
należy zamiast tego użyć capability helm.
Encja Recipe deklarująca omits: jest odrzucana. Klucz omits:
pomija w kompilacji dokumenty renderowane przez źródło, a ten provider nie renderuje
żadnego dokumentu w czasie kompilacji: kopiuje chart do parasola, a szablony chartu
są renderowane podczas instalacji parasola. Skoro nic nie jest renderowane,
nie ma czego pomijać, więc ten provider nie deklaruje obsługi tego klucza, a
encja Recipe lub FeatureRecipe, która go deklaruje, jest odrzucana, zanim cokolwiek zostanie skopiowane — zob.
The provider does not support omits (Provider nie obsługuje pomijania).
W przypadku chartu przechowywanego obok encji Recipe wiersz w znajdującym się tam pliku .aggregaignore pomija
zamiast tego plik chartu, począwszy od następnego przypięcia encji Recipe; w przypadku pobranego
chartu, z którego wyniku musi zniknąć dokument, należy go renderować przez providera helm, który
obsługuje ten klucz.
Kompozycja według ścieżki — kształt wykresu parasolowego
Dostawca działa w dwóch fazach dla każdej ścieżki asemblacji:
- Kopiowanie dla każdego kontrybutora. Dla każdego węzła powiązanego z encją Recipe typu helm-chart dostawca kopiuje pełne drzewo katalogów źródłowego wykresu do miejsca na wykres podrzędny. Pliki trafiają płasko do mapy wyjściowej danego kontrybutora; asembler wskazuje
chartsjako podkatalog, w którym znajdują się jego kontrybutorzy, a orkiestrator przy składaniu wykresu parasolowego daje tam każdemu kontrybutorowi własny katalog —charts/<instance_id>/dla komponentu. Załącznik encji Feature również jest kontrybutorem — niezależnie od tego, czy dostarcza wykres, czy renderuje manifesty przez dostawcę helm — i otrzymuje katalog obok katalogu komponentu, a nie w jego wnętrzu; zob. „Gdzie trafia wykres załącznika”. - Asemblacja wykresu parasolowego dla każdej pary
(path, provider). Gdy wszystkie kopie dla węzłów danej ścieżki zostaną ukończone, asembler emituje parasolowe plikiChart.yaml+values.yamlw katalogu głównym ścieżki asemblacji. Wykres parasolowy deklaruje jedną zależność na każdy węzeł-kontrybutora i kieruje wartości poszczególnych węzłów do podbloków kluczowanych identyfikatorem instancji. Gdy ścieżka asemblacji otrzymuje kontrybutorów z więcej niż jednej granicy (granice ze wspólnymdirectory:), każdy kontrybutor trafia jako zależność do tego samego wykresu parasolowego.
Parasolowy plik Chart.yaml ma postać:
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: Aggrega umbrella chart for boundary "<assembly-path>"dependencies: - name: <encoded-instance-id> # the name the placed sub-chart carries version: <user-chart-version> # from the source chart's Chart.yaml alias: <encoded-instance-id> # see "How a name is derived" below repository: file://charts/<instance_id> # the sub-chart's own directoryRozstrzyganie nazwy wykresu
Wartość name wykresu parasolowego jest rozstrzygana przez kaskadę adnotacji granic. Efektywna adnotacja aggrega.ai/chart-name każdej granicy-kontrybutora (wartość rozstrzygnięta kaskadowo, w górę drzewa granic) określa nazwę wykresu parasolowego; rozstrzygnięta wartość jest kodowana dla pozycji nazwy wykresu dokładnie tak jak każda inna tożsamość, więc wartość zawierająca wyłącznie litery, cyfry, podkreślenia i łączniki, które zachowuje poniższa reguła, trafia do wykresu dosłownie. Gdy ścieżka asemblacji otrzymuje kontrybutorów z więcej niż jednej granicy, efektywna adnotacja aggrega.ai/chart-name każdego kontrybutora MUSI rozstrzygać się do tej samej wartości; niezgodności zatrzymują kompilację z diagnostyką wskazującą sprzeczne wartości i granice-kontrybutorów.
Kaskada w naturalny sposób rozwiązuje napięcie wokół zasady DRY: wystarczy zadeklarować aggrega.ai/chart-name raz na granicy nadrzędnej, a granice podrzędne dziedziczą ją przez kaskadę; granice równorzędne bez wspólnego rodzica muszą jawnie deklarować zgodne wartości. Granice, w których kaskadzie nigdzie nie zadeklarowano aggrega.ai/chart-name, przyjmują nazwę agregatu i ścieżkę zestawienia — katalog wyjściowy wykresu parasolowego w dist/, na przykład boundaries/data/helm-chart — każdą zakodowaną i połączoną w sposób opisany poniżej.
Wartość name każdego wpisu zależności to nazwa, którą nosi umieszczony wykres podrzędny — zakodowana tożsamość samej instancji komponentu, ta sama wartość co alias — z powodów opisanych w „Nazwa wykresu należąca do wykresu parasolowego”. Jego version to nadal wersja z pliku Chart.yaml samego wykresu źródłowego. Alias umieszcza wartości wykresu podrzędnego w zakresie values.yaml.<alias>.*, zgodnie z konwencją wartości wykresów parasolowych Helm, dzięki czemu wartości poszczególnych instancji propagują się poprawnie podczas instalacji wykresu parasolowego.
Katalog wykresu podrzędnego komponentu zachowuje instance_id dokładnie w postaci, w jakiej go zapisano, więc charts/<instance_id>/ to miejsce, do którego trafiają jego pliki, i to, na co wskazuje repository zależności. Dwie instancje tego samego wykresu źródłowego współistnieją więc bez kolizji w systemie plików, a każda zachowuje własny blok wartości pod własnym aliasem.
name zależności i jej repository to różne ciągi znaków, i jest to celowe. name to to, co DEKLARUJE wykres znajdujący się w tej lokalizacji, ponieważ Helm wiąże zależność z wykresem podrzędnym według nazwy zadeklarowanej przez sam ten wykres; repository to miejsce, w którym ten wykres się znajduje. W przypadku komponentu obie wartości wyglądają tak samo, ponieważ obie wywodzą się z tego samego identyfikatora instancji. W przypadku załącznika encji Feature różnią się — zadeklarowana nazwa zawiera złożoną tożsamość załącznika, a katalog jego dwie połączone współrzędne — więc odczytanie jednej jako drugiej wskazuje coś, czego nie ma.
Gdzie trafia wykres załącznika
Załącznik encji Feature, który dostarcza wykres, otrzymuje własny katalog obok komponentu, do którego jest dołączony, jeden poziom pod charts/:
charts/├── api/ # the component's own chart├── api--guardrail/ # a Feature attached to `api` under `guardrail`└── api--audit/ # a second Feature attached to the same componentEncja Feature dołączona do granicy, a nie do komponentu, nie ma komponentu-hosta do wskazania, więc jej katalogiem jest sama nazwa instancji: charts/aux/.
Dlaczego obok, a nie wewnątrz. Helm wykrywa wykres podrzędny w charts/* — na jednym poziomie, bez rekurencyjnego przeszukiwania. Wykres umieszczony głębiej nie jest niczyim wykresem podrzędnym; jest danymi w katalogu innego wykresu podrzędnego, dostępnymi tylko przez .Files. Wykres umieszczony wewnątrz katalogu wykresu samego komponentu zostałby więc skopiowany do wyniku, kompilacja zakończyłaby się sukcesem, a do wdrożenia nie trafiłby żaden z jego zasobów — i nic by tego nie zgłosiło. To umieszczenie każdego kontrybutora we własnym katalogu najwyższego poziomu sprawia, że zasoby załącznika są renderowane.
Wykres parasolowy deklaruje też załącznik jako jedną ze swoich zależności. Potrzebne są obie części: wykres obecny w charts/, a nieobecny w dependencies: to błąd lintera, a wykres zadeklarowany w dependencies: bez obecnego pasującego wykresu podrzędnego sprawia, że wykres parasolowy odmawia załadowania.
Dwie współrzędne są łączone, a nie sklejane. Nazwa katalogu jest składana z hosta i instancji za pomocą tej samej reguły ucieczki opisanej poniżej, stosowanej do każdej współrzędnej przed połączeniem ich przez --. Bezpośrednie sklejenie ich przez -- byłoby niejednoznaczne: host o nazwie a--b z instancją c oraz host a z instancją b--c trafiłyby do jednego katalogu. Wcześniejsze zakodowanie każdej współrzędnej rozdziela je, więc zapisane -- wewnątrz współrzędnej pojawia się jako -zh-.
Co dopuszcza nazwa katalogu. Litery ASCII obu wielkości, cyfry, kropka i podkreślenie przechodzą bez zmian, więc API--aux i web.api--aux wyglądają zgodnie z oczekiwaniami. Zapisany łącznik jest zachowywany wszędzie tam, gdzie następny znak należy do tego zbioru, więc web-api--aux pozostaje bez zmian; podwójny łącznik podlega ucieczce, ponieważ ta para jest złączem. Wszystko inne podlega ucieczce według tej samej reguły co nazwa wykresu. Zbiór wyznaczono w ten sposób, ponieważ te nazwy katalogów są zarówno ścieżkami na dysku, jak i lokalizacją, do której rozstrzyga się wskaźnik file:// zależności, a znak dopuszczalny w nazwie pliku może obciąć lub ponownie zdekodować adres URL.
Wartości podążają za zadeklarowaną nazwą, a nie za katalogiem. Wartości wykresu podrzędnego są objęte zakresem nazwy deklarowanej przez ten wykres, więc wartości dla powyższego wykresu adresuje się zadeklarowaną nazwą api--guardrail — cfr-zh-api-zh-guardrail — a nie jego katalogiem.
Tego klucza nigdy nie zapisuje się samodzielnie. Wartości zapisuje się na załączniku, a values.yaml wykresu parasolowego jest składany automatycznie, z blokiem już pod adresem, pod którym adresowany jest umieszczony wykres. Dla encji Feature dołączonej do komponentu są to values: deklarowane na załączniku, odczytywane przez własne valuesMapping: encji FeatureRecipe; dla encji Feature dołączonej do granicy jest to infra: deklarowane w tym miejscu, ponieważ encja Feature dołączona do granicy nie ma filaru wartości komponentu. W każdym przypadku mapa, do której rozstrzyga się valuesMapping:, staje się własnym blokiem załącznika w wykresie parasolowym:
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"To jedyna droga tych wartości. Wykres dostarczany przez encję Feature trafia z plikami w postaci nadanej przez jego autora — z wyjątkiem jednego pola manifestu opisanego w „Nazwa wykresu należąca do wykresu parasolowego” — więc nic nie zapisuje wartości w tym wykresie, a dostarcza je blok wykresu parasolowego. Wykres, do którego blok nigdy nie dotarł, nie jest uszkodzony: renderuje wartości domyślne z własnego values.yaml i zgłasza sukces, dlatego aby podczas tworzenia zauważyć różnicę, warto nadać wartości domyślnej wartość łatwą do rozpoznania.
Załącznik, którego encja FeatureRecipe renderuje przez dostawcę helm
Encja FeatureRecipe o capability helm dołączona do komponentu w tym celu wnosi gotowe manifesty Kubernetes zamiast wykresu. Trafiają one do własnego katalogu załącznika dokładnie w takiej postaci, w jakiej wyrenderował je dostawca helm, a dostawca nadaje temu katalogowi dwie rzeczy, które czynią z niego wykres instalowany przez Helm: minimalny Chart.yaml, deklarujący własną nazwę załącznika w wersji 0.1.0, oraz jeden szablon, templates/rendered.yaml, który emituje każdy wyrenderowany plik YAML przez .Files.Get Helma po jego nazwie:
charts/api--guardrail/├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0├── guardrail-config.yaml # the manifest the helm provider rendered└── templates/ └── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}Zadeklarowana nazwa to ta, którą zadeklarowałby wykres dostarczony przez ten sam załącznik, więc wpis zależności wykresu parasolowego i jego blok wartości są adresowane dokładnie tak, jak opisano powyżej. .Files.Get zwraca bajty pliku bez zmian, nie wyliczając ich po raz drugi, więc manifest zawierający dosłowne nawiasy klamrowe szablonów — {{ $labels.instance }} reguły alertu, zapytanie dashboardu — instaluje się z nimi nienaruszonymi. Jego wartości zostały rozwiązane w tych manifestach, gdy renderował je dostawca helm, więc blok, który values.yaml wykresu parasolowego niesie pod tą nazwą, nie jest przez nic odczytywany.
Nazwa wykresu należąca do wykresu parasolowego
Jedyne, co Aggrega zmienia wewnątrz dostarczonego wykresu, to własne pole name tego wykresu. W pliku Chart.yaml umieszczonego wykresu name jest ustawiane na zakodowaną tożsamość tego, co wniosło ten wykres.
W przypadku komponentu jest to tożsamość samej instancji komponentu — ta sama wartość co alias zależności — a wpis zależności w wykresie parasolowym również wskazuje tę wartość, więc obie strony zawsze są zgodne.
Wykres dostarczany przez załącznik encji Feature jest samodzielnym kontrybutorem i deklaruje własną tożsamość, zamiast powtarzać tożsamość komponentu, do którego jest dołączony. Ta tożsamość jest składana z dwóch zapisanych elementów — komponentu będącego hostem załącznika oraz nazwy, pod którą dołączono encję Feature — poprzedzonych krótkim prefiksem oznaczającym ją jako tożsamość załącznika, a nie komponentu; złożona wartość jest następnie zapisywana dla pozycji nazwy wykresu za pomocą opisanego poniżej wyprowadzenia, dokładnie tak jak każda inna tożsamość.
Dołączenie encji Feature dostarczającej wykres do komponentu o nazwie api pod nazwą guardrail umieszcza więc wykres deklarujący cfr-zh-api-zh-guardrail, podczas gdy własny wykres tego komponentu nadal deklaruje api. Są to dwaj odrębni kontrybutorzy i każdy deklaruje własną nazwę, zamiast obu deklarować nazwę hosta.
Nic innego w wykresie nie jest modyfikowane. Każdy inny plik trafia bajt w bajt w zapisanej postaci, a wewnątrz Chart.yaml każde inne pole, każdy komentarz, kolejność kluczy i cudzysłowy pozostają dokładnie takie, jak je zapisano. Klucz zagnieżdżony w innym miejscu manifestu, który również nazywa się name — na przykład nazwisko opiekuna — pozostaje nietknięty.
Dlaczego wykres parasolowy potrzebuje tego pola. name wykresu to to, z czym Helm wiąże zależność wykresu parasolowego. Zapisuje je autor wykresu, którym w przypadku wykresu pozyskanego z upstreamu nie jest osoba go wdrażająca — dlatego dwa komponenty w jednej ścieżce asemblacji mogą całkiem zasadnie dostarczać wykresy, których manifesty deklarują tę samą nazwę. Gdyby oba wykresy podrzędne zachowały tę wspólną nazwę, obie zależności wykresu parasolowego rozstrzygałyby się do tego z dwóch wykresów, który Helm załadowałby jako pierwszy: wykres jednego komponentu zostałby wyrenderowany dwukrotnie, a drugiego wcale, choć wartości każdego komponentu nadal by docierały, więc wynik wyglądałby na kompletny i byłby błędny. Wyprowadzenie nazwy umieszczonego wykresu z instancji komponentu całkowicie usuwa wspólną nazwę, dlatego niczego nie trzeba odrzucać — także w dwóch przypadkach, które nie mają innego rozwiązania: dostarczenia tego samego wykresu dla dwóch komponentów, gdzie nazwa jest wspólna z samej konstrukcji, oraz dostarczenia wykresu, którego nie jest się autorem, a którego nazwy nie można zmienić.
Jedyny obserwowalny efekt. Szablon odczytujący nazwę własnego wykresu — {{ .Chart.Name }} i wszystko, co z niej wyprowadzono, np. popularny idiom nazewnictwa zasobów {{ .Chart.Name }}-{{ .Release.Name }} — odczytuje zakodowaną tożsamość instancji, a nie nazwę zapisaną w pliku Chart.yaml wykresu źródłowego. Taki szablon odczytywał to już przed ustawieniem pola, ponieważ Helm raportuje wykres podrzędny pod aliasem, którym wiąże go wykres nadrzędny; ustawienie pola sprawia, że plik na dysku zgadza się z tym, co renderowanie już dawało. W poniższym przykładzie szablon w wykresie podrzędnym api-east odczytuje więc api-east.
Jeśli nazwa zasobu musi zawierać nazwę nadaną wykresowi przez autora, należy umieścić tę nazwę w pliku values.yaml wykresu i odczytywać ją stamtąd — wartość należy do autora i Aggrega jej nie modyfikuje.
Jak wyprowadzana jest nazwa
Nazwa wykresu Helm i alias zależności Helm akceptują węższy zbiór znaków niż ten, który może zawierać nazwa agregatu, ścieżka granicy lub instance_id. Zamiast zastępować znak nieakceptowany przez cel, wyprowadzenie zapisuje go w postaci rozwiniętej, dzięki czemu dwie tożsamości różniące się wyłącznie interpunkcją zawsze dają dwie nazwy — a wartość zapisana pod jednym aliasem może trafić wyłącznie do wykresu podrzędnego wskazywanego przez ten alias.
- Litera, cyfra i podkreślenie są przenoszone dokładnie w zapisanej postaci.
- Łącznik jest zachowywany w zapisanej postaci wszędzie tam, gdzie następny znak jest przenoszony bezpośrednio i nie jest małą literą
z. Łącznik, po którym następuje mała literaz, otwiera sekwencję ucieczki, więc zapisany łącznik w tej pozycji sam jest zapisywany w postaci rozwiniętej —api-zonestaje sięapi-zhzone, co pozwala odczytać dowolną nazwę bez zgadywania. - Każdy inny znak jest zapisywany jako
-z, po którym następuje litera go oznaczająca:ddla kropki,sdla separatora ścieżki,hdla łącznika, którego powyższa reguła nie zachowuje. Wszystko inne jest zapisywane jakoxi sześciocyfrowy szesnastkowy punkt kodowy znaku, a bajt, który nie rozpoczyna żadnego znaku, jakobi jego własna dwucyfrowa wartość — dzięki temu nazwa niebędąca poprawnym tekstem nadal jest zapisywana w sposób odróżnialny, a nie zwijana. - Pusta wartość jest zapisywana jako
-ze, czego żadna niepusta wartość nie może dać. - Gdy dwie tożsamości składają się na jedną nazwę wykresu — nazwa agregatu kwalifikująca ścieżkę zestawienia — są łączone przez
--. Pojedyncza zakodowana tożsamość nigdy nie zawiera tej pary, więc połączona nazwa jednoznacznie wskazuje, która tożsamość jest którą.
Zatem instance_id data.main-db daje alias data-zdmain-db, a agregat fullstack-app ze ścieżką zestawienia boundaries/data/helm-chart daje nazwę wykresu fullstack-app--boundaries-zsdata-zshelm-chart. Identyczne dane wejściowe zawsze dają identyczną nazwę.
Parasolowy plik values.yaml jest kluczowany aliasem:
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2Gdy valuesMapping: wykresu podrzędnego jest ewaluowane względem jego kontekstu szablonów, wynikowa mapa wartości automatycznie wypełnia ten podblok kluczowany aliasem. Dotyczy to każdego kontrybutora wykresu parasolowego, nie tylko komponentów: załącznik encji Feature, który dostarcza wykres, jest samodzielnym kontrybutorem, więc valuesMapping: jego encji FeatureRecipe wypełnia własny blok, kluczowany nazwą deklarowaną przez umieszczony wykres. Zob. „Gdzie trafia wykres załącznika”.
Klucz, który valuesMapping: ustawia na null, jest zapisywany w swoim bloku jako null. Przy instalacji za pomocą Helm 4 wartość null we własnym values.yaml wykresu parasolowego usuwa wartość domyślną wykresu podrzędnego dla tego klucza tylko wtedy, gdy instalacja dostarcza również wartości dla tego wykresu podrzędnego; instalacja, która nie dostarcza dla niego żadnych, pomija null i obowiązuje wartość domyślna wykresu podrzędnego. null w wartościach przekazanych do helm install usuwa wartość domyślną w obu przypadkach.
Osobliwości specyficzne dla Provider
- Plik
Chart.yamlpodchartu jest wymagany. Operacja kopiowania wymusza obecność plikuChart.yamlw katalogu głównym ścieżki źródłowej. Jego brak zatrzymuje kompilację, zanim zostanie uruchomiony krok umbrella. - Pole
nameumieszczonego chartu należy do umbrelli. Jest ustawiane na zakodowaną tożsamość tego, co dostarczyło chart — własną tożsamość instancji komponentu lub, w przypadku chartu wnoszonego przez dołączenie encji Feature, własną tożsamość tego dołączenia — i jest to jedyna rzecz wewnątrz dołączonego chartu, którą Aggrega zmienia. Zob. „Nazwa chartu, do której prawo ma umbrella”. - Chart źródłowy musi deklarować wersję i nazwę. Wersja wpisu zależności to ta, którą deklaruje własny plik
Chart.yamlchartu źródłowego, więc chart niedeklarujący wersji zatrzymuje kompilację, zamiast otrzymać jakąś wersję — zależność przypięta do wersji, której podchart nie ma, sprawiłaby, że wartości umbrelli przypisane do poszczególnych instancji nie mogłyby do niego dotrzeć. Chart, którego plikChart.yamlnie deklaruje nazwy, zawiera więcej niż jeden dokument YAML lub nie daje się sparsować, zatrzymuje kompilację z tego samego powodu: umbrella nie może złożyć podchartu, którego nie potrafi odczytać. - Zakodowane aliasy i nazwy chartów. Identyfikator instance_id, nazwa agregatu lub ścieżka granicy zawierające znak, którego nie akceptuje nazwa chartu Helm ani alias zależności, pojawiają się w wyrenderowanej umbrelli w postaci zakodowanej, zgodnie z sekcją „Jak wyprowadzana jest nazwa” powyżej. Tożsamość zbudowana wyłącznie z liter, cyfr, podkreśleń i łączników zachowywanych przez wyprowadzenie pojawia się dokładnie w postaci, w jakiej została zapisana.
- Wskaźnik repozytorium
file://. Wpisy zależności umbrelli używają wskaźnika repozytoriumfile://wskazującego własny katalog chartu podrzędnego —file://charts/<instance_id>dla komponentu oraz własny katalog dołączenia dla chartu wnoszonego przez encję Feature. Jest to konwencja lokalnego systemu plików dla chartów podrzędnych w drzewie, która pozwala poleceniuhelm dependency buildrozwiązać umbrellę bez wywołań zewnętrznego rejestru. Wskaźnik wskazuje lokalizację, a nigdy zadeklarowaną nazwę chartu; w przypadku dołączenia te dwie wartości się różnią, a tohelm dependency buildjest krokiem, który odrzuca wskaźnik do nieistniejącego katalogu. - Brak renderowania szablonów na poziomie helm-chart. Dostawca nie wywołuje potoku renderowania Helm SDK; kopiuje i składa. Autorzy potrzebujący wstępnie wyrenderowanych płaskich manifestów powinni zamiast tego użyć trybu źródłowego dostawcy helm.
Przykład praktyczny
Granica z dwoma węzłami, z których każdy jest powiązany z encją Recipe typu helm-chart wskazującą ten sam chart źródłowy:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Po kompozycji obliczona ścieżka montażu granicy (domyślnie dist/<boundary-directory>/<capability>/, ponieważ subDirectory: ma domyślnie wartość {{ .capability }}) zawiera:
dist/<boundary-directory>/helm-chart/├── Chart.yaml # umbrella; lists api-east and api-west as dependencies├── values.yaml # alias-keyed: api-east + api-west values blocks└── charts/ ├── api-east/ # ./charts/api-server, name: api-east │ ├── Chart.yaml │ ├── values.yaml │ └── templates/ │ └── deployment.yaml └── api-west/ # ./charts/api-server, name: api-west ├── Chart.yaml ├── values.yaml └── templates/ └── deployment.yamlOba sub-charty są kopiami tego samego chartu źródłowego i każdy z nich zawiera w swoim pliku Chart.yaml nazwę własnej instancji — dzięki temu jeden chart można dołączyć dwukrotnie do jednego chartu parasolowego. Cała reszta obu kopii jest identyczna ze źródłem.
Polecenie helm install <release-name> dist/<boundary-directory>/helm-chart wykonane na tym układzie instaluje obie instancje jako pojedyncze wydanie Helm, przy czym wartości chartu parasolowego, kluczowane aliasami, sterują szablonami każdego sub-chartu.
Odsyłacze
providers/helm.md— siostrzany provider, który emituje płaski, wyrenderowany YAML Kubernetes zamiast szkieletu chartu; obsługuje syntezę workloadów.entities/recipe.md— sposób tworzenia encji Recipe i trzy rodzaje wejścia.entities/release.md— semantyka granicy encji Release i katalogi wyjściowe poszczególnych granic.architecture/16-recipe-input-composition.md— macierz możliwości (Provider Capability Matrix) obejmująca wszystkie providery.10-status.md#providers— bieżąca klasyfikacja gotowości.