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

ArtifactLibrary

ArtifactLibrary to encja katalogu, która przechowuje wielokrotnego użytku pakiety artefaktów — nazwane zestawy pomocniczych plików wyjściowych, które należą do siebie. Encje Recipes i FeatureRecipes, które emitują te same zasoby pomocnicze — CRD wraz z jego RBAC i ConfigMap, NetworkPolicy w parze z HPA — deklarują taki zestaw raz w bibliotece i odwołują się do niego w momencie użycia przez wpis artifacts:, którego wartością jest dyrektywa $import:. Encja biblioteki należy do poziomu 3: jest opcjonalna i przeznaczona dla katalogów, które potrzebują ponownego użycia artefaktów w wielu encjach Recipe. Katalogi, w których każda encja Recipe ma własne pliki pomocnicze, obywają się bez żadnej encji ArtifactLibrary.

Rola encji ArtifactLibrary

Architekci platformy tworzą encje ArtifactLibraries, aby scentralizować pomocnicze manifesty, które powtarzają się w encjach Recipes i FeatureRecipes katalogu. Biblioteka nie jest instrukcją budowania przeznaczoną do wdrożenia; jest przestrzenią nazw definicji. Autorzy encji Recipe i FeatureRecipe odwołują się do pakietu za pomocą dyrektywy $import:, zapisanej raz i wykorzystywanej wszędzie tam, gdzie import zostanie rozwiązany.

Ten rodzaj biblioteki odróżnia od pozostałych trzech granulacja wpisu. Wpis w encji SchemaLibrary to jeden schemat, wpis w encji MappingLibrary to jeden fragment szablonu, a wpis w encji WorkloadLibrary to jeden dokument Workload — każdy z nich to pojedyncza treść wykorzystywana w jednym miejscu. Wpis w encji ArtifactLibrary to zestaw plików, ponieważ grupowane przez niego zasoby są użyteczne tylko razem: zaimportowanie CRD bez jego RBAC daje zestaw manifestów, który nie działa. Dlatego jednostką ponownego użycia jest pakiet, a jedno miejsce wykorzystania rozwija się w kilka plików wyjściowych.

Koperta encji

Encja ArtifactLibrary ma standardową kopertę katalogu. apiVersion: aggrega.ai/v1beta1 i kind: ArtifactLibrary 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ę w spec.artifacts, wymaganej mapie, która musi deklarować co najmniej jeden pakiet.

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: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
artifacts:
OperatorSupport:
crd.yaml: |
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
rbac.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: "{{ .context.instance_id }}-operator"
rules:
- apiGroups: ["platform.example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch"]

Tworzenie pakietów artefaktów

spec.artifacts ma dwa poziomy zagnieżdżenia, a każdy poziom pełni odrębną funkcję. Klucz zewnętrzny to nazwa pakietu — identyfikator, do którego odwołuje się konsument. Klucze wewnętrzne to nazwy plików, a każda wartość wewnętrzna to treść szablonu Go emitowana do danego pliku. Pakiet musi deklarować co najmniej jeden plik.

spec:
artifacts:
NetworkBaseline:
deny-all.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-deny-all"
spec:
podSelector: {}
policyTypes: ["Ingress"]
allow-dns.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-allow-dns"

Treść pliku to fragment szablonu Go zapisany jako ciąg znaków YAML. Ponieważ manifest jest wielowierszowy, treści plików korzystają z dosłownego skalara YAML (|), dzięki czemu znaki nowego wiersza i wcięcia zachowują się bez zmian w obie strony. Wartość wpisu pakietu musi być mapowaniem nazwy pliku na treść w postaci ciągu znaków; zapisanie samego ciągu znaków lub sekwencji w miejscu pakietu jest odrzucane — poziomem importowanym przez konsumenta jest pakiet, a nie pojedynczy plik.

Treść jest nieprzezroczysta dla koperty encji. Kompilator przechowuje każdy ciąg znaków dosłownie podczas ładowania encji ArtifactLibrary i nie parsuje w tym miejscu szablonu; parser szablonów działa w momencie konsumpcji, gdy encja Recipe lub FeatureRecipe importuje pakiet. Dosłowne przechowywanie treści zachowuje wierność zapisu przy ponownej emisji, a ponadto sprawia, że błąd szablonu ujawnia się tam, gdzie pakiet jest konsumowany i znany jest jego kontekst filarów, a nie w bibliotece.

Kolejność plików w pakiecie jest kolejnością, w jakiej zapisał je autor, i jest zachowywana podczas ładowania i konsumpcji, dzięki czemu emitowany zbiór jest stabilny między kolejnymi kompilacjami.

W treści pliku dostępny jest pełny zasób środków kompozycji szablonów Go: {{ define "name" }}...{{ end }} deklaruje bloki wielokrotnego użytku, {{ template "name" . }} je wywołuje, a potoki i funkcje działają zgodnie ze standardowym pakietem Go text/template. Kontekst filarów, który może odczytywać treść pliku — .values, .infra, .locals, .context, .features oraz .workload i .source tam, gdzie konsumująca encja Recipe je deklaruje — to ten sam kontekst, który odczytują własne wpisy artifacts: konsumującej encji Recipe, opisany na stronie Recipe w sekcji pola artifacts:. Treść odczytująca .workload, gdy konsumująca encja Recipe nie deklaruje workload:, lub .source, gdy nie deklaruje source:, zatrzymuje kompilację z diagnostyką wskazującą odwołanie, którego nie udało się spełnić — każdy filar jest sprawdzany osobno, więc zadeklarowanie jednego nie uprawnia do odczytu drugiego.

Jeden tryb tworzenia

ArtifactLibrary udostępnia jeden tryb tworzenia: szablony Go. spec nie przyjmuje równoległej powierzchni tworzenia ani żadnej furtki dla ekspresywności 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 importowany pakiet. Równoległa powierzchnia tworzenia zmuszałaby autorów do przełączania modeli ewaluacji w ramach renderowania jednej encji Recipe — jeden model dla własnej treści encji Recipe, inny dla każdego importowanego pakietu. Zachowanie jednolitej powierzchni oznacza, że autorzy uczą się jednego modelu ewaluacji i stosują go wszędzie.

Autorzy, którzy potrzebują 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ą pakiety biblioteki własną, merytoryczną zmiennością — zamiast przechodzić na drugi język tworzenia wewnątrz biblioteki.

Konwencje nazewnictwa

Nazwy bibliotek i nazwy pakietów stosują 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.artifacts pasują do tego samego wzorca za pomocą propertyNames.

Encja ArtifactLibrary z nazwą pakietu niezgodną z PascalCase nie przechodzi walidacji koperty podczas ładowania przestrzeni roboczej. To wymuszenie ma znaczenie nośne: nazwy pakietów pojawiają się we fragmencie odwołania #/artifacts/<name>, więc nazwa niezgodna z PascalCase rozprzestrzeniłaby się na każdego konsumenta importującego pakiet.

Jednolitość nazewnictwa zapewnia czytelność fragmentu #/artifacts/<name>: #/artifacts/OperatorSupport można odczytać na pierwszy rzut oka.

Nazwy plików wewnątrz pakietu są dowolne, o ile każda z nich wskazuje plik. Nie stosują PascalCase i nie ogranicza ich żaden wzorzec schematu, ponieważ nazywają pliki, które ostatecznie trafiają do wyniku budowania — crd.yaml, deny-all.yaml, values-override.json są poprawne. Nazwa pliku musi być zwykłą względną nazwą pliku, zapisaną wprost; budowanie odrzuca nazwę, która nie wskazuje własnego pliku, jak opisano w sekcji Odwoływanie się do wpisów biblioteki. Oba poziomy są ograniczane inaczej, ponieważ służą różnym odbiorcom: nazwa pakietu jest identyfikatorem, do którego odwołują się inne encje, a nazwy plików to nazwy, które konsument widzi w katalogu, pod którym pakiet jest importowany.

Odwoływanie się do wpisów biblioteki

Autorzy encji Recipe i FeatureRecipe odwołują się do pakietu we wpisie artifacts:, którego wartością jest mapa $import:, za pomocą tożsamości pakietu w postaci samej nazwy:

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

Fragment #/artifacts/<name> wybiera pakiet i odróżnia odwołanie do artefaktów od #/mappings/<name> encji MappingLibrary, #/schemas/<name> encji SchemaLibrary oraz #/workloads/<name> encji WorkloadLibrary. Odwołanie nie zawiera hosta rejestru; forma oci://… zawierająca host 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 określić opcjonalną minimalną wersję jako <Library>:<version>#/artifacts/<name> — separatorem wersji jest :, zgodnie z pozostałymi rodzajami bibliotek i przypięciem w pliku blokady, a zapis z @ jest odrzucany z komunikatem diagnostycznym podającym poprawione odwołanie. Rozwiązana wersja pochodzi z pliku blokady danej encji Release, który przypina każdą używaną bibliotekę według nazwy, wersji i skrótu zawartości; fizyczna lokalizacja jest wiązana w czasie rozwiązywania.

Pakiet jest właścicielem nazw swoich plików, a klucz konsumujący jest właścicielem katalogu, do którego one trafiają. Jeden wpis artifacts: importujący pakiet rozwija się w jeden wynik na każdy plik w tym pakiecie, każdy zagnieżdżony pod kluczem użycia jako <key>/<filename>. Klucz w miejscu użycia — powyżej operator-support — nazywa całe użycie, a nie pojedynczy plik; przykład emituje operator-support/crd.yaml i operator-support/rbac.yaml. Nazwa pakietu jest więc wybierana pod kątem czytelności w odwołaniu, nazwy plików pod kątem czytelnika katalogu wyjściowego, i żadna nie musi być zgodna z drugą. Sam klucz użycia jest ograniczony do pojedynczej nazwy pliku — na początku litera lub cyfra, dalej litery, cyfry, kropki, myślniki i podkreślenia, przy czym klucz spoza tego alfabetu nie przechodzi walidacji koperty — dzięki czemu nazywa dokładnie jeden segment katalogu, a wszystko poniżej tego segmentu pochodzi z pakietu. To pozwala, by nazwy plików pakietu pozostały dowolne, a klucz ścisły: nazwa pliku jest unikalna w obrębie pakietu, klucz jest unikalny w obrębie dokumentu, a klucz jest pierwszym segmentem każdej ścieżki emitowanej przez wpis, więc żadne dwa wpisy artifacts: nie nazywają tego samego wyniku. Dowolność oznacza swobodę w obrębie tego segmentu: nazwa pliku może zawierać własny zagnieżdżony układ — crds/widget.yaml trafia do <key>/crds/widget.yaml — ale musi być zwykłą względną nazwą pliku pod kluczem, zapisaną wprost, a nazwa pliku, która nią nie jest, zatrzymuje budowanie zamiast umieszczać plik w miejscu, którego konsumująca encja Recipe nigdy nie wskazała. Odrzucane są więc: nazwa wychodząca ponad klucz lub wskazująca lokalizację bezwzględną; . lub ./ oraz nazwa sprowadzająca się z powrotem do klucza, taka jak x/.., które wskazują własny katalog klucza, a nie plik w nim; a także nazwa z końcowym lub podwójnym / albo z częścią . lub .. — x/, a//b, ./a, a/../b — będąca drugim zapisem pliku, który może nosić inna nazwa, tak że a//b obok a/b umieściłoby dwa pliki pod jedną ścieżką. Komunikat diagnostyczny podaje plik pakietu i klucz, pod którym został zaimportowany. Dwa wyniki, które faktycznie mają tę samą nazwę pliku, zatrzymują budowanie podczas renderowania węzła, co ma miejsce, gdy dwa różne rodzaje wejść dostarczają tę samą nazwę pliku. Zobacz Recipe, aby dowiedzieć się, jak artifacts: łączy się z innymi rodzajami wejść encji Recipe oraz poznać dwa tryby tworzenia niekorzystające z bibliotek, a także vocabulary/cross-document-ref, aby poznać szersze rozróżnienie między $ref: a $import:.

Kompozycja między bibliotekami

Treść pliku pakietu jest treścią końcową. W odróżnieniu od wpisu MappingLibrary lub WorkloadLibrary plik pakietu nie może być przekierowaniem $import: na poziomie korzenia pola: pojedyncze miejsce na plik nie pomieści kilku plików, które wniósłby inny pakiet, dlatego kompilator odrzuca taki kształt, zamiast rozwiązywać go w coś, czego autor nie napisał. Treść, której pierwszym tokenem jest $import:, zatrzymuje kompilację z diagnostyką wskazującą pakiet i plik.

Kompozycja odbywa się natomiast w miejscu użycia, gdzie jest na nią miejsce. Encja Recipe, która potrzebuje dwóch pakietów, deklaruje dwa wpisy artifacts:, a każdy z nich rozwija się niezależnie:

# Inside a Recipe's spec — compose bundles where the outputs land:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"
network-baseline:
$import: "PlatformArtifacts#/artifacts/NetworkBaseline"

Nieznana nazwa biblioteki oraz nazwa pakietu nieobecna w bibliotece, która się rozwiązuje, są zgłaszane jako odrębne diagnostyki, dzięki czemu autor może odróżnić brakującą zależność od błędnie zapisanej nazwy pakietu.

Umiejscowienie w poziomach

ArtifactLibrary to poziom 3 w modelu dokumentacji poziomów encji — opcjonalny, przeznaczony dla katalogów, które potrzebują ponownego użycia artefaktów między wieloma encjami Recipe. Katalogi, których Recipes zawierają własne pliki pomocnicze, są dostarczane bez żadnej encji ArtifactLibrary; oznaczenie poziomu sygnalizuje „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji po dokumentacji, a nie możliwości. Kompilator traktuje ArtifactLibrary jednolicie z pozostałymi rodzajami encji katalogu: ta sama walidacja koperty przy wczytywaniu przestrzeni roboczej, ten sam potok publikacji OCI w momencie wydania, to samo przypinanie w pliku blokady według nazwy, wersji i skrótu treści.

Ten rodzaj biblioteki uzupełnia zestaw na poziomie katalogu — SchemaLibrary przechowuje definicje schematów wielokrotnego użytku, MappingLibrary przechowuje fragmenty mapowań wielokrotnego użytku, WorkloadLibrary przechowuje treść obciążeń wielokrotnego użytku, a ArtifactLibrary przechowuje pakiety artefaktów wielokrotnego użytku. Każda z nich jest niezależnie opcjonalna; katalogi dostarczają te, których potrzebują, i żadnych innych.

Czym ArtifactLibrary nie jest

Kilka częstych nieporozumień, którym warto zapobiec:

  • Nie zastępuje wbudowanego artifacts:. Większość encji Recipes zawiera pliki pomocnicze na tyle specyficzne, że ich miejsce jest bezpośrednio w definicji, gdzie autor czyta je razem z resztą encji Recipe. ArtifactLibrary przydaje się wtedy, gdy TEN SAM zestaw plików towarzyszy wielu encjom Recipes; w przypadku jednorazowej treści właściwym wyborem jest definiowanie bezpośrednio w miejscu użycia.

  • Nie służy do zmiany nazw plików wewnątrz pakietu. Nazwy plików należą do pakietu. Konsument wybiera katalog, w którym pliki się znajdą — do tego służy klucz konsumpcji — ale nie nazwę żadnego z nich: konsument, który potrzebuje innej nazwy pliku, albo używa pakietu, który ją deklaruje, albo definiuje plik bezpośrednio w miejscu użycia.

  • Nie jest miejscem na treść workloadów, mapowań ani schematów. Dokument Workload należy umieścić w encji WorkloadLibrary, dokument wartości encji Recipe — w encji MappingLibrary, a definicje schematów — w encji SchemaLibrary. Rodzaje bibliotek dzielą się według typu treści, a nie według wzorca ponownego użycia.

  • Nie jest mechanizmem dla zasobów przekrojowych. Zasoby pomocnicze dotyczące wielu komponentów niezależnie od tego, która encja Recipe je realizuje — np. sidecar kopii zapasowych dołączany do każdego magazynu danych — należą do generowania zasobów w encji FeatureRecipe, która dołącza je według encji Feature, a nie według encji Recipe. Zob. entities/featurerecipe.md. ArtifactLibrary wyodrębnia pliki, które kilka encji Recipes emituje każda we własnym imieniu.

  • Nie jest encją wdrażaną niezależnie. Pakiet to treść artefaktów, a treść artefaktów nigdy nie jest adresowalna samodzielnie — istnieje jako dane wejściowe, które konsumuje encja Recipe lub FeatureRecipe. Opublikowanie encji ArtifactLibrary sprawia, że jej pakiety można importować; nie sprawia, że można je wdrażać.