Bibliotecas compartilhadas de esquemas e de mapeamentos: um Component MariaDB
Esta página explica uma ideia, manter a maior parte do esquema de um Component e do mapeamento de uma Recipe em bibliotecas que várias entidades compartilham, e não é um espaço de trabalho executável. MariaDB + Adminer — um exemplo executável com dois destinos compõe as configurações de armazenamento do seu banco de dados a partir de uma biblioteca de esquemas; escreva-o em uma pasta sua com:
aggrega scaffold --example mariadb-adminerEm seguida ele imprime os próximos comandos a executar:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlAs entidades desta página são um catálogo seu, no namespace my-org; a forma de cada uma é a que assumem um Component MariaDB de nível de produção, a sua Recipe e as duas bibliotecas por trás deles.
Uma biblioteca de esquemas contém a forma
Uma SchemaLibrary declara esquemas nomeados, escritos na forma compacta — uma linha por campo, com o seu tipo, restrições e valor padrão — que o build compila para JSON Schema 2020-12 antes que qualquer valor seja verificado em relação a eles. Um trecho:
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 }Uma referência nomeia a biblioteca pelo seu metadata.name — Datastores#/schemas/<entry> — e nunca pelo local onde a biblioteca está armazenada, também dentro da biblioteca, de modo que a mesma referência se resolve quer a biblioteca esteja no catálogo do espaço de trabalho, quer esteja publicada em um registro. validate: e validateMessage: acrescentam uma verificação própria de um campo; when: torna condicional um objeto inteiro, de modo que as restrições do pool secundário só valem onde a arquitetura se resolve para replication. Um $ref: entre documentos aceita ao seu lado apenas properties, required e description, e é por isso que o pool secundário é escrito por extenso em vez de referenciar NodePool.
O Component a referencia
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 -}}O pilar values é uma única linha $ref:; os pequenos infra e provides, específicos do Component, ficam inline. As asserções contêm regras do contrato do Component que nenhuma palavra-chave de esquema expressa, seja qual for a Recipe que o realize.
Uma biblioteca de mapeamentos contém a tradução
Uma MappingLibrary contém fragmentos de template que uma Recipe importa. Uma entrada renderiza os values de um chart e declara com define um template auxiliar que invoca com 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 }}O template auxiliar é declarado dentro da entrada que o usa, porque uma Recipe importa uma única entrada e uma definição viaja com a entrada que a contém. O fragmento é avaliado pelo renderizador do Aggrega, então usa as funções do Sprig e o optional do Aggrega para uma chave que pode estar ausente (veja sprig-functions.md); o include do Helm não é uma delas, e template escreve a sua saída exatamente onde está.
A Recipe a 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"A Recipe é pequena: o mapeamento vive na biblioteca, e a Recipe guarda o que é seu — o chart que renderiza e o endereço que publica. Como o mapeamento fixa o fullnameOverride do chart em .context.rendered_name, a Recipe pode calcular o nome do Service do primário em vez de presumi-lo.
O que as bibliotecas oferecem
Em JSON Schema, o mapa de uma linha de cada campo vira um bloco aninhado e cada objeto acrescenta type: object, properties: e uma lista required:; when: e validate: não têm uma palavra-chave própria do JSON Schema. A forma compacta cobre tudo o que este Component precisa, sem a via de escape $jsonschema:. A economia cresce com o compartilhamento: a biblioteca é escrita uma vez, e o pilar values de cada Component adicional é uma única linha $ref:.
As referências: escrita na forma compacta, $ref: entre documentos, o bloco de asserções, SchemaLibrary e MappingLibrary.