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/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: 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 поместило бы два файла по одному пути. Диагностика указывает файл пакета и ключ, под которым он был импортирован. Два выходных файла, которые действительно имеют одинаковое имя, останавливают сборку при рендеринге узла, что происходит, когда два разных вида входных данных дают одно имя файла. О том, как artifacts: сочетается с другими видами входных данных сущности Recipe, и о двух небиблиотечных режимах авторинга см. Recipe, а о более общем различии $ref: / $import: — vocabulary/cross-document-ref.
Композиция между библиотеками
Тело файла пакета — конечное содержимое. В отличие от записи 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 в модели документирования уровней сущностей — подключается по желанию для каталогов, которым нужно повторное использование артефактов между несколькими сущностями Recipe. Каталоги, в которых сущности Recipes содержат собственные вспомогательные файлы, поставляются без какой-либо сущности ArtifactLibrary; отметка уровня означает «продвинутый; пропустите, если не нужно» для навигации по документации, а не возможности. Компилятор обрабатывает ArtifactLibrary так же, как и другие виды сущностей каталога: та же проверка оболочки при загрузке рабочего пространства, тот же конвейер публикации в OCI при выпуске, та же фиксация в lock-файле по имени, версии и дайджесту содержимого.
Этот вид библиотеки завершает набор на уровне каталога: 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 делает её пакеты импортируемыми, но не делает их развёртываемыми.