Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Bibliotecas partilhadas 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 partilham, e não é um espaço de trabalho executável. MariaDB + Adminer — um exemplo executável com dois destinos compõe as definições de armazenamento da sua base de dados a partir de uma biblioteca de esquemas; pode escrevê-lo numa pasta própria com:

Terminal window
aggrega scaffold --example mariadb-adminer

Depois, imprime os próximos comandos a executar:

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

As entidades desta página são um catálogo próprio, 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 com nome, escritos na forma compacta — uma linha por campo, com o seu tipo, restrições e predefinição — que o build compila para JSON Schema 2020-12 antes de qualquer valor ser verificado face a eles. Um excerto:

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 }

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, pelo que a mesma referência se resolve quer a biblioteca esteja no catálogo do espaço de trabalho, quer esteja publicada num registo. validate: e validateMessage: acrescentam uma verificação própria de um campo; when: torna condicional um objeto inteiro, pelo que as restrições do pool secundário só se aplicam onde a arquitetura se resolve em replication. Um $ref: entre documentos admite a seu lado apenas properties, required e description, e é por isso que o pool secundário está escrito por extenso em vez de referenciar NodePool.

O Component referencia-a

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

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 exprime, 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/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 }}

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, pelo que usa as funções do Sprig e o optional do Aggrega para uma chave que pode estar ausente (consulte sprig-functions.md); o include do Helm não é uma delas, e template escreve a sua saída exatamente onde está.

A Recipe importa-a

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"

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 o presumir.

O que as bibliotecas oferecem

Em JSON Schema, o mapa de uma linha de cada campo torna-se 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 aquilo de que este Component precisa, sem a via de escape $jsonschema:. A poupança cresce com a partilha: 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.