Перейти до вмісту
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.