Współdzielone biblioteki schematów i mapowań: encja Component dla MariaDB
Ta strona wyjaśnia jedną ideę, trzymanie większości schematu encji Component i mapowania encji Recipe w bibliotekach współdzielonych przez wiele encji, i nie jest uruchamialną przestrzenią roboczą. MariaDB + Adminer — uruchamialny przykład z dwoma celami składa ustawienia przechowywania swojej bazy danych z biblioteki schematów; można go zapisać we własnym folderze poleceniem:
aggrega scaffold --example mariadb-adminerNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlEncje na tej stronie tworzą własny katalog, w przestrzeni nazw my-org; każda ma taki kształt, jaki przyjmują produkcyjna encja Component dla MariaDB, jej encja Recipe i dwie stojące za nimi biblioteki.
Biblioteka schematów przechowuje kształt
Encja SchemaLibrary deklaruje nazwane schematy, zapisane w zwartej formie — jeden wiersz na pole, z jego typem, ograniczeniami i wartością domyślną — które build kompiluje do JSON Schema 2020-12, zanim jakakolwiek wartość zostanie względem nich sprawdzona. Fragment:
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: Datastores version: 1.0.0spec: schemas: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } NodePool: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "Datastores#/schemas/PodResources" } MariaDBPayload: architecture: { type: string, enum: [standalone, replication], default: standalone } image: tag: { type: string, validate: '{{ ne . "latest" }}', validateMessage: "image.tag must name a version: latest moves with every chart release" } primary: { $ref: "Datastores#/schemas/NodePool", required: true } secondary: when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 }Odwołanie wskazuje bibliotekę przez jej metadata.name — Datastores#/schemas/<entry> — a nigdy przez miejsce, w którym biblioteka jest przechowywana, również wewnątrz biblioteki, dzięki czemu to samo odwołanie jest rozwiązywane niezależnie od tego, czy biblioteka znajduje się w katalogu przestrzeni roboczej, czy jest opublikowana w rejestrze. validate: i validateMessage: dodają własne sprawdzenie pola; when: czyni warunkowym cały obiekt, dzięki czemu ograniczenia puli pomocniczej obowiązują tylko tam, gdzie architektura rozwiązuje się do replication. Odwołanie $ref: między dokumentami dopuszcza obok siebie tylko properties, required i description, dlatego pula pomocnicza jest wypisana w całości zamiast odwoływać się do NodePool.
Encja Component się do niej odwołuje
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: my-org/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: $ref: Datastores#/schemas/MariaDBPayload infra: cpu_arch: { type: string, enum: [amd64, arm64], default: amd64 } provides: host: { type: string, format: hostname } port: { type: integer, min: 1024, max: 65535 } featuresSchema: root_credentials: required: true inject: [] replication_credentials: required: false inject: [] assertions: replication-needs-credentials: | {{- if eq .values.architecture "replication" -}} {{- if not (hasKey .features "replication_credentials") -}} {{- fail "architecture=replication requires replication_credentials secret to be supplied" -}} {{- end -}} {{- end -}}Filar values to jeden wiersz $ref:; niewielkie, specyficzne dla encji Component infra i provides pozostają inline. Asercje zawierają reguły kontraktu encji Component, których nie wyraża żadne słowo kluczowe schematu, niezależnie od tego, która encja Recipe ją realizuje.
Biblioteka mapowań przechowuje tłumaczenie
Encja MappingLibrary przechowuje fragmenty szablonów, które importuje encja Recipe. Jeden wpis renderuje wartości chartu i deklaruje za pomocą define szablon pomocniczy, który wywołuje za pomocą template dla każdej puli węzłów:
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BitnamiHelpers version: 1.0.0spec: mappings: MariaDBBitnamiCore: | {{- define "BitnamiNodePool" }} resources: requests: cpu: {{ .pool.resources.requests.cpu | quote }} memory: {{ .pool.resources.requests.memory | quote }} {{- end }} {{- with .values -}} fullnameOverride: {{ $.context.rendered_name | quote }} architecture: {{ .architecture }} primary: name: primary {{- template "BitnamiNodePool" (dict "pool" .primary) }} {{- end }}Szablon pomocniczy jest zadeklarowany wewnątrz wpisu, który go używa, ponieważ encja Recipe importuje jeden wpis, a definicja podróżuje razem z wpisem, który ją zawiera. Fragment jest ewaluowany przez renderer Aggrega, więc używa funkcji Sprig oraz funkcji Aggrega optional dla klucza, który może nie istnieć (zob. sprig-functions.md); funkcja Helm include do nich nie należy, a template zapisuje swój wynik dokładnie w miejscu, w którym stoi.
Encja Recipe ją importuje
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: my-org/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore provides: host: "{{ .context.rendered_name }}{{ if eq .values.architecture `replication` }}-primary{{ end }}" port: "3306"Encja Recipe jest mała: mapowanie znajduje się w bibliotece, a encja Recipe zachowuje to, co do niej należy — chart, który renderuje, i adres, który publikuje. Ponieważ mapowanie ustala fullnameOverride chartu na .context.rendered_name, encja Recipe może obliczyć nazwę obiektu Service węzła głównego, zamiast ją zakładać.
Co dają biblioteki
W JSON Schema jednowierszowa mapa każdego pola staje się zagnieżdżonym blokiem, a każdy obiekt dodaje type: object, properties: i listę required:; when: i validate: nie mają własnego słowa kluczowego w JSON Schema. Zwarta forma obejmuje wszystko, czego potrzebuje ta encja Component, bez furtki $jsonschema:. Oszczędność rośnie wraz ze współdzieleniem: bibliotekę pisze się raz, a filar values każdej kolejnej encji Component to jeden wiersz $ref:.
Dokumentacja: tworzenie w zwartej formie, $ref: między dokumentami, blok asercji, SchemaLibrary i MappingLibrary.