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

Helm Provider

Provider helm generuje płaski, wyrenderowany YAML Kubernetes dla odbiorców GitOps (ArgoCD, Flux). Provider składa wynik per (path, provider): wyrenderowany YAML każdego węzła kierowanego do helm trafia do asemblera wyznaczonego przez obliczony directory: granicy połączony z subDirectory: danego komponentu, a ten asembler emituje jeden plik YAML na każdy zasób Kubernetes. Narzędzia niższego rzędu porównują i stosują pliki bezpośrednio, bez kroku instalacji Helm.

Gdy syncWave: <integer> granicy jest różne od 0, każdy emitowany zasób Kubernetes przenosi tę wartość jako adnotację argocd.argoproj.io/sync-wave: "<N>"; hooki Helm dodatkowo przenoszą helm.sh/hook-weight: "<N>". ArgoCD odczytuje adnotację sync-wave, a Helm wagę hooka, i każde z nich porządkuje według niej zasoby; granica z domyślną falą 0 nie przenosi żadnej z nich, co oba narzędzia odczytują jako falę 0.

Ta strona jest dokumentacją referencyjną dla autorów korzystających z providera helm. Model kompozycji wejść wspólny dla providerów opisuje architecture/16-recipe-input-composition.md. Gotowość każdego providera opisuje Status języka → Providers.

Obsługiwane rodzaje wejścia

Provider helm przyjmuje wszystkie trzy rodzaje wejścia encji Recipe, w różnych rolach:

  • Tryb ze źródłem. Encja Recipe z source: <chart-path> wskazuje katalog chartu Helm na dysku. Helm Go SDK wczytuje chart, słownik wartości renderowania bazowego jest scalany z wartościami domyślnymi chartu, a szablony chartu renderują się do płaskiego YAML Kubernetes.
  • Tryb Workload (syntetyzowany). Encja Recipe z workload: (wbudowanym lub wczytanym przez $import:) deklaruje dokument Workload. Provider syntetyzuje jeden lub więcej zasobów Kubernetes na węzeł — obiekt kontrolera wybrany przez form encji Workload oraz obiekty Service dla każdej usługi i PVC dla każdego trwałego wolumenu — bezpośrednio ze specyfikacji Workload; zob. Tryb Workload (syntetyzowany).
  • Tryb wyłącznie artefaktów. Encja Recipe z artifacts:, bez source: i bez workload:, emituje manifesty napisane przez autora, z etykietami i adnotacjami pochodzenia kompilacji wplecionymi we własne metadane każdego zasobu.

Te trzy tryby łączą się: encja Recipe może zadeklarować jednocześnie chart, Workload i artifacts:, a każde z nich renderuje się i jest emitowane samodzielnie, obok siebie w wyjściu węzła — zob. Co dokładnie przyjmuje każdy provider.

Zestaw kluczy source:

Pole source: providera helm wskazuje chart i przyjmuje oba kształty, jakie może mieć pole source:: goły ciąg ze ścieżką systemu plików oraz obiekt strukturalny, którego url: niesie lokalizację. Wszędzie tam, gdzie ta lokalizacja jest ścieżką systemu plików, jest ona zakotwiczona w katalogu zawierającym recipe.yaml, który ją deklaruje, a nie w katalogu, z którego wywołano build, i musi pozostać wewnątrz tego katalogu: ścieżka, która z niego wychodzi, lub ścieżka bezwzględna jest odrzucana, ponieważ każdy plik, który niesie publikacja encji Recipe, pochodzi z jej katalogu — zob. entities/recipe.md „Content paths stay inside the Recipe’s own directory”. Chart wskazany w ten sposób jest publikowany razem z encją Recipe, wraz z każdym plikiem pod nim, który zachowują reguły ignorowania zapisane w chwili przypięcia encji Recipe — provider helm pomija katalogi systemu kontroli wersji oraz pliki ukryte w katalogu templates/ chartu, respektuje własny plik .helmignore chartu, a ostatnie słowo ma plik .aggregaignore autora, jak opisuje Which files ship with an entity — natomiast plik leżący obok encji Recipe, którego nie wskazuje nic, co ona deklaruje, nie jest publikowany. Renderowanie odczytuje te same pliki, które niesie publikacja, więc chart renderuje się tak samo z lokalnego katalogu i z rejestru. Kształt, w jakim zapisano pole, tego nie zmienia: strukturalne source:, którego url: to ./charts/api-server, jest zakotwiczone dokładnie tak samo jak goły ciąg ./charts/api-server.

spec:
capability: helm
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicas: {{ optional .infra `replicas` 2 }}

Strukturalne source: wyraża to samo za pomocą nazwanych pól, a to, co niesie jego url:, decyduje, czy cokolwiek jest pobierane. Gdy url: zawiera schemat transportu — oci://… dla chartu OCI, https://….tgz dla bezpośredniego archiwum chartu lub korzeń repozytorium https:// w parze z chart: — chart jest pobierany: rodzaj wynika ze schematu URL lub z jawnego kind:, aggrega pull pobiera chart i przypina go w pliku blokady, a build wypakowuje go z pamięci podręcznej. Gdy url: wskazuje ścieżkę systemu plików, nic nie jest pobierane ani przypinane — chart jest odczytywany z dysku i zakotwiczony dokładnie tak jak w formie gołego ciągu opisanej wyżej.

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

Tylko url: decyduje, skąd odczytywany jest chart. Pozostałe pola wybierają to, co byłoby pobierane, więc w przypadku ścieżki nie wybierają niczego — nadal trafiają jednak do własnych szablonów encji Recipe jako .source.*.

Lokalne vendorowanie chartu jest obsługiwane jako alternatywa dla pobierania i nie jest wymagane. Schemat akceptuje otwarty obiekt strukturalny.

Chart pod ścieżką źródłową musi zawierać poprawny plik Chart.yaml. Renderowania źródłowe, którym nie uda się wczytać chartu, zgłaszają dosłownie pierwotny błąd Helm SDK. Puste source: "" nie jest sprawą helm: nie wskazuje ani trybu bez źródła, ani trybu źródłowego, więc odmowa, którą powoduje, jest taka sama niezależnie od providera, na który celuje encja Recipe, i następuje już podczas odczytu encji Recipe, przed wczytaniem jakiegokolwiek chartu oraz przed przekazaniem sterowania do tego providera. To, które polecenia ją zgłaszają, opisano w entities/recipe.md „Source field scheme inventory” oraz errors/fatal-halts.md „Recipe source: is an empty string (Pole source encji Recipe jest pustym ciągiem)”.

Tryb źródłowy

Recipe z source: <chart-path> i valuesMapping: podczas renderowania bazowego wykonuje następujący potok:

  1. Chart spod <chart-path> jest ładowany za pomocą Helm Go SDK.
  2. Szablon valuesMapping jest wyliczany względem kontekstu szablonów encji Recipe. Jego wyjście YAML jest traktowane jako nakładka wartości dla chartu.
  3. Nakładka jest jednokrotnie scalana z wartościami domyślnymi z values.yaml chartu; w razie kolizji wygrywają klucze nakładki (standardowa semantyka helm install --values w Helm). Klucz, który nakładka ustawia na null, usuwa wartość domyślną chartu dla tego klucza — na najwyższym poziomie, wewnątrz tabeli lub w wartościach zależności — tak jak robi to helm install --values, więc szablony chartu odczytują ten klucz jako nieobecny; null przy kluczu, dla którego chart nie podaje wartości domyślnej, trafia do szablonów jako null.
  4. Helm SDK renderuje szablony chartu względem scalonych wartości.
  5. Aggrega wstrzykuje swoje metadane pochodzenia do wyrenderowanych manifestów przez przepisywanie YAML po renderowaniu, dzięki czemu wyjście trybu źródłowego nosi te same etykiety co wyjście trybu Workload. Wartości tożsamości stają się etykietami (app.kubernetes.io/name, aggrega.ai/component-id, aggrega.ai/provider, aggrega.ai/provider-version, aggrega.ai/environment oraz — jeśli są ustawione — aggrega.ai/aggregate-name, aggrega.ai/compiler-version), każda zapisana w postaci, którą Kubernetes akceptuje jako wartość etykiety; wartości, których etykieta Kubernetes nie może przedstawić, stają się adnotacjami (aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave, gdy fala jest różna od 0, oraz dosłowna wartość każdej etykiety, której wartość trzeba było przepisać — encja Aggregate o nazwie imported/flow otrzymuje etykietę imported-flow i adnotację imported/flow pod tym samym kluczem). Reguła przepisywania jest podana w well-known-annotations.md „Etykiety pochodzenia emitowane przez dostawców”.
  6. Pliki wyjściowe trafiają płasko do katalogu wyjściowego encji Recipe, po jednym na wyrenderowany zasób, pod nazwą <name-basis>-<kind>[-<namespace>]-<name>.yaml — ta sama podstawa, z której wyprowadzana jest opisana niżej nazwa wydania, a po niej własny rodzaj zasobu, przestrzeń nazw, jeśli ją ma, oraz nazwa, każde zapisane małymi literami, z każdym ciągiem innych znaków zredukowanym do pojedynczego łącznika. Dla zwykłego komponentu tą podstawą jest własna tożsamość komponentu, którą nosi też etykieta aggrega.ai/component-id zasobu; dla chartu dostarczonego przez autora dołączenia encji Feature pozostaje nią tożsamość komponentu gospodarza, podczas gdy etykieta nosi własną tożsamość dołączenia. Dokument bez rodzaju lub bez nazwy otrzymuje zamiast tego nazwę od ścieżki swojego szablonu. Struktura katalogów chartu jest spłaszczana: w wyrenderowanym wyjściu nie ma podkatalogu templates/, a dwa szablony z różnych podkatalogów o tej samej nazwie pliku pozostają dwoma plikami, ponieważ nazwa pochodzi od zasobu, a nie od szablonu. Plik wskazany w bloku artifacts: encji Recipe nie trafia tutaj: leży katalog niżej, w katalogu nazwanym od komponentu, który go zadeklarował, ponieważ taki plik nosi nazwę od klucza zapisanego przez autora, a nie od zasobu, który zawiera — bez tego katalogu dwa komponenty powiązane z jedną encją Recipe zapisałyby jedną ścieżkę, a żaden z autorów nie mógłby ich rozdzielić.

Przestrzeń nazw, względem której chart jest renderowany, jest odczytywana z adnotacji aggrega.ai/namespace dziedziczonej kaskadowo od granicy i trafia do chartu jako przestrzeń nazw jego wydania; gdy żadna granica jej nie deklaruje, chart jest renderowany względem default. Tam, gdzie granica ją deklaruje, każdy zasób z przestrzenią nazw, który chart renderuje bez przestrzeni nazw — bez metadata.namespace albo z wartością pustą lub null — jest emitowany w zadeklarowanej przestrzeni nazw, czyli tam, gdzie umieściłaby go instalacja chartu przez Helm pod tą przestrzenią nazw wydania, a jego plik otrzymuje nazwę z segmentem przestrzeni nazw dokładnie tak jak zasób, którego szablon zapisuje to pole. Zasób, którego szablon zapisuje przestrzeń nazw, zachowuje ją, niezależnie od tego, jaką przestrzeń nazw wskazuje. Zasób o zasięgu klastra pozostaje bez niej. To, czy rodzaj ma przestrzeń nazw, wynika z zasięgu określonego przez samo API Kubernetes dla rodzajów, które API samo obsługuje, a dla rodzaju niestandardowego z pola scope, które deklaruje dla niego CustomResourceDefinition w tym samym renderowaniu — z szablonów chartu lub z jego katalogu crds/. Zasób rodzaju, którego żadne z nich nie klasyfikuje, pozostaje taki, jak zapisał go chart, a kompilacja zgłasza go raz na rodzaj, podając rodzaj i jego grupę API; to samo dotyczy dokumentu kind: List, którego elementy nie są umieszczane. Tam, gdzie żadna granica nie deklaruje przestrzeni nazw, nic nie jest umieszczane i nic nie jest zgłaszane: zasób zapisany przez chart bez przestrzeni nazw jest emitowany bez niej i umieszczany tam, gdzie wskaże narzędzie, które go stosuje.

Zgłoszenie jest ostrzeżeniem kompilacji, która mimo to się kończy:

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

Jeśli chart ma wartość, która renderuje CustomResourceDefinition danego rodzaju, lub taką, która sama zapisuje przestrzeń nazw, ustawienie jej przez valuesMapping encji Recipe umieszcza taki zasób.

Wersja Kubernetes, dla której renderowany jest chart

Szablony chartu odczytują wersję Kubernetes, dla której są renderowane, jako .Capabilities.KubeVersion, a wiele z nich wybiera na jej podstawie wersję API, pole lub cały mechanizm — na przykład token konta usługi projektowany od wersji 1.21 wzwyż, a poniżej token własny. Build nie ma klastra, którego mógłby zapytać, więc wersję należy podać samodzielnie, tam gdzie encja Release określa, gdzie wdrażany jest komponent: w adnotacji aggrega.ai/kubernetes-version na granicy lub na komponencie, gdzie ma ona pierwszeństwo przed adnotacją jego granicy, dziedziczonej kaskadowo dokładnie tak jak aggrega.ai/namespace.

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

Wartość jest odczytywana tak, jak helm template --kube-version odczytuje swoją flagę, więc przyjmuje formy, które przyjmuje ta flaga, a chart odczytuje dokładnie to, co dałaby mu ta flaga: "1.31" jest odczytywane jako v1.31, "v1.31.2" jako v1.31.2, a tekst po liczbach pozostaje w .Capabilities.KubeVersion.Version w zapisanej postaci — "1.29.3-gke.100" jest odczytywane jako v1.29.3-gke.100 — natomiast .Capabilities.KubeVersion wypisane w całości zawiera wersję bez niego. Chart porównujący .Capabilities.KubeVersion.Version za pomocą semverCompare odczytuje taki sufiks jako wersję przedpremierową, więc ograniczenie bez dolnej granicy -0, takie jak ">=1.21", do niej nie pasuje, a wartość otoczona spacjami jest odczytywana wraz z tymi spacjami — " 1.30 " jest odczytywane jako "v 1.30 " — i całkowicie nie przechodzi takiego porównania: tam, gdzie chart porównuje wersję, należy zapisać samą wersję. Wartość, która nie jest wersją — "one.two", "latest", pojedyncza liczba — zatrzymuje build w ramach warunku dla wartości, dla której plugin nie ma reprezentacji, z podaniem wartości, komponentu i jego granicy; chart nigdy nie jest renderowany w zastępstwie dla innej wersji. Zob. A Kubernetes version the helm provider cannot render a chart for (Wersja Kubernetes, dla której provider helm nie może wyrenderować chartu). Pusta wartość jest traktowana jak nieustawiona.

Jeśli żadna adnotacja nie podaje wersji, chart jest renderowany dla wersji, dla której renderuje standardowe helm template tego samego wydania helm, czyli dla wersji biblioteki klienta Kubernetes, z którą zbudowano providera: provider zbudowany z biblioteką klienta v0.37 renderuje dla Kubernetes v1.37.0. Chart renderuje się więc w Aggrega tak, jak renderuje go helm template jego własnych autorów, a wartość domyślna zmienia się tylko wtedy, gdy zmienia się biblioteka klienta, z którą zbudowano providera. Należy podać wersję klastra docelowego zawsze, gdy jest inna: chart wyrenderowany dla nowszej wersji niż ta, na której działa klaster, może wygenerować wersję API, której ten klaster nie obsługuje.

W ten sposób ustawiana jest tylko wersja. Każda inna możliwość odczytywana przez chart — .Capabilities.APIVersions i .Capabilities.HelmVersion — jest wbudowaną wartością biblioteki helm, więc API udostępniane przez klaster z zainstalowanej definicji CustomResourceDefinition nie jest zgłaszane chartowi. Własny zakres kubeVersion chartu w jego pliku Chart.yaml nie jest porównywany z wersją: helm template odrzuca chart, którego zakres wyklucza wersję, dla której renderuje, a build go renderuje. Adnotacja wpływa wyłącznie na chart renderowany ze źródła: syntetyzowana encja Workload i treść artifacts: nie odczytują .Capabilities, a provider helm-chart przekazuje swój chart dalej bez renderowania, aby został wyrenderowany podczas instalacji.

Pomijanie wyrenderowanych dokumentów. Ten provider uwzględnia wpisy omits: deklarowane przez encję Recipe lub FeatureRecipe, w tym trybie i w żadnym innym: syntetyzowana encja Workload i treść artifacts: renderują się bez nich. Każdy dokument renderowany przez chart — z szablonu lub z pliku w jego katalogu crds/ — jest dopasowywany do każdego wpisu mającego zastosowanie do buildu, a dokument wskazany przez którykolwiek wpis jest pomijany. Wpis wskazuje dokument za pomocą słów, które niesie sam dokument, tych samych, z których budowane są nazwa jego pliku wyjściowego i jego fakty renderowania: jego kind, jego metadata.name oraz, tylko jeśli wpis ją podaje, przestrzeń nazw, w której znajduje się dokument — tę zapisaną przez jego szablon lub zadeklarowaną przestrzeń nazw granicy, gdy ten provider umieszcza w niej dokument w sposób opisany powyżej. Nigdy nie jest to przestrzeń nazw, względem której chart jedynie się renderuje: bez zadeklarowanej przestrzeni nazw chart renderuje się względem default, ale dokument, którego szablon nie zapisuje przestrzeni nazw, nie znajduje się w żadnej, więc wpis podający default do niego nie pasuje. Dokument bez rodzaju lub bez nazwy nie pasuje do żadnego wpisu. Pomijane dokumenty są renderowane, a następnie odrzucane po ustaleniu nazw wszystkich plików, więc każdy zachowany dokument otrzymuje nazwę i jest zapisywany dokładnie tak, jak bez tych wpisów, a pominięty dokument nie trafia do niczego, co build robi później — do żadnego pliku, do żadnej nazwy w porównaniu odrzucającym dwóch współtwórców trafiających w jedną, do żadnego faktu renderowania odczytywanego przez encję Feature, do niczego, co otrzymuje krok potoku. Provider zgłasza, ile dokumentów dopasował każdy wpis, a wpis, który nie dopasował żadnego, zatrzymuje build; zob. An omits entry left out nothing the source rendered (Wpis omits nie pominął niczego, co wyrenderowało źródło).

Wydanie Helm, w ramach którego renderowany jest chart

Provider renderuje za pomocą SDK Helm 4 w wersji v4.3, więc chart odczytuje to, co daje mu własne helm template Helma 4, a ten sam chart i te same wartości dają przy każdej kompilacji te same bajty. Chart napisany i sprawdzony z Helmem 3 może zaobserwować następujące zachowania Helma 4:

  • .Capabilities.HelmVersion zwraca wersję Helma 4, v4.3.
  • Domyślna wersja Kubernetes to v1.37.0, ponieważ Helm 4 w wersji v4.3 jest zbudowany z biblioteką kliencką v0.37, a .Capabilities.APIVersions to zestaw wersji API tej biblioteki klienckiej. Należy podać wersję, na której działa klaster, zgodnie z opisem w sekcji Wersja Kubernetes, dla której renderowany jest chart.
  • Domyślna wartość null w chartcie jest pomijana. Klucz, który plik values.yaml chartu ustawia na null — na najwyższym poziomie lub wewnątrz tabeli — jest nieobecny w .Values, chyba że ustawiają go wartości dostarczone przez encję Recipe, więc hasKey zgłasza jego brak, toYaml go pomija, a plik values.schema.json chartu jest sprawdzany względem wartości bez niego.
  • Skalar blokowy zachowuje końcowy znak nowej linii przed ---. Dokument, który kończy się skalarem blokowym i po którym następuje inny dokument z tego samego szablonu, zachowuje ostatni znak nowej linii tego skalara, więc jest zapisywany jako |, a nie |-.
  • .Chart jest mapą kluczowaną nazwami pól. .Chart.Name, .Chart.Version, .Chart.AppVersion i pozostałe pola odczytuje się jak dotąd, ale toYaml .Chart lub toJson .Chart.Maintainers wypisują klucze jako Name, AppVersion itd., z obecnymi pustymi polami, a pole, którego metadane chartu nie zawierają, jest odczytywane jako puste zamiast powodować niepowodzenie renderowania.
  • .Capabilities.KubeVersion.Version zachowuje tekst wersji w zapisanej postaci, jak opisano powyżej dla adnotacji aggrega.ai/kubernetes-version.
  • Plik values.yaml zawierający kilka dokumentów YAML jest odczytywany w całości, a późniejsze dokumenty są scalane z wcześniejszymi, nadpisując je.
  • .Files.Lines dla pustego pliku nie zwraca żadnych wierszy zamiast powodować niepowodzenie renderowania.
  • Funkcje szablonów dodane w Helm 4 — mustToYaml, mustToJson, mustToToml, mustToDuration oraz konwersje duration… — są dostępne w szablonach chartu.
  • Zależność z dwoma aliasami daje każdemu aliasowi własną kopię zależności tej zależności.
  • Walidacja schematu wartości akceptuje lub odrzuca inaczej tylko w przypadkach brzegowych: cytowana część lokalna adresu e-mail, NaN i liczby nieskończone, liczba porównywana z wartością nieliczbową w enum i const oraz lokalizacja zgłaszana dla niespełnionego propertyNames, contentSchema lub dalszego elementu tablicy.

Szablon, którego sam silnik nie zdoła wykonać — na przykład wartość odczytywana przez brakującą tabelę — jest zgłaszany w formie Helma 4: plik, wiersz i kolumna szablonu w osobnym wierszu, a następnie, z wcięciem, to, co było wykonywane, i komunikat, dla każdego szablonu, przez który przeszedł błąd. Własne fail lub required chartu zachowuje jednowierszową formę execution error at (<file>:<line>:<col>): <message>, podobnie jak błąd zwracany przez funkcję szablonu.

Jak wyprowadzana jest nazwa wydania

Chart w trybie źródłowym jest renderowany względem nazwy wydania, która trafia do każdego szablonu jako .Release.Name. Charty rutynowo nazywają zasoby od niej, więc nazwa wydania jest tożsamością wewnątrz klastra, a nie etykietą kompilacji.

Nazwa wydania jest zakodowaną postacią tej samej podstawy, którą poprzedzona jest nazwa pliku wyjściowego renderowanego zasobu, więc obie są jedną nazwą zapisaną dwukrotnie. Tą podstawą jest instance_id dla zwykłego komponentu oraz złożona tożsamość, którą niesie encja Feature dołączona do granicy. Dla chartu dostarczonego przez autora dołączenia encji Feature jest nią nazwa komponentu hosta: własne szablony chartu renderują się względem nazwy wydania, więc wyprowadzenie jej z dołączenia zmieniłoby nazwy zasobów deklarowanych przez chart w klastrze, w którym są już wdrożone. Zasoby te nadal niosą własną tożsamość dołączenia w etykiecie aggrega.ai/component-id — to, jak zasób się nazywa, i to, do czego należy, są tu osobnymi kwestiami i tylko dla zwykłego komponentu mają tę samą odpowiedź. Nazwa wydania Helm akceptuje węższy zbiór znaków niż tożsamość: małe litery, cyfry, łączniki i kropki, z małą literą lub cyfrą na początku i na końcu, do 53 znaków. Zamiast zastępować znak, którego cel nie akceptuje, wyprowadzenie zapisuje go w postaci rozwiniętej, więc dwie tożsamości komponentów różniące się tylko interpunkcją lub wielkością liter zawsze dają dwie różne nazwy wydania.

  • Mała litera i cyfra są przenoszone dokładnie w zapisanej postaci.
  • Łącznik jest zachowywany w zapisanej postaci wszędzie tam, gdzie następujący po nim znak jest przenoszony bezpośrednio i nie jest małą literą z. Łącznik, po którym następuje mała litera z, otwiera sekwencję ucieczki, więc zapisany na tej pozycji łącznik sam jest zapisywany w postaci rozwiniętej — api-zone staje się api-zhzone, co pozwala odczytać każdą nazwę z powrotem bez zgadywania. Łącznik, po którym nic nie następuje, jest z tego samego powodu zapisywany w postaci rozwiniętej, więc db- daje db-zh.
  • Każdy inny znak jest zapisywany jako -z, po którym następuje litera go oznaczająca: d dla kropki, u dla podkreślenia, s dla separatora ścieżki, h dla łącznika, którego powyższa reguła nie zachowuje. Wszystko inne — łącznie z wielką literą — jest zapisywane jako x i sześciocyfrowy szesnastkowy punkt kodowy znaku, a bajt, który nie rozpoczyna żadnego znaku, jako b i jego własna dwucyfrowa wartość.
  • Pusta wartość jest zapisywana jako -ze, czego żadna niepusta wartość nie może dać.

Kropka jest zapisywana w postaci rozwiniętej, a nie przenoszona, mimo że Helm akceptuje ją w nazwie wydania, ponieważ Helm wymaga małej litery lub cyfry po obu stronach kropki, a wyprowadzenie wstawia własne łączniki.

Ponieważ dwie encje Features dołączone do jednego komponentu renderują się względem nazwy wydania tego komponentu, dwa charty, z których każdy nazywa zasób od .Release.Name, emitują dwa zasoby o jednej nazwie. Ten provider zgłasza nazwę, którą nosi każdy zasób wytworzony przez jego własne renderowanie, w zakresie rodzaju tego zasobu oraz — dla rodzaju, który klaster przechowuje w przestrzeni nazw — jego przestrzeni nazw, a kompilacja odrzuca dwóch współtwórców trafiających na jedną z nich, zamiast emitować wynik, w którym zastosowanie obu pozostawia tylko ostatni — zob. ../errors/fatal-halts.md „The same name is derived more than once inside the output (Ta sama nazwa jest wyprowadzana więcej niż raz w wyniku)”. Rodzaj, który klaster przechowuje poza wszelkimi przestrzeniami nazw — ClusterRole, CustomResourceDefinition lub rodzaj niestandardowy, który CustomResourceDefinition w tym samym renderowaniu deklaruje z zakresem Cluster — ma zakres wyłącznie swojego rodzaju, klasyfikowany dokładnie tak, jak klasyfikuje go opisane wyżej umieszczanie w przestrzeni nazw, więc dwa komponenty jednego wyniku, z których każdy zapisuje jeden taki obiekt pod jedną nazwą, są odrzucane nawet wtedy, gdy encja Release umieszcza je w różnych przestrzeniach nazw. Rozwiązaniem jest złożenie nazwy, a to, jakiej współrzędnej potrzebuje, zależy od układu. Dwa dołączenia na jednym komponencie już współdzielą hosta, więc to dołączenie musi dotrzeć do szablonu: należy przekazać .attachment_name do chartu przez valuesMapping: encji FeatureRecipe i ustawić je w tej z własnych wartości chartu, z której budowane są nazwy jego zasobów. Jeden chart dołączony do dwóch komponentów to sytuacja odwrotna — nazwa wydania już różni się dla każdego hosta, więc zasób nazwany od .Release.Name nosi na każdym z nich własną nazwę, a nazwa dosłowna nie. Encja FeatureRecipe dostarczająca swoje zasoby przez artifacts: jest zgłaszana na tych samych zasadach: ten provider odczytuje nazwę, którą nosi każdy emitowany dokument, niezależnie od tego, czy dokument pochodzi z szablonu chartu, czy z treści artefaktów, więc dosłowna nazwa w takiej treści dołączonej do dwóch komponentów również zatrzymuje kompilację. Treść artefaktów jest szablonem, więc nazwę należy złożyć z .context.rendered_name — nazwy wydania hosta, która różni się dla każdego hosta i jest zapisana znakami dozwolonymi w nazwie Kubernetes — oraz .attachment_name tam, gdzie musi być odrębna dla każdego hosta; na hoście, który umieszcza zestaw artefaktów samodzielnie i nie zgłasza nazwy wydania, należy złożyć ją z .context.instance_id. Nie każda nazwa jest zgłaszana, więc kompilacja, która się nie zatrzymuje, nie porównała wszystkiego, co jej wynik ostatecznie będzie zawierał. Przypadek, który najpewniej wystąpi przy pisaniu chartu, to zasób deklarujący generateName, którego uzupełnienie pozostawia się klastrowi, więc nie ma jeszcze czego porównać. Pełny zbiór zawiera strona podlinkowana powyżej.

Zatem instance_id o wartości api daje nazwę wydania api, data.main-db daje data-zdmain-db, a db_host daje db-zuhost. Tożsamość zbudowana wyłącznie z małych liter, cyfr i łączników zachowywanych przez wyprowadzenie pojawia się dokładnie w zapisanej postaci. Identyczne wejście zawsze daje identyczną nazwę.

Dwa z warunków Helm są właściwościami podstawy, a nie wyprowadzenia: nazwa wydania musi zaczynać się od małej litery lub cyfry i mieć co najwyżej 53 znaki. Podstawa, której pierwszy znak jest zapisywany w postaci rozwiniętej, zaczyna nazwę od łącznika, od którego zaczyna się każda sekwencja ucieczki, a podstawa zawierająca znaki zapisywane w postaci rozwiniętej po zakodowaniu jest dłuższa niż w zapisie. Kompilacja pyta ten provider o oba warunki i reaguje na odpowiedź w czasie kompilacji, zamiast pozostawiać odrzucenie klastrowi w czasie stosowania — zob. ../errors/fatal-halts.md „The target will not accept a name derived from an authored identity (Cel nie zaakceptuje nazwy wyprowadzonej z zapisanej tożsamości)”. To, co robi z odpowiedzią, zależy od tego, kto zapisał podstawę. Nazwa zapisana przez autora jest odrzucana, a nie zmieniana, a odrzucenie wskazuje zapisane pole i dostępny limit; nazwa złożona przez Aggrega jest skracana, aż ten provider ją zaakceptuje.

Klaster stosuje do zasobów nazwanych od komponentu jedną regułę surowszą niż Helm: nazwa Service musi zaczynać się od litery, podczas gdy nazwa wydania może zaczynać się od cyfry. Chart rutynowo nazywa swoje Services od nazwy wydania, a Services syntetyzowanego workloadu również się od niej zaczynają, więc ten provider odrzuca także nazwę komponentu zaczynającą się od cyfry, zgłaszając ją jako Service name, której cel nie może użyć. Żadna długość nie naprawi pierwszego znaku, więc to odrzucenie nie podaje żadnej. Dlatego instance_id należy zaczynać od małej litery i utrzymywać na tyle krótkim, by jego zakodowana postać nadal się mieściła.

Zmiana podstawy, z której wyprowadzana jest nazwa wydania, zmienia nazwy zasobów klastra, które chart nazywa od .Release.Name, oraz wszystkich zasobów, które ten provider syntetyzuje dla komponentu, a Kubernetes nie zmienia nazwy zasobu w miejscu. Narzędzie stosujące tworzy zasób pod nową nazwą i usuwa ten pod starą nazwą, co w przypadku zasobów stanowych oznacza zwolnienie pamięci masowej powiązanej ze starą nazwą. Taką zmianę należy traktować jako zastąpienie wymagające zaplanowania — opróżnienia, migracji lub wyznaczenia terminu — a nie jako aktualizację do wdrożenia.

Tryb Workload (syntetyzowany)

Recipe z workload: (wbudowanym lub załadowanym przez $import:) syntetyzuje zasoby Kubernetes z abstrakcyjnej intencji encji Workload. Schemat encji Workload jest opisany w entities/workload.md; ta sekcja opisuje, co emituje provider helm.

Dla każdego węzła:

  • Jeden obiekt kontrolera wybrany przez form encji Workload: stateless (oraz wartość domyślna) emituje Deployment, stateful — StatefulSet, daemon — DaemonSet, task — Job, scheduled — CronJob, którego spec.schedule jest polem schedule encji Workload (5-polowym wyrażeniem cron lub makrem @); workload scheduled bez harmonogramu lub z niepoprawnym harmonogramem jawnie zatrzymuje budowanie. Workload scheduled deklarujący suspend: true emituje swój CronJob z spec.suspend: true, więc żadne uruchomienie nie startuje z harmonogramu, dopóki nie zostanie wznowiony, a Job nadal można utworzyć z CronJob ręcznie; workload, który tego nie deklaruje, w ogóle nie emituje klucza suspend. Deployment i StatefulSet niosą liczbę replik; DaemonSet, Job i CronJob nie niosą żadnej. Workload stateful wymaga dokładnie jednego Service type: Headless zadeklarowanego w encji Workload, który zarządza StatefulSet; provider wiąże serviceName StatefulSet z wyrenderowaną nazwą tego Service, a budowanie zostaje zatrzymane, jeśli nie zadeklarowano żadnego Service headless (lub zadeklarowano więcej niż jeden). Wolumen persistentTemplate towarzyszy form: stateful — zadeklarowanie go przy dowolnej innej formie zatrzymuje budowanie z komunikatem wskazującym poprawkę.
  • Jeden Service na każdy zadeklarowany wpis services: w encji Workload, udostępniający nazwane porty wymienione w specyfikacji usługi. type wpisu staje się typem Service — ClusterIP, NodePort i LoadBalancer dosłownie, a Headless jako Service ClusterIP z clusterIP: None. Wpis Loopback zamiast tego zatrzymuje budowanie, wskazując węzeł i usługę: Service Kubernetes nie ma typu wiążącego się z adresem loopback hosta, a to, na których adresach węzła nasłuchuje Service NodePort, jest ustawieniem całego klastra, więc wpis jest odrzucany, zamiast zostać wyrenderowany z zasięgiem, o który nie prosił. Zob. A service type the helm provider cannot render (Typ usługi, którego provider helm nie może wyrenderować).
  • Jeden PersistentVolumeClaim na każdy wolumen persistent, o rozmiarze i kształcie wynikających ze specyfikacji wolumenu. Wolumen persistentTemplate nie emituje samodzielnego żądania: staje się wpisem volumeClaimTemplates wewnątrz własnej specyfikacji StatefulSet, dlatego towarzyszy form: stateful.

Nazwy zasobów. Każdy zasób emitowany w tym trybie dla komponentu otrzymuje nazwę od nazwy wydania komponentu — tej samej, względem której renderuje się chart w trybie sourced, wyprowadzonej tak, jak opisuje Jak wyprowadzana jest nazwa wydania — a provider zgłasza tę nazwę do budowania jako {{ .context.rendered_name }}. Obiekt kontrolera nosi samą nazwę wydania; każdy Service to <release name>-<service key>; każde samodzielne żądanie to <release name>-<volume>, a wolumen poda odwołuje się dokładnie do tego żądania; sekret dostarczany jako plik jest montowany z wolumenu poda o nazwie <release name>-secret-<slot>, przy czym slot jest zapisany w alfabecie akceptowanym przez klaster, tak jak nazwa wydania — więc slot server_certificate jest montowany z <release name>-secret-server-zucertificate, a w slocie odczytywanym przez połączenie kropka po nazwie połączenia jest zapisywana w ten sam sposób; serviceName StatefulSet jest nazwą emitowanego przez niego Service headless; a Workload udostępniany wyłącznie przez nazwę zewnętrzną emituje jeden Service noszący nazwę wydania. Zatem komponent api emituje Deployment api i Service default o nazwie api-default, a komponent my_api emituje my-zuapi i my-zuapi-default — nazwy, które klaster akceptuje, w przeciwieństwie do tożsamości w zapisanej postaci. Recipe publikujący adres jednego z tych Service buduje go z {{ .context.rendered_name }}, jak pokazuje ../templates/rendered-resource-names.md; dla komponentu, którego nazwa nie zawiera podkreślenia ani wielkiej litery, nazwa wydania jest równa jego instance_id, więc jego nazwy brzmią dokładnie jak tożsamość. Jedynym wyjątkiem jest workload syntetyzowany przez dołączenie encji Feature: otrzymuje nazwę od własnej złożonej tożsamości dołączenia — wartości, którą niesie jego etykieta aggrega.ai/component-id — ponieważ dołączenie renderuje się względem komponentu hosta, a wyprowadzona tam nazwa wydania nazwałaby workload dołączenia od hosta i kolidowałaby z własnym workloadem hosta. Ta tożsamość nigdy nie zawiera wielkiej litery: wielka litera w nazwie hosta lub dołączenia jest zapisywana jako sekwencja ucieczki, tak jak każdy inny znak, którego nie przyjmuje nazwa zasobu, więc dołączenie worker na komponencie myApi emituje Deployment cfr--my-zx000041pi--worker i Service default o nazwie cfr--my-zx000041pi--worker-default, a każda nazwa, którą nosi workload, jest akceptowana przez klaster.

Długości nazw zależne od encji Workload. Dwie z tych nazw podlegają w klastrze własnym limitom, a kompilacja sprawdza obie po rozwiązaniu encji Workload, zamiast zostawiać odmowę klastrowi w momencie zastosowania. Nazwa CronJob ma co najwyżej 52 znaki, mniej niż inne nazwy w klastrze, ponieważ kontroler nazywa Job każdego uruchomienia od nazwy CronJob z dołączonym sufiksem; jest sprawdzana tylko dla encji Workload scheduled. Każda nazwa Service, <release name>-<service key>, ma co najwyżej 63 znaki. Po przekroczeniu któregokolwiek limitu to, co się dzieje, zależy od tego, kto napisał nazwę, dokładnie tak jak w przypadku nazwy release: nazwa komponentu napisana przez autora jest odrzucana, a kompilacja zatrzymuje się na zapisanym przez niego kluczu spec.components, podając rodzaj nazwy, jej długość i dostępny dla niej budżet znaków — zob. ../errors/fatal-halts.md „The target will not accept a name derived from an authored identity (Cel nie akceptuje nazwy wyprowadzonej z tożsamości zapisanej przez autora)”; tożsamość złożona, taka jak ta, od której nazywany jest workload dołączenia encji Feature, jest skracana, aż każda nazwa się zmieści. Nazwa Service powstaje z nazwy komponentu i klucza deklarowanego przez workload — w encji Recipe lub w encji FeatureRecipe — więc odmowa wskazuje ten klucz i miejsce, w którym workload go deklaruje, spec.workload.services.<key>; klucz, który nie zostawia miejsca na żadną nazwę komponentu, musi sam zostać skrócony. Komponent z encją Workload scheduled może więc mieć zakodowaną nazwę o długości do 52 znaków, a komponent web może mieć klucze Service o długości do 59. Encja Feature dołączona do całej granicy ma tożsamość ustaloną przed rozwiązaniem jej encji Workload, ponieważ miejsce zestawienia jej wyniku może zależeć od tej tożsamości, więc żaden z tych limitów nie jest sprawdzany dla zasobów, które syntetyzuje.

Każdy emitowany zasób niesie pełny zestaw etykiet i adnotacji pochodzenia Aggrega oraz parę selektora (app: <instance_id>) łączącą Deployment/StatefulSet z jego Service. Wartość etykiety dopuszcza tożsamość w zapisanej postaci, więc selektor ją zachowuje, podczas gdy powyższe nazwy przyjmują nazwę wydania. Nazwy kontenerów w wyrenderowanym Deployment to klucze kontenerów encji Workload, w których znaki . i _ zastąpiono znakiem - (sanityzacja nazw Kubernetes).

Transport portu. Port kontenera deklarujący transport emituje go dosłownie jako protocol: w wyrenderowanym containerPort, a każdy port Service wskazujący ten port kontenera niesie tę samą wartość — transport jest deklarowany raz, przy porcie kontenera, więc udostępnienie nie może być z nim sprzeczne. Port bez zadeklarowanego transportu nie emituje klucza protocol w żadnym z zasobów, pozostawiając w mocy wartość domyślną klastra. Wszystkie trzy wartości dopuszczane przez Workload (TCP, UDP, SCTP) są emitowane dosłownie; helm nie wymaga degradacji, ponieważ Kubernetes wyraża każdą z nich bezpośrednio.

Uruchamianie w sieci węzła. Workload deklarujący hostNetwork: true emituje hostNetwork: true w wyrenderowanej specyfikacji poda, więc pod działa we własnej przestrzeni nazw sieci węzła, a porty otwierane przez jego kontenery są osiągalne pod adresami węzła. Kubernetes wyraża ten wybór bezpośrednio, więc nic nie jest degradowane. Deklaracja trafia do specyfikacji poda i nigdzie indziej: nie dodaje, nie usuwa ani nie przepisuje żadnego portu, a emitowane Service są identyczne z nią i bez niej. Workload, który jej nie deklaruje, w ogóle nie emituje klucza hostNetwork.

Ilości zasobów. Każda ilość kopiowana przez providera do manifestów jest emitowana dosłownie, a każda jest najpierw sprawdzana pod kątem formy ilości opisanej w Workload → Ilości zasobów: wartości resources.requests i resources.limits każdego kontenera i kontenera init — cpu, memory oraz każdego zasobu rozszerzonego, takiego jak nvidia.com/gpu — oraz ephemeral.sizeLimit, persistent.size i persistentTemplate.size każdego wolumenu. Sprawdzenie działa na encji Workload w postaci, w jakiej obliczyły ją szablony encji Recipe, więc wartość, która przyszła przez infra lub parametr encji Release, jest oceniana według tego, do czego się wyrenderowała. Wartość spoza tej formy zatrzymuje budowanie z TRANSLATION_ERROR wskazującym węzeł, ścieżkę pola w encji Workload i wartość — na przykład containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — tam, gdzie chart w przeciwnym razie zbudowałby się bez błędów, a następnie zostałby odrzucony przez klaster przy instalacji. Puste cpu, memory lub sizeLimit jest pomijane w manifestach, więc nie jest sprawdzane; pusta wartość zasobu rozszerzonego lub pusty rozmiar trwały nadal zostałyby wyemitowane, więc są odrzucane. Sprawdzenie ocenia wyłącznie formę: czy klaster może zaplanować daną ilość, tego provider nie może wiedzieć w czasie budowania.

Nazewnictwo plików wyjściowych ma dwie postacie. Obiekt kontrolera otrzymuje nazwę od nazwy wydania i swojego rodzaju — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Plik dla pojedynczego zasobu otrzymuje nazwę od zasobu, który zawiera, z rodzajem na końcu: <release name>-<svcName>-service.yaml i <release name>-<volName>-pvc.yaml, każda pobrana z własnego metadata.name tego zasobu zgodnie z konwencją nazw syntetyzowanych opisaną w entities/workload.md. Workload udostępniany wyłącznie przez nazwę zewnętrzną emituje <release name>-service.yaml, ponieważ nie ma klucza usługi do uwzględnienia.

Fakty renderowania

Oprócz renderowanych plików ten provider zgłasza o każdym węźle cztery fakty renderowania: co wyemitowane przez niego dokumenty Kubernetes mówią o swoich podach, selektorach, portach i przestrzeni nazw, do której każdy z nich jest emitowany. Encja FeatureRecipe dołączona do komponentu odczytuje własne fakty komponentu w .context.render_facts; taka, która ustawia readsCallerRenderFacts: true, odczytuje także, w każdym wpisie .context.used_by, fakty komponentu łączącego się z jej hostem, a taka, która ustawia readsTargetRenderFacts: true, odczytuje w każdym wpisie .context.uses fakty komponentu, z którym jest połączony jej host. W ten sposób encja Feature może wskazać pody komponentów wywołujących jej hosta lub komponentów, do których sięga jej host — na przykład polityka sieciowa dopuszczająca dokładnie te pody — na podstawie tego, co faktycznie wyemitowały ich renderowania, bez ręcznego powtarzania czyjejkolwiek etykiety. Poniższe nazwy i wpisy stanowią kontrakt tego providera.

FaktJeden wpis naKażdy wpis zawiera
pod_template_labelswyemitowany szablon poda: spec.template obiektu Deployment, StatefulSet, DaemonSet, ReplicaSet lub Job, szablon zadania obiektu CronJob oraz samodzielny Pod, który jest własnym szablonemkind, name i namespace zasobu zawierającego szablon; labels — etykiety szablonu
controller_selectorswyemitowany Deployment, StatefulSet, DaemonSet, ReplicaSet, Job i CronJobkind, name, namespace; match_labels — matchLabels jego selektora
service_selectorswyemitowany Servicename, namespace; selector — etykiety, do których kieruje ruch
container_portskontener szablonu poda deklarujący listę ports, łącznie z kontenerami initkind, name i namespace zasobu zawierającego szablon; container — nazwa kontenera; ports — jeden wpis na port z jego name, container_port i protocol

Jak odczytywać fakty:

  • Każdy fakt jest listą. Szablon zawsze iteruje po fakcie, nawet gdy zawiera on jeden wpis; nie ma pojedynczej wartości do odczytania osobno.
  • Wszystkie cztery przy każdym renderowaniu. Każdy jest zgłaszany zawsze, gdy ten provider renderuje węzeł, jako pusta lista, gdy renderowanie nie wyemitowało niczego, co opisuje — komponent, którego chart emituje tylko ConfigMap, zgłasza cztery puste listy. Renderowanie innego providera nie zgłasza żadnej z tych nazw, a nazwa, której nikt nie zgłosił, odczytywana jest jako nic.
  • Odczytywane z tego, co wyemitowano, na każdej ścieżce. Fakty pochodzą z dokumentów wyemitowanych przez renderowanie, niezależnie od trybu, który je wytworzył: z wyrenderowanych manifestów chartu, z manifestów syntetyzowanego Workload oraz z manifestów umieszczonych przez autora za pomocą artifacts:, które zgłaszają dokładnie to, co te manifesty zawierają. Są odczytywane w tym samym przebiegu, z tych samych dokumentów, co nazwy zasobów zgłaszane przez ten provider na potrzeby sprawdzania duplikatów nazw w buildzie. Własne etykiety pochodzenia zasobu są częścią jego zawartości, więc labels samodzielnego Poda je obejmują; szablon poda chartu lub artefaktu zachowuje etykiety napisane przez jego autora.
  • Wpisy mogą pochodzić z własnego renderowania komponentu i z renderowań jego encji Features. Jeden komponent może być renderowany przez więcej niż jedno wywołanie — na przykład chart i umieszczenie przez artifacts: — a listy, które jedna nazwa otrzymuje z tych wywołań, są łączone w jedną w kolejności wykonania wywołań. W .context.used_by i .context.uses fakty komponentu po drugiej stronie połączenia obejmują też, po jego własnych, to, co wyrenderowały dołączone do niego encje Features; .context.render_facts zawiera wyłącznie własne renderowanie komponentu.
  • W kolejności emisji. Wpisy zachowują kolejność, w jakiej renderowanie wyemitowało zasoby. Mapa etykiet jest mapą z kluczami, jak każda inna w kontekście, więc szablon iterujący po niej napotyka klucze w kolejności kluczy.
  • Czego brakuje w dokumencie, tego brakuje we wpisie. Zasób nazwany przez generateName nie ma name; zasób niezapisujący metadata.namespace nie ma namespace, podobnie jak zasób zapisujący je jako puste lub null, co również nie wskazuje żadnej przestrzeni nazw; kontroler zapisany bez matchLabels — Job polegający na selektorze generowanym przez klaster — nie ma match_labels; Service bez selektora nie ma selector; port bez nazwy lub protokołu nie ma żadnego z nich. Każda inna część zapisana jako pusta jest zgłaszana jako pusta. protocol jest zgłaszany tylko tam, gdzie dokument go zapisuje, więc szablon, który go potrzebuje, sam zapisuje domyślną wartość klastra, TCP. container_port jest liczbą wszędzie tam, gdzie dokument go zapisuje.
  • namespace to ta wartość, którą zapisuje dokument, nigdy domysł. Jest to własne metadata.namespace zasobu — dla szablonu poda wartość zasobu, który go zawiera, czyli tam, gdzie działają jego pody; przestrzeń nazw zapisana w samym szablonie poda nie jest odczytywana. Syntetyzowany Workload zapisuje w każdym emitowanym zasobie przestrzeń nazw deklarowaną przez jego granicę, więc jego wpisy zawierają tę przestrzeń nazw. Wpisy chartu zawierają to, co zapisują jego wyemitowane dokumenty: tam, gdzie granica deklaruje przestrzeń nazw, tę przestrzeń nazw — niezależnie od tego, czy projektują ją szablony chartu, czy provider umieszcza w niej zasób (zob. Tryb sourced) — chyba że szablon przypina własną, którą wtedy zawiera wpis; tam, gdzie żadna nie jest zadeklarowana, przestrzeń nazw release, default, gdy projektują ją szablony, i nic, gdy nie zapisują żadnej. Tam, gdzie nic nie zapisano, wpis nie zawiera namespace zamiast wartości domyślnej granicy lub klastra, ponieważ taki zasób trafia tam, gdzie umieści go narzędzie stosujące wynik, czego nie wiadomo w trakcie buildu. Szablon rozróżnia te przypadki za pomocą optional: {{ optional . "namespace" "" }} jest puste dokładnie tam, gdzie dokument nie zapisał żadnej, więc encja Feature umieszczająca coś obok podów komponentu może odróżnić komponent, którego przestrzeń nazw podów jest znana, od takiego, którego nie jest.
  • Rozpoznawane po rodzaju i grupie API. Pod i Service są odczytywane w grupie core, cztery kontrolery w apps, Job i CronJob w batch, w dowolnej wersji grupy. Zasób niestandardowy innej grupy, który przypadkiem nosi jedną z tych nazw rodzajów, nie jest jako taki odczytywany. matchExpressions selektora nie są zgłaszane, podobnie jak zasób opakowany w dokument kind: List czy wartość zapisana przez klucz scalania YAML.

Czego fakty nie widzą. Opisują dokumenty emitowane przez build i nic, co klaster tworzy później. Pody, które kontroler tworzy w czasie działania z zasobu niestandardowego — na przykład klaster bazy danych operatora — nie występują w żadnym wyemitowanym dokumencie, więc z założenia ich brak; podobnie każdej etykiety dodawanej przez mutujący kontroler dopuszczenia przy stosowaniu manifestów. Encja Feature, która musi dopuścić takie pody, pobiera ich etykiety z dokumentacji zasobu niestandardowego, tak jak autor zrobiłby to bez tych faktów.

Encja FeatureRecipe dopuszczająca do podów swojego hosta dokładnie pody komponentów, które go wywołują, i wybierająca własne pody hosta po selektorze jego kontrolera:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

Dla hosta api wywoływanego przez komponent web, którego Workload zsyntetyzował ten provider, polityka wybiera app: "api" i dopuszcza podSelector zawierający każdą etykietę szablonu poda web — te same etykiety, które zawiera spec.template.metadata.labels jego wyemitowanego obiektu Deployment. Ponieważ encja FeatureRecipe ustawia ten klucz, jej dołączenie renderuje się dopiero po wyrenderowaniu każdego komponentu, więc fakty są dostępne niezależnie od tego, do którego z api i web build dotrze najpierw; bez tego klucza szablon odczytujący render_facts w .context.used_by zatrzymuje build, zanim cokolwiek zostanie wyrenderowane.

podSelector w from polityki dopasowuje pody we własnej przestrzeni nazw polityki, więc powyższa polityka dopuszcza wywołujących wyemitowanych do przestrzeni nazw, w której jest stosowana. Wywołującego, którego wpisy zawierają inną namespace, dopuszcza się, łącząc jego podSelector z namespaceSelector na etykiecie kubernetes.io/metadata.name tej przestrzeni nazw, którą Kubernetes ustawia w każdej przestrzeni nazw.

Osobliwości specyficzne dla Provider

  • Pobieranie chartów korzysta wyłącznie z wbudowanych mechanizmów Helm. Chart pobierany z repozytorium Helm jest ściągany za pomocą wbudowanych w Helm mechanizmów obsługi http i https. Wtyczka pobierania Helm — zainstalowana dla polecenia helm lub znajdująca się w katalogu, z którego uruchamiany jest build — nigdy nie jest używana, więc zawartość tego katalogu nie może zmienić sposobu pobierania chartu.

  • Wstrzykiwanie informacji o pochodzeniu. Ścieżki sourced i synthesized prowadzą do tego samego zestawu etykiet i adnotacji; renderowania w trybie sourced wstrzykują je przez przepisywanie YAML po renderowaniu (gdy Helm SDK już wyrenderował wynik), dzięki czemu autorzy chartów nie muszą przekazywać etykiet Aggrega przez własne szablony.

  • Kolejność zmiennych środowiskowych — najpierw wpisy odczytywane z Secret. Lista env syntetyzowanego kontenera zawiera dwa rodzaje wpisów: każdy wpis attachments dostarczany jako as: env odczytuje swoją wartość z obiektu Secret przez valueFrom.secretKeyRef, a każdy wpis variables zawiera zwykłą wartość value. Dostawca zapisuje najpierw wszystkie wpisy odczytywane z Secret, a po nich wszystkie zwykłe zmienne, każdy rodzaj w kolejności, w jakiej został zdefiniowany, a źródła envFrom wymienia osobno pod envFrom. Kubernetes rozwija odwołanie $(NAME) w wartości env na podstawie wpisów wymienionych przed nim w tym samym kontenerze, nigdy na podstawie wpisu wymienionego po nim, więc ta kolejność pozwala zwykłej zmiennej złożyć przez odwołanie wartość odczytaną z Secret, podczas gdy sam sekret pozostaje w obiekcie Secret:

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    Wyrenderowany kontener wymienia DB_PASSWORD przed DATABASE_URL, więc proces otrzymuje URL z hasłem na swoim miejscu. Zmienna może też odwoływać się do dowolnej zmiennej zdefiniowanej przed nią, dzięki czemu kolejność definicji ma znaczenie w obrębie variables. Kontenery init stosują tę samą kolejność. Kontener, który podaje jedną nazwę zarówno jako wpis variables, jak i jako wpis attachments dostarczany jako as: env, zatrzymuje build zamiast zapisywać oba wpisy, ponieważ o tym, którą wartość widzi proces, decydowałaby wtedy wyłącznie ta kolejność (zob. A container gives one environment variable two values (Kontener nadaje jednej zmiennej środowiskowej dwie wartości)).

  • Kaskada przestrzeni nazw — oba tryby docierają do zasobu inaczej. Oba odczytują aggrega.ai/namespace z kaskady adnotacji granic i żaden nie wymyśla przestrzeni nazw, gdy żadna granica jej nie deklaruje. W trybie synthesized dostawca zapisuje metadata.namespace bezpośrednio i całkowicie pomija to pole, gdy kaskada nie zwraca wartości. W trybie sourced dostawca przekazuje wartość jako przestrzeń nazw wydania chartu — default, gdy kaskada nic nie zwraca — a własny szablon chartu decyduje, czy ją przenieść; gdy przestrzeń nazw jest zadeklarowana, dostawca zapisuje ją następnie w każdym zasobie objętym przestrzenią nazw, który chart wyrenderował bez niej (zob. Tryb sourced). Zatem przy zadeklarowanej przestrzeni nazw oba tryby umieszczają w niej każdy zasób objęty przestrzenią nazw — z wyjątkiem przestrzeni nazw, którą chart sam przypina, i rodzaju, którego dostawca nie potrafi sklasyfikować. Bez deklaracji tryby się rozchodzą: chart przenoszący przestrzeń nazw wydania umieszcza swoje zasoby w default, podczas gdy wynik synthesized nie zapisuje żadnej, a chart niezapisujący przestrzeni nazw nie umieszcza ich w żadnej, więc trafiają tam, gdzie umieści je narzędzie stosujące manifesty. Lokalne charty dostarczane przez FeatureRecipes biblioteki standardowej odczytują zamiast tego wartość kaskady bezpośrednio przez swoje valuesMapping: pozwala im to pominąć pole, gdy żadna granica nie deklaruje przestrzeni nazw, zgodnie z wynikiem synthesized, czego sama przestrzeń nazw wydania nie może wyrazić, ponieważ nigdy nie jest pusta.

Przykłady

Tryb sourced — encja Recipe wskazująca na dołączony (vendored) chart:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Tryb Workload — encja Recipe deklarująca wbudowaną encję Workload:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

Odsyłacze