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

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/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
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.name pasuje do ^[A-Z][A-Za-z0-9]*$.
  • Klucze mapy spec.workloads pasują do tego samego wzorca za pośrednictwem propertyNames.

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/MetricsServer

Nieznana 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.