Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

ArtifactLibrary

ArtifactLibrary — це сутність каталогу, що містить багаторазово використовувані набори артефактів — іменовані набори допоміжних вихідних файлів, які належать разом. Сутності Recipes і FeatureRecipes, що генерують однакові допоміжні ресурси — CRD разом з його RBAC і ConfigMap, NetworkPolicy у парі з HPA, — оголошують такий набір один раз у бібліотеці та посилаються на нього під час використання через запис artifacts:, значенням якого є директива $import:. Сутність бібліотеки належить до рівня 3: її підключають за бажанням каталоги, яким потрібне повторне використання артефактів між сутностями Recipe. Каталоги, у яких кожна сутність із Recipes містить власні допоміжні файли, постачаються без жодної сутності ArtifactLibrary.

Роль сутності ArtifactLibrary

Архітектори платформи створюють сутності ArtifactLibraries, щоб централізувати допоміжні маніфести, які повторюються в сутностях Recipes і FeatureRecipes каталогу. Бібліотека не є інструкцією збирання, яку можна розгорнути; це простір імен визначень. Автори сутностей Recipe і FeatureRecipe посилаються на набір через директиву $import:, яку пишуть один раз і використовують усюди, де розв’язується імпорт.

Від інших трьох видів бібліотек цей вид відрізняє гранулярність запису. Запис SchemaLibrary — це одна схема, запис MappingLibrary — один фрагмент шаблону, а запис WorkloadLibrary — один документ Workload; кожен із них — це одне тіло, що використовується в одному місці. Запис ArtifactLibrary — це набір файлів, бо ресурси, які він групує, корисні лише разом: імпорт CRD без його RBAC дає набір маніфестів, який не працює. Саме тому одиницею повторного використання є набір, а одне місце використання розгортається в кілька вихідних файлів.

Оболонка сутності

Сутність ArtifactLibrary має стандартну оболонку каталогу. apiVersion: aggrega.ai/v1beta1 і kind: ArtifactLibrary позначають тип сутності; metadata.name — ідентифікатор у стилі PascalCase; metadata.version дотримується суворого семантичного версіонування. Обидва поля обов’язкові. metadata.description, metadata.labels і metadata.annotations необов’язкові — мітки й анотації є непрозорими метаданими, які оголошує автор і які переносяться для того, хто читає бібліотеку, щоб він міг за ними зіставляти, і компілятор не інтерпретує їхніх значень. Вміст бібліотеки розміщується в spec.artifacts — обов’язковій мапі, яка має оголошувати щонайменше один пакет.

Оболонка закрита на всіх трьох рівнях — корінь документа, metadata і spec відхиляють ключі, яких не оголошує схема.

apiVersion: aggrega.ai/v1beta1
kind: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
artifacts:
OperatorSupport:
crd.yaml: |
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
rbac.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: "{{ .context.instance_id }}-operator"
rules:
- apiGroups: ["platform.example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch"]

Створення пакетів артефактів

spec.artifacts має два рівні вкладеності, і кожен рівень виконує окреме завдання. Зовнішній ключ — це назва пакета, ідентифікатор, на який посилається споживач. Внутрішні ключі — це імена файлів, а кожне внутрішнє значення — тіло Go-шаблону, що виводиться в цей файл. Пакет має оголошувати щонайменше один файл.

spec:
artifacts:
NetworkBaseline:
deny-all.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-deny-all"
spec:
podSelector: {}
policyTypes: ["Ingress"]
allow-dns.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-allow-dns"

Тіло файлу — це фрагмент Go-шаблону, записаний як рядок YAML. Оскільки маніфест багаторядковий, тіла файлів використовують літеральний скаляр YAML (|), щоб переноси рядків і відступи зберігалися без змін. Значенням запису пакета має бути відображення імен файлів на рядкові тіла; простий рядок або послідовність на місці пакета відхиляються — споживач імпортує рівень пакета, а не окремий файл.

Для оболонки сутності тіло непрозоре. Під час завантаження сутності ArtifactLibrary компілятор зберігає кожен рядок дослівно й не розбирає там шаблон; парсер шаблонів запускається під час споживання, коли сутність Recipe або FeatureRecipe імпортує пакет. Дослівне збереження тіл забезпечує точність авторського тексту для повторного виведення, а також означає, що помилка шаблону виявляється там, де пакет споживається і відомий його контекст опор, а не в бібліотеці.

Порядок файлів у пакеті — це порядок, у якому їх записав автор; він зберігається під час завантаження та споживання, тож набір виведених файлів стабільний між збірками.

У тілі файлу доступний увесь словник композиції Go-шаблонів: {{ define "name" }}...{{ end }} оголошує блоки для повторного використання, {{ template "name" . }} викликає їх, а конвеєри та функції відповідають стандартному пакету Go text/template. Контекст опор, який може читати тіло файлу, — .values, .infra, .locals, .context, .features, а також .workload і .source, якщо їх оголошує сутність Recipe, що споживає пакет, — це той самий контекст, який читають власні записи artifacts: цієї сутності Recipe; його описано на сторінці Recipe у розділі про поле artifacts:. Тіло, що читає .workload, коли сутність Recipe-споживач не оголошує workload:, або .source, коли вона не оголошує source:, зупиняє компіляцію з діагностикою, що називає посилання, яке не вдалося задовольнити, — кожна опора перевіряється окремо, тож оголошення однієї не дозволяє читати іншу.

Єдиний режим створення

ArtifactLibrary постачається з одним режимом створення: шаблони Go. spec не приймає паралельної поверхні створення та жодного запасного виходу для виразності на рівні бібліотеки.

Причина — однорідність поверхні споживання. Recipes і FeatureRecipes повністю побудовані на шаблонах Go, і їхній власний вміст обчислюється тим самим рушієм шаблонів Go, який розв’язує імпортований пакет. Паралельна поверхня створення змусила б авторів перемикати моделі обчислення в межах рендерингу однієї сутності Recipe — одна модель для власного вмісту Recipe, інша для кожного імпортованого пакета. Однорідна поверхня означає, що автори вивчають одну модель обчислення й застосовують її скрізь.

Автори, яким потрібна виразність понад словник композиції шаблонів Go, компонують на вищому рівні — сутності Components або Features, що обгортають пакети бібліотеки власними змістовими варіаціями, — замість того щоб переходити до другої мови створення всередині бібліотеки.

Домовленості щодо іменування

Імена бібліотек та імена пакетів записуються в PascalCase. JSON Schema оболонки сутності забезпечує цю домовленість у двох місцях за допомогою обмежень-шаблонів:

  • metadata.name відповідає ^[A-Z][A-Za-z0-9]*$.
  • Ключі мапи spec.artifacts відповідають тому самому шаблону через propertyNames.

Сутність ArtifactLibrary з іменем пакета не в PascalCase не проходить валідацію оболонки під час завантаження робочого простору. Ця перевірка суттєва: імена пакетів з’являються у фрагменті посилання #/artifacts/<name>, тож ім’я не в PascalCase поширилося б на кожного споживача, що імпортує пакет.

Однорідність іменування зберігає фрагмент #/artifacts/<name> читабельним: #/artifacts/OperatorSupport зрозуміло з першого погляду.

Імена файлів усередині пакета довільні, якщо кожне з них називає файл. Вони не записуються в PascalCase, і жоден шаблон схеми їх не обмежує, оскільки вони називають файли, які зрештою містить результат збірки, — crd.yaml, deny-all.yaml, values-override.json усі допустимі. Ім’я файлу має бути звичайним відносним іменем файлу, записаним просто; збірка відхиляє ім’я, яке не називає власного файлу, як описано в розділі Посилання на записи бібліотеки. Два рівні обмежено по-різному, бо вони слугують різним читачам: ім’я пакета — це ідентифікатор, на який посилаються інші сутності, а імена файлів — це імена, які споживач бачить у каталозі, куди імпортовано пакет.

Посилання на записи бібліотеки

Автори сутностей Recipe та FeatureRecipe посилаються на пакет усередині запису artifacts:, значенням якого є мапа $import:, за ідентичністю пакета у вигляді простого імені:

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

Фрагмент #/artifacts/<name> вибирає пакет і відрізняє посилання на артефакти від #/mappings/<name> у MappingLibrary, #/schemas/<name> у SchemaLibrary та #/workloads/<name> у WorkloadLibrary. Посилання не містить хоста реєстру; форму з хостом oci://… відхиляє як схема оболонки, так і місце споживання, тож фізичне розташування реєстру ніколи не потрапляє в авторський вихідний код. Автор може задати необов’язкову нижню межу версії у вигляді <Library>:<version>#/artifacts/<name> — роздільником версії є :, як і в інших видах бібліотек та в закріпленні lock-файлу, а запис @ натомість відхиляється з діагностикою, що називає виправлене посилання. Розв’язану версію надає lock-файл кожної сутності Release, який закріплює кожну спожиту бібліотеку за іменем, версією та дайджестом вмісту; фізичне розташування прив’язується під час розв’язання.

Пакет володіє своїми іменами файлів, а ключ споживання володіє каталогом, у який вони потрапляють. Один запис artifacts:, що імпортує пакет, розгортається в один результат на кожен файл цього пакета, кожен вкладений під ключ споживання як <key>/<filename>. Ключ у місці споживання — operator-support вище — називає все споживання, а не якийсь окремий файл; приклад створює operator-support/crd.yaml і operator-support/rbac.yaml. Отже, ім’я пакета обирають для читабельності в посиланні, імена файлів — для читача вихідного каталогу, і вони не зобов’язані узгоджуватися між собою. Сам ключ споживання обмежено одним іменем файлу — початкова літера або цифра, далі літери, цифри, крапки, дефіси та підкреслення, а ключ поза цим алфавітом не проходить валідацію оболонки, — тож він називає рівно один сегмент каталогу, а все нижче цього сегмента походить із пакета. Саме це дає змогу іменам файлів пакета лишатися довільними, тоді як ключ лишається суворим: ім’я файлу унікальне в межах свого пакета, ключ унікальний у межах свого документа, а ключ є першим сегментом кожного шляху, який створює запис, тож жодні два записи artifacts: не називають один результат. Довільність означає свободу в межах цього сегмента: ім’я файлу може мати власну вкладену структуру — crds/widget.yaml потрапляє в <key>/crds/widget.yaml, — але воно має бути звичайним відносним іменем файлу під ключем, записаним просто, а ім’я файлу, яке таким не є, зупиняє збірку замість того, щоб розмістити файл там, куди сутність Recipe-споживач ніколи не вказувала. Так відхиляється ім’я, що піднімається вище ключа або називає абсолютне розташування; . чи ./, а також ім’я, що згортається назад до ключа, як-от x/.., які називають власний каталог ключа, а не файл у ньому; і ім’я з кінцевим або подвоєним / чи частиною . або .. — x/, a//b, ./a, a/../b, — яке є другим написанням файлу, що його може мати інше ім’я, тож a//b поруч із a/b поклало б два файли за одним шляхом. Діагностика називає файл пакета та ключ, під яким його імпортовано. Два результати, що справді мають однакове ім’я файлу, зупиняють збірку під час рендерингу вузла, що трапляється, коли два різні види вхідних даних додають одне ім’я файлу. Див. Recipe про те, як artifacts: поєднується з іншими видами вхідних даних сутності Recipe, і про два небібліотечні режими авторингу, а також vocabulary/cross-document-ref про ширшу відмінність між $ref: і $import:.

Композиція між бібліотеками

Тіло файлу бандла — кінцевий вміст. На відміну від запису MappingLibrary або WorkloadLibrary, файл бандла не може бути перенаправленням $import: на рівні кореня поля: в одному слоті файлу немає місця для кількох файлів, які приніс би інший бандл, тому компілятор відхиляє таку форму, а не розв’язує її в щось, чого автор не писав. Тіло, першим токеном якого є $import:, зупиняє збірку з діагностикою, що називає бандл і файл.

Натомість композиція відбувається в місці споживання, де для неї є місце. Recipe, якому потрібні два пакети, оголошує два записи artifacts:, і кожен розгортається незалежно:

# Inside a Recipe's spec — compose bundles where the outputs land:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"
network-baseline:
$import: "PlatformArtifacts#/artifacts/NetworkBaseline"

Невідома назва бібліотеки та назва пакета, відсутня в бібліотеці, яка розв’язується, повідомляються як окремі діагностики, тож автор може відрізнити відсутню залежність від помилки в назві пакета.

Розміщення в рівнях

ArtifactLibrary належить до рівня 3 у моделі документації за рівнями сутностей — це опція для каталогів, яким потрібне повторне використання артефактів між Recipes. Каталоги, чиї Recipes містять власні допоміжні файли, постачаються без жодної сутності ArtifactLibrary; позначка рівня сигналізує «розширене; пропустіть, якщо не потрібно» для навігації документацією, а не про можливості. Компілятор обробляє ArtifactLibrary однаково з іншими видами сутностей каталогу: та сама валідація оболонки під час завантаження робочого простору, той самий конвеєр публікації OCI під час випуску, те саме закріплення в lockfile за назвою, версією та дайджестом вмісту.

Цей вид бібліотеки доповнює набір на рівні каталогу — SchemaLibrary містить повторно використовувані визначення схем, MappingLibrary містить повторно використовувані фрагменти відображень, WorkloadLibrary містить повторно використовуваний вміст робочих навантажень, а ArtifactLibrary містить повторно використовувані пакети артефактів. Кожна з них підключається незалежно; каталоги постачають ті, що їм потрібні, і жодних інших.

Чим ArtifactLibrary не є

Кілька поширених хибних уявлень, яким варто запобігти:

  • Не замінник вбудованого artifacts:. Більшість сутностей Recipes містять допоміжні файли, достатньо специфічні, щоб розміщуватися вбудовано, де автор читає їх разом з рештою сутності Recipe. Сутність ArtifactLibrary корисна, коли ТОЙ САМИЙ набір файлів супроводжує багато сутностей Recipes; для одноразового вмісту правильним вибором є вбудоване написання.

  • Не спосіб перейменувати файли всередині пакета. Імена файлів належать пакету. Споживач вибирає каталог, у який вони потрапляють, — саме це робить ключ споживання, — але не те, як називається будь-який із них: споживач, якому потрібне інше ім’я файлу, або використовує пакет, що його оголошує, або пише файл вбудовано.

  • Не місце для вмісту робочих навантажень, відображень чи схем. Документ Workload належить до сутності WorkloadLibrary, документ значень сутності Recipe належить до сутності MappingLibrary, а визначення схем належать до сутності SchemaLibrary. Види бібліотек розділяються за типом вмісту, а не за шаблоном повторного використання.

  • Не механізм для наскрізних ресурсів. Допоміжні ресурси, що застосовуються до багатьох компонентів незалежно від того, яка сутність Recipe їх реалізує, — як-от sidecar резервного копіювання, приєднаний до кожного сховища даних, — належать до генерування ресурсів у сутності FeatureRecipe, яка приєднується за сутністю Feature, а не за сутністю Recipe. Див. entities/featurerecipe.md. Сутність ArtifactLibrary виокремлює файли, які кілька сутностей Recipes кожна генерує від власного імені.

  • Не сутність, що розгортається самостійно. Пакет — це вміст артефактів, а вміст артефактів ніколи не адресується сам по собі: він існує як вхідні дані, які споживає сутність Recipe або FeatureRecipe. Публікація сутності ArtifactLibrary робить її пакети придатними для імпорту; вона не робить їх придатними для розгортання.