Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Gemeinsame Schema- und Mapping-Bibliotheken: eine MariaDB-Component

Diese Seite erklärt eine Idee, nämlich den Großteil des Schemas einer Component und des Mappings eines Recipe in Bibliotheken zu halten, die mehrere Entitäten teilen, und ist kein ausführbarer Workspace. MariaDB + Adminer — ein ausführbares Beispiel mit zwei Zielen setzt die Speichereinstellungen seiner Datenbank aus einer Schema-Bibliothek zusammen; schreiben Sie es mit folgendem Befehl in einen eigenen Ordner:

Terminal window
aggrega scaffold --example mariadb-adminer

Danach gibt er die als Nächstes auszuführenden Befehle aus:

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

Die Entitäten auf dieser Seite bilden einen eigenen Katalog, im Namespace my-org; jede hat die Form, die eine produktionsreife MariaDB-Component, ihr Recipe und die beiden Bibliotheken dahinter annehmen.

Eine Schema-Bibliothek enthält die Form

Eine SchemaLibrary deklariert benannte Schemas, geschrieben in der kompakten Form — eine Zeile pro Feld, mit Typ, Einschränkungen und Standardwert —, die der Build zu JSON Schema 2020-12 kompiliert, bevor irgendein Wert dagegen geprüft wird. Ein Auszug:

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 }

Ein Verweis benennt die Bibliothek über ihren metadata.name — Datastores#/schemas/<entry> — und nie danach, wo die Bibliothek gespeichert ist, auch innerhalb der Bibliothek, sodass derselbe Verweis aufgelöst wird, ob die Bibliothek im Katalog des Workspace liegt oder in einer Registry veröffentlicht ist. validate: und validateMessage: fügen eine eigene Prüfung eines Felds hinzu; when: macht ein ganzes Objekt bedingt, sodass die Einschränkungen des sekundären Pools nur gelten, wo die Architektur zu replication aufgelöst wird. Ein dokumentübergreifendes $ref: erlaubt neben sich nur properties, required und description, weshalb der sekundäre Pool ausgeschrieben ist, statt auf NodePool zu verweisen.

Die Component verweist darauf

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 -}}

Die Säule values ist eine einzige Zeile $ref:; die kleinen, Component-spezifischen infra und provides bleiben inline. Die Zusicherungen halten Regeln des Vertrags der Component fest, die kein Schema-Schlüsselwort ausdrückt, welches Recipe sie auch realisiert.

Eine Mapping-Bibliothek enthält die Übersetzung

Eine MappingLibrary enthält Template-Fragmente, die ein Recipe importiert. Ein Eintrag rendert die Values eines Charts und deklariert mit define ein Hilfs-Template, das er mit template für jeden Node-Pool aufruft:

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 }}

Das Hilfs-Template ist innerhalb des Eintrags deklariert, der es verwendet, weil ein Recipe einen einzelnen Eintrag importiert und eine Definition mit dem Eintrag reist, der sie enthält. Das Fragment wird vom Renderer von Aggrega ausgewertet, daher verwendet es die Funktionen von Sprig und das optional von Aggrega für einen Schlüssel, der fehlen kann (siehe sprig-functions.md); das include von Helm gehört nicht dazu, und template schreibt seine Ausgabe genau dort, wo es steht.

Das Recipe importiert sie

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"

Das Recipe ist klein: Das Mapping liegt in der Bibliothek, und das Recipe behält, was ihm gehört — das Chart, das es rendert, und die Adresse, die es veröffentlicht. Weil das Mapping das fullnameOverride des Charts auf .context.rendered_name festlegt, kann das Recipe den Service-Namen des primären Knotens berechnen, statt ihn anzunehmen.

Was die Bibliotheken bringen

In JSON Schema geschrieben, wird die einzeilige Map jedes Felds zu einem verschachtelten Block, und jedes Objekt fügt type: object, properties: und eine Liste required: hinzu; when: und validate: haben kein eigenes JSON-Schema-Schlüsselwort. Die kompakte Form deckt alles ab, was diese Component braucht, ohne den Ausweg $jsonschema:. Die Ersparnis wächst mit der gemeinsamen Nutzung: Die Bibliothek wird einmal geschrieben, und die Säule values jeder weiteren Component ist eine einzige Zeile $ref:.

Die Referenzen: Erstellung in kompakter Form, dokumentübergreifendes $ref:, der Zusicherungsblock, SchemaLibrary und MappingLibrary.