Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Bibliothèques partagées de schémas et de mappings : un Component MariaDB

Cette page explique une idée, conserver l’essentiel du schéma d’un Component et du mapping d’une Recipe dans des bibliothèques que plusieurs entités partagent, et n’est pas un espace de travail exécutable. MariaDB + Adminer — un exemple exécutable à double cible compose les paramètres de stockage de sa base de données à partir d’une bibliothèque de schémas ; écrivez-le dans un dossier à vous avec :

Terminal window
aggrega scaffold --example mariadb-adminer

Elle affiche ensuite les prochaines commandes à exécuter :

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

Les entités de cette page forment un catalogue à vous, dans le namespace my-org ; la forme de chacune est celle que prennent un Component MariaDB de niveau production, sa Recipe et les deux bibliothèques qui les sous-tendent.

Une bibliothèque de schémas porte la forme

Une SchemaLibrary déclare des schémas nommés, écrits dans la forme compacte — une ligne par champ, avec son type, ses contraintes et sa valeur par défaut — que le build compile en JSON Schema 2020-12 avant qu’une quelconque valeur soit vérifiée par rapport à eux. Un extrait :

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 }

Une référence nomme la bibliothèque par son metadata.name — Datastores#/schemas/<entry> — et jamais par l’endroit où la bibliothèque est stockée, y compris à l’intérieur de la bibliothèque, si bien que la même référence se résout que la bibliothèque se trouve dans le catalogue de l’espace de travail ou qu’elle soit publiée dans un registre. validate: et validateMessage: ajoutent une vérification propre à un champ ; when: rend conditionnel un objet entier, si bien que les contraintes du pool secondaire ne s’appliquent que là où l’architecture se résout en replication. Un $ref: inter-documents n’admet à côté de lui que properties, required et description, et c’est pourquoi le pool secondaire est écrit en entier au lieu de faire référence à NodePool.

Le Component y fait référence

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

Le pilier values tient en une ligne $ref: ; les petits infra et provides, propres au Component, restent en ligne. Les assertions portent des règles du contrat du Component qu’aucun mot-clé de schéma n’exprime, quelle que soit la Recipe qui le réalise.

Une bibliothèque de mappings porte la traduction

Une MappingLibrary contient des fragments de template qu’une Recipe importe. Une entrée rend les values d’un chart et déclare avec define un template auxiliaire qu’elle invoque avec template pour chaque 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 }}

Le template auxiliaire est déclaré dans l’entrée qui l’utilise, car une Recipe importe une seule entrée et une définition voyage avec l’entrée qui la contient. Le fragment est évalué par le moteur de rendu d’Aggrega, si bien qu’il utilise les fonctions de Sprig et optional d’Aggrega pour une clé qui peut être absente (voir sprig-functions.md) ; le include de Helm n’en fait pas partie, et template écrit sa sortie exactement là où il se trouve.

La Recipe l’importe

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 est petite : le mapping vit dans la bibliothèque, et la Recipe garde ce qui lui est propre — le chart qu’elle rend et l’adresse qu’elle publie. Comme le mapping fixe le fullnameOverride du chart à .context.rendered_name, la Recipe peut calculer le nom du Service du primaire au lieu de le supposer.

Ce qu’apportent les bibliothèques

En JSON Schema, la map d’une ligne de chaque champ devient un bloc imbriqué et chaque objet ajoute type: object, properties: et une liste required: ; when: et validate: n’ont pas de mot-clé JSON Schema qui leur soit propre. La forme compacte couvre tout ce dont ce Component a besoin, sans la porte de sortie $jsonschema:. Le gain croît avec le partage : la bibliothèque est écrite une fois, et le pilier values de chaque Component supplémentaire tient en une seule ligne $ref:.

Les références : écriture en forme compacte, $ref: inter-documents, le bloc d’assertions, SchemaLibrary et MappingLibrary.