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

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:

Terminal window
aggrega scaffold --example mariadb-adminer

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności:

Terminal window
cd mariadb-adminer
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.yaml

Encje 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/v1beta1
kind: SchemaLibrary
metadata:
name: Datastores
version: 1.0.0
spec:
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/v1beta1
kind: Component
metadata:
name: my-org/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
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/v1beta1
kind: MappingLibrary
metadata:
name: BitnamiHelpers
version: 1.0.0
spec:
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/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
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.