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:
aggrega scaffold --example mariadb-adminerDespués imprime los comandos que hay que ejecutar a continuación:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlLas 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/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 }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/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 -}}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/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 }}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/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"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.