Іменування відрендереного ресурсу
Recipe регулярно має назвати щось, що створив її власний вивід: ім’я хоста, яке публікується через
provides:, посилання всередині valuesMapping:, ідентифікатор, записаний у тіло artifacts:.
Два ключі контексту шаблону містять імена, доступні для цього, і вони відповідають на різні запитання.
Читання не того ключа дає вивід, який мовчки хибний, а не відхилений, — адресу, що називає
ресурс, якого ніщо не створило, — тому ця сторінка пояснює, який ключ відповідає на яке запитання.
Вона також пояснює відмінність, на якій ґрунтуються ці два ключі: ціль і посилання — не одне й те саме, і ціль ніколи не є ім’ям, яке розв’яже платформа розгортання.
Ціль називає компонент; посилання називає відрендерений ресурс
Ціль — це авторська ідентичність. Це значення, яке розробник пише, щоб указати, на який компонент
вказує ребро, — 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 }} | Ідентичність вузла та ім’я ресурсів, побудованих для цього вузла, для яких жоден provider не виводить імені, — набір артефактів, розміщений із вашого блоку artifacts:, і робоче навантаження, синтезоване з вашого блоку workload: тим provider, який називає його за ідентичністю, як це робить compose. Присутній завжди. |
{{ .context.rendered_name }} | Ім’я, яке прив’язаний provider виводить для ресурсів, що він рендерить для цього вузла, — для джерела, наданого вами, це ім’я, відносно якого ваші власні надані шаблони рендерять свої ресурси, наприклад ім’я релізу, яке читає чарт; для workload:, який він синтезує, це ім’я, яке він дає цим ресурсам там, де називає їх за власним ім’ям, а не за ідентичністю, як це робить helm. Присутній лише там, де цей provider його виводить. У власних шаблонах прикріплення Feature це ім’я компонента-хоста — див. нижче. |
Такий поділ випливає з того, де ім’я має бути придатним до використання. Чарт або модуль, наданий вами, має шаблони, і ці шаблони називають свої ресурси за тією ідентичністю, яку їм передає платформа, — тож ім’я має бути саме тим, яке використає ця платформа, записаним її власним алфавітом. Синтезоване робоче навантаження не має ваших шаблонів, але його ресурси все одно мусять мати імена, які приймає платформа: provider, чиї імена допускають усе, що може містити авторське ім’я, називає їх за ідентичністю, а той, чиї імена цього не допускають, називає їх за виведеним ним ім’ям — і тоді повідомляє це ім’я тут, тож вам ніколи не доводиться його передбачати.
Вузол, що оголошує і надане джерело, і workload:, видає обидва види виводу одночасно й
не потребує третього ключа. У helm обидва названо за одним іменем релізу, тож rendered_name
придатний для обох: власні ресурси чарту несуть його так, як його складають шаблони чарту, а кожен
синтезований Service — це <rendered_name>-<service key>. У provider, який називає синтезоване
робоче навантаження за ідентичністю, називайте ресурси цього навантаження за допомогою instance_id, а ресурси наданого
виводу — тим, що provider повідомляє для нього.
Саме алфавіти є причиною, чому ці два імені взагалі можуть відрізнятися. Авторське ім’я компонента може містити підкреслення або
велику літеру; ім’я релізу чарту — ні, і замість того щоб звести такий символ до схожого
(що дозволило б двом компонентам, які ви розрізняєте, отримати одне ім’я в кластері),
виведення записує його явно. Див. ../providers/helm.md «How the release name is
derived», щоб дізнатися власний алфавіт і обмеження довжини цього provider.
Які провайдери повідомляють ім’я і чому інші цього не роблять
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чарта, який ви вендорили, у закодовану ідентичність того, хто його додав; це також псевдонім, за яким umbrella прив’язує цей підчарт, і ключ, під яким обмежено його значення. Для компонента ця ідентичність — це те, що містить{{ .context.instance_id }}, тож ім’я розміщеного чарта вже доступне під ключем, який каже, чим воно є. Ім’я, відносно якого рендеряться власні шаблони вендореного чарта, — це ім’я релізу, яке надає реліз umbrella під час встановлення, а не виводить цей провайдер, — тож тут немає такого імені, яке цей ключ міг би повідомити. Див.../providers/helm-chart.md«The chart name the umbrella owns».
Читання ключа там, де ім’я не повідомляється
Читання {{ .context.rendered_name }} на вузлі, provider якого не повідомляє такого імені, зупиняє
збирання, а діагностика вказує, який ключ написати натомість. Порожнє значення не рендериться: адреса,
якій бракує одного сегмента, — це хибний артефакт, який розгортається, а це гірше, ніж збирання, що зупиняється.
Яке виправлення пропонує зупинка, залежить від вузла, а не від того, де ви написали посилання:
- Вузол, що не надає власного джерела, під provider, який не повідомляє для нього імені, має ресурси,
названі за його ідентичністю, тож зупинка називає
{{ .context.instance_id }}— правильне значення існує, і вона про це повідомляє. - Вузол, що надає джерело, під provider, який не виводить для нього імені, не має заміни. Зупинка повідомляє про це замість того, щоб запропонувати заміну, бо відсилання до ідентичності в цьому разі називало б ресурси, яких ваш вузол не містить.
Відмова охоплює provides: і кожен інший шаблон, який Recipe пише вбудовано, — його
valuesMapping:, тіло workload:, кожен запис artifacts:, а також with: і
when: кожного кроку конвеєра.
🔴 Обидві форми імпорту лишаються поза нею. Запис valuesMapping:, workload: чи artifacts:, наданий
через $import:, — незалежно від того, чи імпорт називає локальний файл, чи запис бібліотеки, — не містить тексту у вашому
Recipe, доки рендеринг його не розв’яже, тож посилання на цей ключ усередині такого тіла не перевіряється.
Воно рендерить ім’я, яке повідомляє provider імпортувального вузла, там, де цей provider його повідомляє, і порожнє
значення замість зупинки там, де не повідомляє. Тому імпортоване тіло читає ключ лише тоді, коли кожен Recipe, що
його імпортує, прив’язує provider, який повідомляє ім’я, — запис бібліотеки, написаний для helm Recipes, що надають
chart, і який зазначає це у своєму описі. Тіло, призначене для імпортерів, чий provider може не повідомляти імені, бере
ім’я натомість через значення, яке встановлює імпортувальний Recipe.
Записи locals: сутності Recipe взагалі не читають цей ключ. Локальна змінна має спільний контекст із шаблоном
source: сутності Recipe, а те, чи надає вузол джерело, — одна з речей, від яких залежить ім’я, тож
ім’я там не пропонується. Тому посилання на {{ .context.rendered_name }} у локальній змінній зупиняє збирання незалежно від того,
що повідомляє provider, з діагностикою для посилання, яке контекст рендерингу не визначає (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 пише вбудовано, крім його injectMapping:.
injectMapping:, а також запис valuesMapping:, workload: чи artifacts:, який FeatureRecipe надає
через $import:, не перевіряються: на хості, що не повідомляє імені, посилання там рендерить порожнє
значення, а не зупиняє збірку.
Якщо прикріплення постачає чарт, наданий його автором, шаблони цього чарту рендеряться з іменем релізу компонента-хоста, і це навмисно: виведення його з прикріплення перейменувало б
ресурси, які оголосив автор чарту і які, можливо, вже розгорнуто. .attachment_name — це значення,
яке розрізняє два прикріплення на одному хості, — див. ../providers/helm.md
«Як виводиться ім’я релізу».
Імена, похідні від вкладення з’єднання
Вкладення, яке несе з’єднання, є вкладенням компонента-споживача з іменем <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. Чому крапка записується в закодованому вигляді, а не замінюється, див. у Домовленостях щодо іменування, розділ «Роздільник не потрапляє в ім’я».
Пов’язані сторінки
- Контракт контексту шаблону — повна форма контексту, у якому розташовані ці ключі.
- Матриця розгортання шаблонів — які стовпи читає кожне місце шаблону.
- Тріада топології:
provides,inject,uses— як опубліковане значення перетинає ребро до споживача. - Домовленості щодо іменування — що можна писати як ім’я компонента і чого коштує ім’я за вужчого алфавіту.
errors/fatal-halts.md— зупинка, яку описує ця сторінка, разом із повідомленням, яке вона виводить.