Спільні бібліотеки схем і відображень: сутність 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.