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:
aggrega scaffold --example mariadb-adminerDanach gibt er die als Nächstes auszuführenden Befehle aus:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlDie 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/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 }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/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 -}}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/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 }}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/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"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.