Общие библиотеки схем и сопоставлений: сущность Component для MariaDB
Эта страница объясняет одну идею, хранить большую часть схемы сущности Component и сопоставления сущности Recipe в библиотеках, которые совместно используют несколько сущностей, и не является запускаемым рабочим пространством. MariaDB + Adminer — запускаемый пример с двумя целями составляет настройки хранения своей базы данных из библиотеки схем; запишите его в собственную папку командой:
aggrega scaffold --example mariadb-adminerЗатем она выводит команды, которые нужно выполнить дальше:
cd mariadb-admineraggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlСущности на этой странице — это ваш собственный каталог в пространстве имён my-org; форма каждой — та, которую принимают сущность Component для MariaDB промышленного уровня, её сущность Recipe и две стоящие за ними библиотеки.
Библиотека схем хранит форму
Сущность SchemaLibrary объявляет именованные схемы, записанные в компактной форме — одна строка на поле, с его типом, ограничениями и значением по умолчанию, — которые сборка компилирует в JSON Schema 2020-12, прежде чем какое-либо значение будет по ним проверено. Фрагмент:
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 }Ссылка указывает библиотеку по её metadata.name — Datastores#/schemas/<entry> — и никогда по месту её хранения, в том числе и внутри библиотеки, поэтому одна и та же ссылка разрешается независимо от того, находится ли библиотека в каталоге рабочего пространства или опубликована в реестре. validate: и validateMessage: добавляют собственную проверку поля; when: делает условным целый объект, поэтому ограничения вторичного пула действуют только там, где архитектура разрешается в replication. Междокументная $ref: допускает рядом с собой только properties, required и description, поэтому вторичный пул записан полностью, а не через ссылку на NodePool.
Сущность Component ссылается на неё
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 -}}Столп values — это одна строка $ref:; небольшие, специфичные для сущности Component infra и provides остаются встроенными. Утверждения содержат правила контракта сущности Component, которые не выражает ни одно ключевое слово схемы, какая бы сущность Recipe её ни реализовывала.
Библиотека сопоставлений хранит преобразование
Сущность MappingLibrary хранит фрагменты шаблонов, которые импортирует сущность Recipe. Одна запись рендерит значения чарта и объявляет с помощью define вспомогательный шаблон, который вызывает с помощью template для каждого пула узлов:
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 }}Вспомогательный шаблон объявлен внутри записи, которая его использует, потому что сущность Recipe импортирует одну запись, а определение переносится вместе с содержащей его записью. Фрагмент вычисляет рендерер Aggrega, поэтому он использует функции Sprig и функцию Aggrega optional для ключа, который может отсутствовать (см. sprig-functions.md); функция Helm include к ним не относится, а template записывает свой вывод ровно там, где стоит.
Сущность Recipe её импортирует
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"Сущность 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.