Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Librerie condivise di schemi e di mapping: un Component MariaDB

Questa pagina spiega un’idea, tenere la maggior parte dello schema di un Component e del mapping di una Recipe in librerie che più entità condividono, e non è un workspace eseguibile. MariaDB + Adminer — un esempio eseguibile a doppio target compone le impostazioni di archiviazione del suo database da una libreria di schemi; scrivilo in una tua cartella con:

Terminal window
aggrega scaffold --example mariadb-adminer

Poi stampa i prossimi comandi da eseguire:

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

Le entità di questa pagina sono un tuo catalogo, nel namespace my-org; la forma di ciascuna è quella che assumono un Component MariaDB di livello produzione, la sua Recipe e le due librerie che li sostengono.

Una libreria di schemi contiene la forma

Una SchemaLibrary dichiara schemi con nome, scritti nella forma compatta — una riga per campo, con il suo tipo, i vincoli e il valore predefinito — che la build compila in JSON Schema 2020-12 prima che qualsiasi valore venga verificato rispetto a essi. Un estratto:

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 }

Un riferimento nomina la libreria con il suo metadata.name — Datastores#/schemas/<entry> — mai con il luogo in cui la libreria è archiviata, anche all’interno della libreria, così lo stesso riferimento si risolve sia che la libreria si trovi nel catalogo del workspace sia che sia pubblicata in un registry. validate: e validateMessage: aggiungono una verifica propria di un campo; when: rende condizionale un intero oggetto, così i vincoli del pool secondario valgono solo dove l’architettura si risolve in replication. Un $ref: tra documenti ammette accanto a sé solo properties, required e description, ed è per questo che il pool secondario è scritto per esteso invece di fare riferimento a NodePool.

Il Component vi fa riferimento

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

Il pilastro values è una sola riga $ref:; i piccoli infra e provides, specifici del Component, restano inline. Le asserzioni contengono regole del contratto del Component che nessuna parola chiave di schema esprime, qualunque sia la Recipe che lo realizza.

Una libreria di mapping contiene la traduzione

Una MappingLibrary contiene frammenti di template che una Recipe importa. Una voce produce i values di un chart, e dichiara con define un template di supporto che invoca con template per ogni node pool:

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

Il template di supporto è dichiarato dentro la voce che lo usa, perché una Recipe importa una sola voce e una definizione viaggia con la voce che la contiene. Il frammento è valutato dal renderer di Aggrega, quindi usa le funzioni di Sprig e optional di Aggrega per una chiave che può essere assente (vedi sprig-functions.md); include di Helm non è tra queste, e template scrive il suo output esattamente dove si trova.

La Recipe la importa

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"

La Recipe è piccola: il mapping vive nella libreria, e la Recipe conserva ciò che è suo — il chart che renderizza e l’indirizzo che pubblica. Poiché il mapping fissa il fullnameOverride del chart a .context.rendered_name, la Recipe può calcolare il nome del Service del primario invece di presumerlo.

Che cosa offrono le librerie

In JSON Schema, la mappa di una riga di ciascun campo diventa un blocco annidato e ogni oggetto aggiunge type: object, properties: e un elenco required:; when: e validate: non hanno una parola chiave JSON Schema propria. La forma compatta copre tutto ciò di cui questo Component ha bisogno, senza la via d’uscita $jsonschema:. Il risparmio cresce con la condivisione: la libreria si scrive una volta, e il pilastro values di ogni ulteriore Component è una sola riga $ref:.

I riferimenti: scrittura in forma compatta, $ref: tra documenti, il blocco delle asserzioni, SchemaLibrary e MappingLibrary.