WorkloadLibrary
WorkloadLibrary to encja katalogu przechowująca fragmenty szablonów Workload wielokrotnego użytku. Encje Recipes i FeatureRecipes, które wdrażają ten sam kształt obciążenia — serwer udostępniający metryki, zadanie wsadowe, parę sidecarów — deklarują ten kształt raz w bibliotece i odwołują się do niego w momencie użycia za pomocą dyrektywy workload: { $import: ... }. Encja biblioteki należy do poziomu 3: jest opcjonalna dla katalogów, które potrzebują ponownego użycia obciążeń między encjami Recipe. Katalogi, w których każda encja Recipe ma własny, odrębny kształt obciążenia, obywają się bez żadnej encji WorkloadLibrary.
Rola encji WorkloadLibrary
Architekci platformy tworzą encje WorkloadLibraries, aby scentralizować treść encji Workload powtarzającą 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 wykorzystywanej 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łączenia behawioralne. Encje WorkloadLibraries kodują wyłącznie treść encji Workload — kształt obciążenia, który provider syntetyzuje w natywne dla providera manifesty. 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 obciążeń, nigdy nie stykają się z encją biblioteki.
Koperta encji
Encja WorkloadLibrary ma standardową kopertę katalogu. apiVersion: aggrega.ai/v1beta1 i kind: WorkloadLibrary oznaczają rodzaj encji; metadata.name jest identyfikatorem w notacji PascalCase; metadata.version stosuje ścisłe wersjonowanie semantyczne. Oba pola są wymagane. metadata.description, metadata.labels i metadata.annotations są opcjonalne — etykiety i adnotacje to nieprzezroczyste metadane deklarowane przez autora, przenoszone po to, by mogło je dopasowywać to, co odczytuje bibliotekę, a kompilator nie interpretuje ich wartości. Zawartość biblioteki znajduje się pod spec.workloads — wymaganą mapą, która musi deklarować co najmniej jeden wpis.
Koperta jest zamknięta na wszystkich trzech poziomach — korzeń dokumentu, metadata i spec odrzucają klucze, których schemat nie deklaruje.
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Tworzenie wpisów Workload
Każdy wpis to fragment szablonu Go zapisany jako łańcuch YAML. Wyrenderowanym wynikiem wpisu jest cały dokument Workload — zawiera własne apiVersion: aggrega.ai/v1beta1 i kind: Workload — ponieważ pole workload: encji Recipe przyjmuje jeden kompletny dokument Workload, a nie fragment wklejany do otaczającego dokumentu, a import zastępuje całe pole. Wpis MappingLibrary jest całością w ten sam sposób: jego zaimportowanie zastępuje całe valuesMapping: encji Recipe.
Treść jest nieprzezroczysta dla koperty encji. Kompilator przechowuje łańcuch dosłownie podczas ładowania encji WorkloadLibrary i nie parsuje tam szablonu; parser szablonów działa w momencie użycia, gdy encja Recipe lub FeatureRecipe importuje wpis. Przechowywanie fragmentu dosłownie zachowuje wierność zapisu przy ponownej emisji, a ponadto błąd szablonu ujawnia się tam, gdzie wpis jest używany i znany jest jego kontekst filarów, a nie w bibliotece.
Ponieważ dokument Workload jest wielowierszowy, wpisy używają literalnego skalara YAML (|), aby znaki nowego wiersza i wcięcia zachowały się w obiegu:
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]Wartość wpisu musi być skalarem łańcuchowym. Zapisanie mapy lub sekwencji w miejscu treści jest odrzucane — treść wpisu to tekst szablonu, a nie ustrukturyzowany YAML, który kompilator przegląda.
Wewnątrz wpisu 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, a potoki i funkcje działają zgodnie ze standardowym pakietem Go text/template. Kontekst filarów, który wpis może odczytywać — .values, .infra, .locals, .context, .features — jest tym samym kontekstem, który odczytuje każdy szablon Workload, i jest opisany na stronie Workload w części dotyczącej ewaluacji szablonów.
Docelowy dostawca musi obsługiwać syntezę obciążeń. Encja Recipe, która importuje wpis biblioteki, ale jest powiązana z dostawcą niepotrafiącym zsyntetyzować dokumentu Workload, zatrzymuje się z błędem w czasie renderowania, zamiast emitować zdegradowany kształt; katalog biblioteki standardowej deklaruje workloadSchema u dostawców, którzy ją obsługują, jako udokumentowany kontrakt.
Jeden tryb tworzenia
WorkloadLibrary udostępnia jeden tryb tworzenia: szablony Go. spec nie przyjmuje żadnej równoległej powierzchni tworzenia ani furtki zwiększającej ekspresywność na poziomie biblioteki.
Powodem jest jednolitość powierzchni konsumpcji. 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 zaimportowany fragment. Równoległa powierzchnia tworzenia zmuszałaby autorów do przełączania modeli ewaluacji w obrębie renderowania jednej encji Recipe — jeden model dla własnej treści encji Recipe, inny dla każdego zaimportowanego wpisu biblioteki. Zachowanie jednolitej powierzchni oznacza, że autorzy uczą się jednego modelu ewaluacji i stosują go wszędzie.
Autorzy potrzebujący ekspresywności wykraczającej poza słownik 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 przechodzić na drugi język tworzenia wewnątrz biblioteki.
Konwencje nazewnictwa
Nazwy bibliotek i klucze wpisów workload są zapisywane w notacji 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.workloadspasują do tego samego wzorca za pośrednictwempropertyNames.
Encja WorkloadLibrary z kluczem niezgodnym z PascalCase w spec.workloads nie przechodzi walidacji koperty podczas ładowania przestrzeni roboczej. To wymuszanie ma istotne znaczenie: klucze wpisów workload pojawiają się we fragmencie odwołania #/workloads/<name>, więc klucz niezgodny z PascalCase propagowałby się do każdego konsumenta importującego dany wpis.
Jednolite nazewnictwo zapewnia czytelność fragmentu #/workloads/<name>: #/workloads/BatchJob można odczytać na pierwszy rzut oka.
Odwoływanie się do wpisów biblioteki
Autorzy encji Recipe i FeatureRecipe odwołują się do wpisu workload wewnątrz bloku workload: { $import: ... } za pomocą jego tożsamości w postaci samej nazwy:
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"Fragment #/workloads/<name> wybiera wpis i odróżnia odwołanie do workloadu od #/mappings/<name> w encji MappingLibrary oraz #/schemas/<name> w encji SchemaLibrary. Odwołanie nie zawiera hosta rejestru; forma z hostem oci://… jest odrzucana zarówno przez schemat koperty, jak i w miejscu użycia, dzięki czemu fizyczna lokalizacja rejestru nigdy nie trafia do tworzonego źródła. Autor może zadeklarować opcjonalną dolną granicę wersji jako <Library>:<version>#/workloads/<name> — separatorem wersji jest :, zgodnie z mapowaniami recipe/feature i przypięciem w pliku lockfile, a zapis z @ jest odrzucany z diagnostyką wskazującą poprawione odwołanie. Rozstrzygniętą wersję dostarcza plik lockfile dla każdej encji Release, który przypina każdą używaną bibliotekę według nazwy, wersji i skrótu treści; fizyczna lokalizacja jest wiązana w czasie rozstrzygania.
To samo pole workload: przyjmuje dwie inne formy — wbudowany ciąg szablonu Go oraz $import: lokalnej ścieżki pliku względnej wobec katalogu encji Recipe. Trzy formy rozróżnia się po kształcie treści, a wszystkie trzy dają ten sam Workload po parsowaniu. Zob. Recipe, aby dowiedzieć się, jak workload: łączy się z innymi rodzajami danych wejściowych encji Recipe, oraz vocabulary/cross-document-ref, aby poznać szersze rozróżnienie $ref: / $import:.
Kompozycja między bibliotekami
Wpis w encji WorkloadLibrary może być przekierowaniem $import: na poziomie korzenia pola: pierwszym tokenem jego treści jest $import: <Library>#/workloads/<entry>, co zastępuje cały wpis treścią wpisu, do którego się odwołuje — ponowne użycie przez tożsamość, a nie szablonowanie w miejscu. Przekierowanie jest rozwiązywane w momencie użycia, a nie podczas ładowania encji WorkloadLibrary, i jest rozwiązywane rekurencyjnie, więc importowany wpis może sam być przekierowaniem $import: na poziomie korzenia pola. Łańcuch, który zapętla się sam na siebie, zatrzymuje kompilację z diagnostyką wskazującą cykl. $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 wpisu, należy użyć define / template z szablonów Go.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerNieznana nazwa biblioteki oraz nazwa wpisu nieobecna w bibliotece, która daje się rozwiązać, są zgłaszane jako odrębne diagnostyki, dzięki czemu autor może odróżnić brakującą zależność od błędnie zapisanej nazwy wpisu.
Umiejscowienie w poziomach
WorkloadLibrary należy do poziomu 3 w modelu dokumentacji poziomów encji — jest opcjonalna i przeznaczona dla katalogów, które potrzebują ponownego użycia treści workload w wielu encjach Recipe. Katalogi, których Recipes zawierają własną, odrębną treść workload, są dostarczane bez żadnej encji WorkloadLibrary; oznaczenie poziomu sygnalizuje „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji po dokumentacji, a nie możliwości. Kompilator traktuje WorkloadLibrary tak samo jak pozostałe rodzaje encji katalogu: ta sama walidacja koperty przy ładowaniu przestrzeni roboczej, ten sam potok publikacji OCI w czasie wydania, to samo przypinanie w pliku lockfile według nazwy, wersji i skrótu treści.
Ten rodzaj biblioteki jest jednym z zestawu na poziomie katalogu — SchemaLibrary przechowuje definicje schematów wielokrotnego użytku, MappingLibrary przechowuje fragmenty mapowań wielokrotnego użytku, ArtifactLibrary przechowuje pakiety artefaktów wielokrotnego użytku, a WorkloadLibrary przechowuje treść workload wielokrotnego użytku. Każda z nich jest opcjonalna niezależnie od pozostałych; katalogi dostarczają te, których potrzebują, i żadnych innych.
Czym WorkloadLibrary nie jest
Kilka częstych nieporozumień, którym warto zapobiec:
-
Nie zastępuje wbudowanego
workload:. Większość encji Recipes zawiera treść workloadu na tyle specyficzną, że należy ją umieścić bezpośrednio w miejscu użycia, gdzie autor czyta ją razem z resztą encji Recipe. Encja WorkloadLibrary przydaje się wtedy, gdy TEN SAM kształt workloadu pojawia się w wielu encjach Recipes; w przypadku jednorazowej treści właściwym wyborem jest tworzenie jej bezpośrednio w miejscu użycia. -
Nie jest miejscem na częściowe fragmenty. Wpis renderuje się do kompletnego dokumentu Workload. Dokument values encji Recipe należy do encji MappingLibrary, zestaw plików pomocniczych do encji ArtifactLibrary, a definicje schematów do encji SchemaLibrary. Rodzaje bibliotek dzielą się według typu treści, a nie według wzorca ponownego użycia.
-
Nie jest encją wdrażaną samodzielnie. Wpis biblioteki to treść Workload, a treść Workload nigdy nie jest adresowalna samodzielnie — istnieje jako dane wejściowe, które konsumuje encja Recipe lub FeatureRecipe. Opublikowanie encji WorkloadLibrary sprawia, że jej wpisy można importować; nie sprawia, że można je wdrażać.
-
Nie zapewnia parametrycznego ponownego użycia wykraczającego poza mechanizmy szablonów Go. Autorzy potrzebujący zmienności parametrycznej używają mechanizmów
{{ define }}+{{ template }}szablonów Go wewnątrz wpisów biblioteki albo kontekstu filarów, który dostarcza konsumująca encja Recipe. Sama encja biblioteki nie zawiera żadnych mechanizmów pomocniczych do parametryzacji.