Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Bibliotecas compartidas de esquemas y de mapeos: un Component de MariaDB

Esta página explica una idea, mantener la mayor parte del esquema de un Component y del mapeo de una Recipe en bibliotecas que comparten varias entidades, y no es un espacio de trabajo ejecutable. MariaDB + Adminer — un ejemplo ejecutable con dos destinos compone los ajustes de almacenamiento de su base de datos a partir de una biblioteca de esquemas; escríbelo en una carpeta propia con:

Terminal window
aggrega scaffold --example mariadb-adminer

Después imprime los comandos que hay que ejecutar a continuación:

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

Las entidades de esta página son un catálogo propio, en el namespace my-org; la forma de cada una es la que adoptan un Component de MariaDB apto para producción, su Recipe y las dos bibliotecas que los respaldan.

Una biblioteca de esquemas contiene la forma

Una SchemaLibrary declara esquemas con nombre, escritos en la forma compacta — una línea por campo, con su tipo, sus restricciones y su valor predeterminado —, que el build compila a JSON Schema 2020-12 antes de comprobar ningún valor con ellos. Un extracto:

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 }

Una referencia nombra la biblioteca por su metadata.name — Datastores#/schemas/<entry> — y nunca por el lugar donde está almacenada, también dentro de la biblioteca, de modo que la misma referencia se resuelve tanto si la biblioteca está en el catálogo del espacio de trabajo como si está publicada en un registro. validate: y validateMessage: añaden una comprobación propia de un campo; when: hace condicional un objeto entero, de modo que las restricciones del pool secundario solo se aplican donde la arquitectura se resuelve a replication. Un $ref: entre documentos solo admite junto a él properties, required y description, y por eso el pool secundario se escribe completo en lugar de hacer referencia a NodePool.

El Component hace referencia a ella

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

El pilar values es una sola línea $ref:; los pequeños infra y provides, específicos del Component, permanecen en línea. Las aserciones contienen reglas del contrato del Component que ninguna palabra clave de esquema expresa, sea cual sea la Recipe que lo realice.

Una biblioteca de mapeos contiene la traducción

Una MappingLibrary contiene fragmentos de plantilla que importa una Recipe. Una entrada renderiza los values de un chart y declara con define una plantilla auxiliar que invoca con template para cada 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 }}

La plantilla auxiliar se declara dentro de la entrada que la usa, porque una Recipe importa una sola entrada y una definición viaja con la entrada que la contiene. El fragmento lo evalúa el renderizador de Aggrega, así que usa las funciones de Sprig y el optional de Aggrega para una clave que puede estar ausente (consulta sprig-functions.md); el include de Helm no es una de ellas, y template escribe su salida exactamente donde se encuentra.

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 es pequeña: el mapeo vive en la biblioteca, y la Recipe conserva lo que es suyo — el chart que renderiza y la dirección que publica. Como el mapeo fija el fullnameOverride del chart a .context.rendered_name, la Recipe puede calcular el nombre del Service del primario en lugar de suponerlo.

Lo que aportan las bibliotecas

En JSON Schema, el mapa de una línea de cada campo se convierte en un bloque anidado y cada objeto añade type: object, properties: y una lista required:; when: y validate: no tienen una palabra clave propia de JSON Schema. La forma compacta cubre todo lo que necesita este Component, sin la vía de escape $jsonschema:. El ahorro crece al compartir: la biblioteca se escribe una vez, y el pilar values de cada Component adicional es una sola línea $ref:.

Las referencias: escritura en forma compacta, $ref: entre documentos, el bloque de aserciones, SchemaLibrary y MappingLibrary.