Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Общие библиотеки схем и сопоставлений: сущность Component для MariaDB

Эта страница объясняет одну идею, хранить большую часть схемы сущности Component и сопоставления сущности Recipe в библиотеках, которые совместно используют несколько сущностей, и не является запускаемым рабочим пространством. MariaDB + Adminer — запускаемый пример с двумя целями составляет настройки хранения своей базы данных из библиотеки схем; запишите его в собственную папку командой:

Terminal window
aggrega scaffold --example mariadb-adminer

Затем она выводит команды, которые нужно выполнить дальше:

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

Сущности на этой странице — это ваш собственный каталог в пространстве имён my-org; форма каждой — та, которую принимают сущность Component для MariaDB промышленного уровня, её сущность Recipe и две стоящие за ними библиотеки.

Библиотека схем хранит форму

Сущность SchemaLibrary объявляет именованные схемы, записанные в компактной форме — одна строка на поле, с его типом, ограничениями и значением по умолчанию, — которые сборка компилирует в JSON Schema 2020-12, прежде чем какое-либо значение будет по ним проверено. Фрагмент:

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 }

Ссылка указывает библиотеку по её metadata.name — Datastores#/schemas/<entry> — и никогда по месту её хранения, в том числе и внутри библиотеки, поэтому одна и та же ссылка разрешается независимо от того, находится ли библиотека в каталоге рабочего пространства или опубликована в реестре. validate: и validateMessage: добавляют собственную проверку поля; when: делает условным целый объект, поэтому ограничения вторичного пула действуют только там, где архитектура разрешается в replication. Междокументная $ref: допускает рядом с собой только properties, required и description, поэтому вторичный пул записан полностью, а не через ссылку на NodePool.

Сущность Component ссылается на неё

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

Столп values — это одна строка $ref:; небольшие, специфичные для сущности Component infra и provides остаются встроенными. Утверждения содержат правила контракта сущности Component, которые не выражает ни одно ключевое слово схемы, какая бы сущность Recipe её ни реализовывала.

Библиотека сопоставлений хранит преобразование

Сущность MappingLibrary хранит фрагменты шаблонов, которые импортирует сущность Recipe. Одна запись рендерит значения чарта и объявляет с помощью define вспомогательный шаблон, который вызывает с помощью template для каждого пула узлов:

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

Вспомогательный шаблон объявлен внутри записи, которая его использует, потому что сущность Recipe импортирует одну запись, а определение переносится вместе с содержащей его записью. Фрагмент вычисляет рендерер Aggrega, поэтому он использует функции Sprig и функцию Aggrega optional для ключа, который может отсутствовать (см. sprig-functions.md); функция Helm include к ним не относится, а template записывает свой вывод ровно там, где стоит.

Сущность Recipe её импортирует

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"

Сущность Recipe невелика: сопоставление живёт в библиотеке, а сущность Recipe хранит то, что принадлежит ей, — чарт, который она рендерит, и адрес, который она публикует. Поскольку сопоставление фиксирует fullnameOverride чарта на .context.rendered_name, сущность Recipe может вычислить имя Service основного узла, а не предполагать его.

Что дают библиотеки

В JSON Schema однострочное отображение каждого поля превращается во вложенный блок, а каждый объект добавляет type: object, properties: и список required:; у when: и validate: нет собственного ключевого слова в JSON Schema. Компактная форма покрывает всё, что нужно этой сущности Component, без запасного выхода $jsonschema:. Экономия растёт с совместным использованием: библиотека пишется один раз, а столп values каждой следующей сущности Component — это одна строка $ref:.

Справка: создание в компактной форме, междокументная $ref:, блок утверждений, SchemaLibrary и MappingLibrary.