Именование отрендеренного ресурса
Сущности Recipe регулярно приходится называть что-то, что породил её собственный вывод: имя хоста, публикуемое через
provides:, ссылку внутри valuesMapping:, идентификатор, записанный в тело artifacts:.
Имена, доступные для этого, несут два ключа контекста шаблона, и они отвечают на разные вопросы.
Если прочитать не тот ключ, получится вывод, который молча ошибочен, а не отклонён, — адрес, называющий
ресурс, который ничто не сгенерировало, — поэтому на этой странице описано, какой ключ отвечает на какой вопрос.
На ней также описано различие, на котором основаны оба ключа: цель (target) и ссылка (reference) — не одно и то же, и цель никогда не является именем, которое разрешит платформа развёртывания.
Цель именует компонент; ссылка именует отрисованный ресурс
Цель — это авторская идентичность. Это значение, которое разработчик пишет, чтобы указать, на какой компонент направлено ребро, — target: my_db в блоке uses, — и это идентичность, по которой сборка находит этот компонент, сообщает о нём в диагностике и индексирует его факты. Она читается одинаково при любом провайдере, потому что это факт о ваших документах, а не о какой-либо платформе.
Ссылка — это то, что заставляет один отрисованный артефакт указывать на другой. Она записывается в собственном словаре конкретного провайдера: адрес внутри кластера при helm, имя сервиса при compose, интерполяция при terraform, импортированное значение при cloudformation. Ссылка различается для каждого провайдера, потому что каждая платформа разрешает ссылки по-своему.
🔴 Цель никогда не записывается в отрисованный вывод. Каждый провайдер выводит собственные имена, поэтому авторская идентичность, переданная платформе в качестве имени, ошибочна всякий раз, когда два написания различаются, — а различаются они ровно на тех символах, которые не допускает собственный алфавит цели. Идентичность без таких символов проходит без изменений, и именно поэтому здесь легко ошибиться: ошибка работает, пока кто-нибудь не назовёт компонент с подчёркиванием или заглавной буквой.
Поэтому ссылку, нужную потребителю, публикует производитель: именно Recipe производителя знает словарь своего провайдера, — потребитель может привязать совсем другой провайдер и не может записать ссылку для платформы, в которую он не отрисовывает. Потребитель читает обычную опубликованную строку.
Разобранная пара
Recipe производителя публикует адрес; потребитель читает его обратно через псевдоним ребра.
# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.# It publishes an in-cluster address built from the name that chart's own# templates render their resources against.spec: capability: helm source: ./charts/postgres provides: host: "{{ .context.rendered_name }}.svc.cluster.local" port: "5432"# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an# authoring identity and stays in the documents. The uses block is keyed by the# socket the catalog entity declares, then by the alias you choose for the edge.spec: components: api: type: core/compute/api-server uses: databases: primary: target: my_db inject: env: - in: DB_HOST from: host - in: DB_PORT from: port# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.# The context keys an edge by its alias, so the socket does not reappear here.spec: capability: helm valuesMapping: | { "db_host": "{{ .context.uses.primary.provides.host }}" }Для предоставленного автором чарта при helm компонент с именем my_db отрисовывает свои ресурсы под именем релиза my-zudb. Поэтому чарт производителя создаёт Service, у которого metadata.name равно my-zudb, опубликованный host равен my-zudb.svc.cluster.local, и потребитель подключается к существующему Service — независимо от того, читает ли он значение через .context.uses.primary.provides.host или получает его как внедрённую DB_HOST.
Если написать там {{ .context.uses.primary.target }}, вместо этого будет опубликовано my_db.svc.cluster.local. Это значение не выглядит ошибочным: это идентичность, которую написал разработчик, в точности в его написании. Просто оно не именует никакой Service, и ничто в сборке об этом не сообщает.
Два ключа как пара
Ни один из ключей не понятен сам по себе, потому что каждый определяется тем, чем не является другой.
| Ключ | Что он именует |
|---|---|
{{ .context.instance_id }} | Идентичность узла и имя ресурсов, построенных для этого узла, для которых ни один провайдер не выводит имя, — набора артефактов, размещённого из вашего блока artifacts:, и рабочей нагрузки, синтезированной из вашего блока workload: провайдером, который называет её по идентичности, как это делает compose. Присутствует всегда. |
{{ .context.rendered_name }} | Имя, которое привязанный провайдер выводит для ресурсов, которые он рендерит для этого узла: для исходников, предоставленных вами, — имя, относительно которого ваши собственные шаблоны рендерят свои ресурсы, например имя релиза, которое читает чарт; для синтезируемого им workload: — имя, которое он даёт этим ресурсам, если называет их по собственному имени, а не по идентичности, как это делает helm. Присутствует, только если этот провайдер выводит такое имя. В собственных шаблонах подключения Feature это имя компонента-хоста — см. ниже. |
Такое разделение следует из того, где имя должно быть пригодно к использованию. У чарта или модуля, предоставленного вами, есть шаблоны, и эти шаблоны называют свои ресурсы по той идентичности, которую им передаёт платформа, — поэтому имя должно быть тем, которое будет использовать платформа, записанным в собственном алфавите этой платформы. У синтезированной рабочей нагрузки нет ваших шаблонов, но её ресурсы всё равно должны носить имена, которые принимает платформа: провайдер, чьи имена допускают всё, что может содержать авторское имя, называет их по идентичности, а провайдер, чьи имена этого не допускают, называет их по выводимому им имени — и затем сообщает это имя здесь, так что вам никогда не придётся его предугадывать.
Узел, объявляющий и предоставленные исходники, и workload:, выдаёт оба вида вывода одновременно, и третий ключ ему не нужен. В helm оба названы по одному имени релиза, поэтому rendered_name подходит для любого из них: собственные ресурсы чарта несут его, как бы ни составляли его шаблоны, а каждый синтезированный Service называется <rendered_name>-<service key>. В провайдере, который называет синтезированную рабочую нагрузку по идентичности, называйте ресурсы этой рабочей нагрузки через instance_id, а ресурсы предоставленного вывода — тем, что провайдер сообщает для него.
Именно из-за алфавитов эти два ключа вообще могут различаться. Авторское имя компонента может содержать подчёркивание или заглавную букву; имя релиза чарта — нет, и вместо того чтобы сводить такой символ к похожему, что позволило бы двум различимым для вас компонентам получить в кластере одно имя, вывод имени записывает его явно. Алфавит и ограничение длины этого провайдера описаны в разделе «How the release name is derived» в ../providers/helm.md.
Какие провайдеры сообщают имя и почему остальные этого не делают
helm сообщает одно имя — имя релиза. Подключённый чарт читает его как .Release.Name и обычно называет
по нему свои ресурсы, и провайдер тоже называет по нему каждый ресурс, который синтезирует для компонента, —
контроллер получает само имя релиза, а каждый Service — имя вида <release name>-<service key>. Поэтому адрес, публикуемый для любого из двух видов вывода, строится из rendered_name. Для узла,
который размещает только набор артефактов, провайдер не сообщает никакого имени: имена в этом наборе — те, что написал его автор.
# A synthesized helm Recipe publishing the address of the Service its workload# declares under the key `default`.spec: capability: helm workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "valkey/valkey:8" ports: redis: 6379 services: default: type: ClusterIP ports: redis: 6379 provides: host: "{{ .context.rendered_name }}-default" port: "6379"Компонент с именем cache публикует cache-default, а компонент с именем my_cache публикует
my-zucache-default — в обоих случаях это имя Service, который выдаёт сборка.
Остальные четыре провайдера не сообщают имени, и причины у них не одинаковые. Ни один из них не ждёт поддержки: в каждом случае либо нет производного имени, которое можно было бы сообщить, либо нужное вам имя уже доступно другим способом.
-
cloudformationиcompose— имена написали вы, или имя совпадает с идентичностью. В Recipe для cloudformation заданы логические идентификаторы его ресурсов, и провайдер читает их ровно так, как они написаны; предоставленный вами compose-файл сам называет свои сервисы, а провайдер объединяет и помечает этот файл, ничего в нём не переименовывая. Рабочая нагрузка, которую синтезируетcompose, называется по идентичности узла, которую compose-файл допускает в исходном виде, поэтому{{ .context.instance_id }}и есть это имя. Сообщать нечего, так как никакого вывода имени нет, а имена — те, что стоят в ваших собственных документах. Это имя принадлежит главному сервису рабочей нагрузки — тому, к которому обращаются другие сервисы; sidecar- или init-сервис, который она содержит, называется по той же идентичности и имени контейнера, соединённым через--, как описано в разделе Как называется sidecar- или init-сервис. -
terraform— имя зависит от того, где были размещены файлы. Блокmoduleучастника получает имя по выходному каталогу, в который была записана его конфигурация, а этот каталог определяется при сборке файлов границы, а не при рендеринге узла. В момент, когда выполняются шаблоны Recipe, этого положения ещё не существует. -
helm-chart— имя, которое он выводит, — это собственный адрес размещённого чарта, а это не то же самое, что имя, относительно которого рендерятся шаблоны этого чарта. Этот провайдер задаёт полюnameчарта, который вы включили в поставку, закодированную идентичность того, кто его внёс; это же имя служит псевдонимом, под которым зонтичный чарт подключает этот подчарт, и ключом, в области которого находятся его значения. Для компонента эту идентичность несёт{{ .context.instance_id }}, поэтому имя размещённого чарта уже доступно под ключом, который прямо говорит, что это такое. Имя, относительно которого рендерятся собственные шаблоны включённого чарта, — это имя релиза, которое задаёт релиз зонтичного чарта во время установки, а не выводит этот провайдер, — так что здесь нет такого имени, которое этот ключ мог бы сообщить. См.../providers/helm-chart.md, раздел «The chart name the umbrella owns».
Чтение ключа там, где имя не сообщается
Чтение {{ .context.rendered_name }} на узле, провайдер которого не сообщает такого имени, останавливает
сборку, и диагностика указывает, какой ключ написать вместо него. Пустое значение не подставляется: адрес, в котором
не хватает одного сегмента, — это неверный артефакт, который развёртывается, а это хуже, чем остановленная сборка.
Какое решение предлагает остановка, зависит от узла, а не от того, где вы написали ссылку:
- Узел, который не предоставляет собственного источника, при провайдере, не сообщающем для него имени, получает
имена ресурсов по своей идентичности, поэтому остановка называет
{{ .context.instance_id }}: правильное значение существует, и диагностика об этом сообщает. - У узла, который предоставляет источник, при провайдере, не выводящем для него имени, замены нет. Остановка сообщает об этом, а не предлагает замену, потому что отсылка к идентичности здесь дала бы имена ресурсам, которых у вашего узла нет.
Отказ распространяется на provides: и на все прочие шаблоны, которые Recipe пишет встроенно, — его
valuesMapping:, тело workload:, каждую запись artifacts:, а также with: и
when: каждого шага конвейера.
🔴 Обе формы импорта находятся вне его действия. Запись valuesMapping:, workload: или artifacts:, предоставленная
через $import:, — указывает ли импорт на локальный файл или на запись библиотеки — не содержит текста в вашем
Recipe, пока рендеринг её не разрешит, поэтому ссылка на этот ключ внутри такого тела не проверяется.
Она выдаёт имя, которое сообщает провайдер импортирующего узла, если он его сообщает, и пустое
значение вместо остановки, если не сообщает. Поэтому импортируемое тело читает ключ, только если каждый Recipe, который
его импортирует, привязывает провайдер, сообщающий имя, — например, запись библиотеки, написанная для сущностей Recipe с helm, которые берут
чарт из источника, и указывающая это в своём описании. Тело, предназначенное для импортёров, провайдер которых может не сообщать имени, получает
имя через значение, которое задаёт импортирующий Recipe.
Записи locals: в Recipe вообще не читают этот ключ. Локальная переменная разделяет контекст с шаблоном
source: сущности Recipe, а то, предоставляет ли узел источник, — одно из условий, от которых зависит имя, поэтому
имя там не предлагается. Следовательно, ссылка на {{ .context.rendered_name }} в локальной переменной останавливает сборку, что бы ни
сообщал провайдер, с диагностикой для ссылки, которую контекст рендеринга не определяет (E0060),
и в ней .context.instance_id указан как единственный ключ, который .context там предлагает. Читайте ключ в записи provides:
или во встроенном шаблоне, которому он нужен.
О собственных шаблонах подключения Feature
В шаблонах, которые пишет FeatureRecipe подключения Feature, — его locals:, source:, provides:,
injectMapping:, valuesMapping:, workload:, каждой записи artifacts: и в with: и when: каждого шага конвейера — {{ .context.rendered_name }} является именем компонента-хоста: тем, которое собственный провайдер хоста сообщает для ресурсов, отрисовываемых им для хоста, то есть значением, которое читает собственный Recipe хоста. Оно составляет пару с {{ .context.instance_id }}, который в этих шаблонах является идентификатором компонента-хоста; само подключение — это .attachment_name. Подключение, записанное на одном из соединений компонента, читает имя компонента-потребителя, поскольку этот компонент и является его хостом.
Именно из этого ключа следует строить имена собственных ресурсов подключения. Сущности FeatureRecipe, которая называет Secret,
маршрут или политику по компоненту, к которому она подключена, нужно имя, допустимое для платформы, а идентификатор хоста в записанном виде таким не является, если содержит подчёркивание или заглавную букву. При
helm компонент с именем my_db сообщает my-zudb, поэтому Secret с именем
{{ .context.rendered_name }}-{{ .attachment_name }} для подключения root отрисовывается как
my-zudb-root, тогда как {{ .context.instance_id }} дал бы my_db-root, который кластер отвергает.
Значение остаётся значением хоста, через какой бы провайдер ни отрисовывалось подключение.
Оно присутствует везде, где провайдер хоста сообщает имя, — при helm это хост, чей Recipe предоставляет
чарт или объявляет workload:, — и отсутствует там, где имя не сообщается: у хоста, размещающего только набор артефактов, и у хоста на любом другом провайдере. Чтение этого ключа в подключении такого хоста останавливает сборку
с диагностикой для ссылки, которую контекст отрисовки не определяет (E0060); она перечисляет ключи, которые
.context там определяет. {{ .context.instance_id }} входит в их число, и именно по нему названы собственные
ресурсы такого хоста, поэтому FeatureRecipe, написанный для хостов, которые могут не сообщать имя,
читает вместо этого идентификатор.
Отказ распространяется на шаблоны, которые FeatureRecipe пишет inline, кроме его injectMapping:.
injectMapping:, а также запись valuesMapping:, workload: или artifacts:, которую FeatureRecipe предоставляет
через $import:, не проверяются: на хосте, не сообщающем имя, ссылка там отрисовывает пустое
значение, а не останавливает сборку.
Если подключение доставляет чарт, предоставленный его автором, шаблоны этого чарта отрисовываются с именем релиза
компонента-хоста, и это сделано намеренно: выведение имени из подключения переименовало бы
ресурсы, которые объявил автор чарта и которые, возможно, уже развёрнуты. .attachment_name — это значение,
которое различает два подключения на одном хосте, — см. ../providers/helm.md,
«How the release name is derived».
Имена, производные от вложения соединения
Вложение, которое несёт соединение, является вложением потребляющего компонента и называется <alias>.<slot> — gpt.credential для слота credential соединения, записанного под псевдонимом gpt (см. запись соединения в сущности Aggregate). Это составное имя и есть .attachment_name, с которым рендерится его FeatureRecipe, и оно содержит точку.
Из него следуют имена двух видов, и с точкой они обращаются по-разному.
Имя, которое составляет FeatureRecipe, сохраняет всё, что записывает его шаблон. Реализации учётных данных из стандартной библиотеки называют свой ресурс {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, поэтому учётные данные на соединении gpt компонента с именем router рендерятся как ресурс с именем router-gpt.credential, включая точку, — это допустимое имя объекта Kubernetes. Точка сохраняется в имени такого вида ровно тогда, когда её сохраняет шаблон.
Имя, которое сборка выводит из идентичности вложения, записывает точку в закодированном виде. Метки идентичности и выпускаемый файл составляются из компонента-хоста и имени вложения через ту же кодировку, через которую проходит каждое имя, выводимое из идентичности, и она записывает точку как zd, а заглавную букву — как экранирование её кодовой точки, потому что идентичность используется и как имя ресурса, и как метка, а имя Service не допускает ни того, ни другого: соединение, записанное под псевдонимом gptPro, дало бы cfr--router--gpt-zx000050ro-zdcredential. Ресурс выше получает метку aggrega.ai/component-id: cfr--router--gpt-zdcredential (и так же app.kubernetes.io/name), а при провайдере helm выпускается как router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Почему точка кодируется, а не заменяется, см. в разделе «The separator does not reach a name» страницы Соглашения об именовании.
Связанные материалы
- Контракт контекста шаблона — полная структура контекста, в котором находятся эти ключи.
- Матрица раскрытия шаблонов — какие опоры читает каждое место шаблона.
- Триада топологии:
provides,inject,uses— как опубликованное значение переходит по ребру к потребителю. - Соглашения об именовании — что можно указать в качестве имени компонента и чего стоит имя при более узком алфавите.
errors/fatal-halts.md— останов, описанный на этой странице, с выводимым сообщением.