レンダリングされたリソースの命名
Recipe では、自身の出力が生成したものを名前で指す必要が日常的に生じます。たとえば
provides: を通じて公開するホスト名、valuesMapping: 内の参照、artifacts: の本文に書き込む識別子などです。
そのために利用できる名前を保持するテンプレートコンテキストのキーは 2 つあり、それぞれ異なる問いに答えます。
誤ったキーを読むと、拒否されるのではなく、気づかれないまま誤った出力が生成されます。つまり、何も出力していない
リソースを指すアドレスになります。そのため、このページではどのキーがどの問いに答えるかを説明します。
また、2 つのキーの前提となる区別についても説明します。ターゲットと参照は 同じものではなく、ターゲットは決してデプロイプラットフォームが解決する名前ではありません。
target はコンポーネントを指し、reference はレンダリングされたリソースを指す
target はオーサリング上の識別子です。 これは、エッジがどのコンポーネントを指すかを示すために開発者が書く値であり(uses ブロック内の target: my_db)、ビルドがそのコンポーネントを見つけ、診断でそれについて報告し、その事実をキーとして管理するために使う識別子です。target はどのプロバイダーのもとでも同じように読まれます。これはプラットフォームについての事実ではなく、ドキュメントについての事実だからです。
reference は、あるレンダリング済みアーティファクトを別のアーティファクトに向けるものです。 reference は各プロバイダー独自の語彙で書かれます。helm ではクラスター内部のアドレス、compose ではサービス名、terraform では補間、cloudformation ではインポートされた値です。reference はプロバイダーごとに異なります。各プラットフォームが独自の方法で reference を解決するためです。
🔴 target がレンダリング出力に書き込まれることはありません。 各プロバイダーは独自の名前を導出するため、オーサリングされた識別子を名前としてプラットフォームに渡すと、2 つの表記が異なる場合には必ず誤りになります。そして両者は、target 自身のアルファベットが許容しない文字の部分でちょうど異なります。そのような文字を含まない識別子はそのまま残るため、この誤りは起こしやすいものです。誰かがアンダースコアや大文字を含む名前をコンポーネントに付けるまでは、誤りがあっても動作してしまいます。
したがって、コンシューマーが必要とする reference はプロデューサーが公開します。自身のプロバイダーの語彙を知っているのはプロデューサーの Recipe だからです。コンシューマーはまったく別のプロバイダーをバインドしている可能性があり、レンダリング先ではないプラットフォーム向けの reference を記述することはできません。コンシューマーは公開された通常の文字列を読み取ります。
具体例
プロデューサーの 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 というリリース名でレンダリングします。そのため、プロデューサーのチャートは metadata.name が my-zudb である Service を出力し、公開される host は my-zudb.svc.cluster.local となり、コンシューマーは実在する Service に接続します。これは、値を .context.uses.primary.provides.host を通じて読み取る場合も、注入された DB_HOST として受け取る場合も同じです。
そこで {{ .context.uses.primary.target }} と書くと、代わりに my_db.svc.cluster.local が公開されます。この値は見た目には誤りに見えません。開発者が書いた識別子を、書いたとおりの表記で示しているからです。単にどの Service も指しておらず、ビルドのどこにもそれが示されないだけです。
2 つのキーを対として見る
どちらのキーも単独では意味をなしません。それぞれが、もう一方ではないものによって定義されるからです。
| キー | 名前を与える対象 |
|---|---|
{{ .context.instance_id }} | ノードのアイデンティティ、およびこのノードのために構築されたリソースのうち、どのプロバイダも名前を導出しないものの名前です。artifacts: ブロックから配置されるアーティファクトセットや、compose のようにアイデンティティにちなんで名前を付けるプロバイダが workload: ブロックから合成するワークロードがこれにあたります。常に存在します。 |
{{ .context.rendered_name }} | バインドされたプロバイダがこのノードのためにレンダリングするリソースについて導出する名前です。自分で提供したソースについては、提供したテンプレートがリソースをレンダリングする際に基準とする名前で、たとえばチャートが読むリリース名です。プロバイダが合成する workload: については、helm のように、アイデンティティではなく独自の名前にちなんでリソースに名前を付ける場合に、それらのリソースに与える名前です。そのプロバイダが名前を導出する場合にのみ存在します。Feature アタッチメント自身のテンプレートでは、ホストとなるコンポーネントの名前になります。後述を参照してください。 |
この区別は、名前がどこで使用可能でなければならないかに由来します。自分で提供したチャートやモジュールにはテンプレートがあり、それらのテンプレートはプラットフォームから渡されたアイデンティティにちなんでリソースに名前を付けます。 そのため、名前はそのプラットフォームが実際に使うもので、そのプラットフォーム自身のアルファベットで綴られていなければなりません。合成されたワークロードには自分のテンプレートはありませんが、そのリソースにもプラットフォームが受け付ける名前が必要です。作成された名前が含みうるすべての文字を名前に許容するプロバイダはアイデンティティにちなんで名前を付け、許容しないプロバイダは自ら導出した名前にちなんで名前を付けます。そしてその名前をここで報告するので、名前を予測する必要はありません。
提供されたソースと workload: の両方を宣言するノードは、両方の種類の出力を同時に生成し、
3 つ目のキーは必要ありません。 helm では両方とも 1 つのリリース名にちなんで名前が付けられるため、rendered_name がどちらにも使えます。チャート自身のリソースはテンプレートがどう組み立てるにせよこの名前を持ち、合成される各 Service は <rendered_name>-<service key> になります。合成されたワークロードにアイデンティティにちなんで名前を付けるプロバイダでは、そのワークロードのリソースには instance_id を、提供された出力のリソースにはプロバイダがそれについて報告するものを使って名前を付けます。
そもそも 2 つが異なりうるのは、アルファベットのためです。作成されたコンポーネント名にはアンダースコアや大文字を含めることができますが、チャートのリリース名には含められません。導出処理は、そのような文字を似た文字に畳み込むのではなく(そうすると区別できる 2 つのコンポーネントがクラスタ内で 1 つの名前に行き着いてしまいます)、その文字を書き出します。そのプロバイダ自身のアルファベットと長さの制限については、../providers/helm.md の「How the release name is derived」を参照してください。
名前を報告するプロバイダと、他のプロバイダが報告しない理由
helm は 1 つの名前、つまりリリース名を報告します。ソースとして指定されたチャートはこれを .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 の名前です。
残りの 4 つは名前を報告せず、その理由は同じではありません。いずれも対応を待っているプロバイダではありません。どの場合も、報告すべき導出された名前が存在しないか、必要な名前がすでに別の方法で参照可能であるかのどちらかです。
-
cloudformationとcompose:名前は自分で書いたものであるか、アイデンティティがそのまま名前です。 cloudformation の Recipe はそのリソースの論理 ID を記述し、プロバイダはそれを書かれたとおりに読み取ります。自分で用意した compose ファイルはそれ自身のサービスに名前を付け、プロバイダはそのファイル内の何も名前を変えずに、ファイルをマージしてラベルを付けます。composeが合成するワークロードはノードのアイデンティティにちなんで命名され、compose ファイルはそれを書かれたとおりに受け入れるため、{{ .context.instance_id }}がその名前になります。報告すべき導出は存在せず、名前は自分のドキュメントに記述されているものです。その名前はワークロードのメインサービス、つまりピアが到達するサービスの名前です。ワークロードが持つサイドカーまたは init サービスは、サイドカーまたは init サービスの命名方法で説明しているとおり、同じアイデンティティとコンテナ名を--で結合して命名されます。 -
terraform:名前はファイルが配置された場所によって決まります。 コントリビュータのmoduleブロックは、その設定が書き込まれた出力ディレクトリから命名されます。これはノードがレンダリングされる時点ではなく、境界のファイルが組み立てられる時点で確定します。Recipe の テンプレートが実行される時点では、その位置はまだ存在しません。 -
helm-chart:このプロバイダが導出する名前は配置されたチャート自身のアドレスであり、そのチャートのテンプレートがレンダリングの基準とする名前とは別物です。 このプロバイダは、ベンダリングしたチャートのnameフィールドを、それを提供したもののエンコードされたアイデンティティに設定します。これは、アンブレラがそのサブチャートをバインドするエイリアスでもあり、その値のスコープとなるキーでもあります。コンポーネントの場合、そのアイデンティティは{{ .context.instance_id }}が保持するものであるため、配置されたチャートの名前は、それが何であるかを示すキーですでに参照できます。ベンダリングしたチャート自身のテンプレートがレンダリングの基準とする名前はリリース名であり、これはこのプロバイダが導出するのではなく、インストール時にアンブレラのリリースが提供します。 そのため、ここにはこのキーが報告すべきそのような名前は存在しません。../providers/helm-chart.mdの「The chart name the umbrella owns」を参照してください。
名前が報告されない場合にキーを読み取る
provider がそのような名前を報告しないノードで {{ .context.rendered_name }} を読み取ると、ビルドが停止し、代わりにどのキーを書くべきかが診断メッセージに示されます。空の値はレンダリングされません。セグメントが 1 つ欠けたアドレスはデプロイされてしまう誤った成果物であり、停止するビルドよりも悪い結果になるためです。
停止時に提示される対処法は、参照を書いた場所ではなくノードによって決まります。
- 独自のソースを一切提供せず、名前を報告しない provider の下にあるノードは、そのリソースが識別子にちなんで名付けられるため、停止時には
{{ .context.instance_id }}が示されます。正しい値が存在し、診断がそれを伝えます。 - ソースを提供し、名前を導出しない provider の下にあるノードには代替がありません。停止時には代替を提示する代わりにその旨が示されます。そこで識別子を案内すると、ノードが持たないリソースを名指すことになるためです。
この拒否は、provides: と、Recipe がインラインで書くその他すべてのテンプレート、つまり valuesMapping:、workload: 本体、各 artifacts: エントリ、各パイプラインステップの with: と when: に適用されます。
🔴 どちらのインポート形式も対象外です。 $import: を通じて提供される valuesMapping:、workload:、artifacts: エントリは、インポートがローカルファイルを指すかライブラリエントリを指すかにかかわらず、レンダリングで解決されるまで Recipe 内にテキストを持たないため、そのような本体の内部にあるこのキーへの参照はチェックされません。インポートするノードの provider が名前を報告する場合はその名前がレンダリングされ、報告しない場合は停止ではなく空の値がレンダリングされます。したがって、インポートされる本体がこのキーを読み取るのは、それをインポートするすべての Recipe が名前を報告する provider をバインドする場合に限られます。たとえば、チャートをソースとする helm Recipes 向けに書かれ、その旨を説明に記したライブラリエントリです。provider が名前を報告しない可能性のあるインポート元を想定した本体は、代わりにインポートする Recipe が設定する値を通じて名前を受け取ります。
Recipe の locals: エントリはこのキーを一切読み取りません。ローカルは Recipe の source: テンプレートとコンテキストを共有しており、ノードがソースを提供するかどうかは名前が依存する要素の 1 つであるため、そこでは名前が提供されません。したがって、ローカル内の {{ .context.rendered_name }} への参照は、provider が何を報告するかにかかわらず、レンダリングコンテキストで定義されていない参照に対する診断(E0060)で停止します。この診断では、そこで .context が提供する唯一のキーとして .context.instance_id が示されます。キーは、それを必要とする provides: エントリまたはインラインテンプレートで読み取ってください。
Feature アタッチメント自身のテンプレートについて
Feature アタッチメントの FeatureRecipe が書くテンプレート、つまり locals:、source:、provides:、
injectMapping:、valuesMapping:、workload:、各 artifacts: エントリ、各パイプラインステップの
with: と when: では、{{ .context.rendered_name }} はホストコンポーネントの名前です。これは、ホスト自身の provider がホスト向けにレンダリングするリソースについて報告する名前であり、ホスト自身の Recipe が読み取る値と同じです。これは {{ .context.instance_id }} と対になり、これらのテンプレートではホストコンポーネントの識別子を表します。アタッチメント自体は .attachment_name です。コンポーネントの接続の 1 つに書かれたアタッチメントは、消費側コンポーネントの名前を読み取ります。そのコンポーネントがホストだからです。
アタッチメント自身のリソース名を組み立てる際に使うべきキーはこれです。アタッチ先のコンポーネントにちなんで Secret、ルート、ポリシーを名付ける FeatureRecipe には、プラットフォームが受け入れる名前が必要ですが、記述どおりのホストの識別子は、アンダースコアや大文字を含む場合には受け入れられません。
helm では、my_db という名前のコンポーネントは my-zudb を報告するため、アタッチメント root に対して
{{ .context.rendered_name }}-{{ .attachment_name }} と名付けた Secret は
my-zudb-root としてレンダリングされます。一方 {{ .context.instance_id }} では my_db-root となり、クラスタに拒否されます。
この値は、アタッチメントがどの provider を通じてレンダリングされても、ホストの値のままです。
このキーは、ホストの provider が名前を報告する場合(helm では、Recipe がチャートを提供するか workload: を宣言するホスト)には存在し、報告しない場合(成果物セットのみを配置するホストや、その他の provider 上のホスト)には存在しません。そのようなホストのアタッチメントでこれを読み取ると、レンダリングコンテキストで定義されていない参照に対する診断(E0060)でビルドが停止し、そこで .context が定義するキーが一覧表示されます。{{ .context.instance_id }} はその中に含まれ、そのようなホストではホスト自身のリソースがこれにちなんで名付けられます。したがって、名前を報告しない可能性のあるホスト向けに書かれた FeatureRecipe は、代わりに識別子を読み取ります。
この拒否は、FeatureRecipe がインラインで書くテンプレートのうち、injectMapping: 以外に適用されます。
injectMapping:、および FeatureRecipe が $import: を通じて提供する valuesMapping:、workload:、artifacts: エントリはチェックされません。名前を報告しないホストでは、そこでの参照は停止せず空の値をレンダリングします。
アタッチメントがその作成者の提供したチャートを配信する場合、そのチャートのテンプレートは意図的にホストコンポーネントのリリース名に対してレンダリングされます。代わりにアタッチメントから導出すると、チャートの作成者が宣言し、すでにデプロイしている可能性のあるリソースの名前が変わってしまうためです。1 つのホスト上の 2 つのアタッチメントを区別する値は .attachment_name です。../providers/helm.md
の「How the release name is derived」を参照してください。
接続のアタッチメントから導出される名前
接続が持つアタッチメントは消費側コンポーネントのアタッチメントであり、<alias>.<slot> という名前を持ちます。たとえば、エイリアス gpt の下に書かれた接続の credential スロットであれば gpt.credential です(Aggregate の接続エントリを参照)。この合成された名前が、その FeatureRecipe がレンダリングに用いる .attachment_name であり、ドットを含みます。
ここから 2 種類の名前が生じ、両者はドットの扱いが異なります。
FeatureRecipe が合成する名前は、そのテンプレートが書いたとおりになります。 標準ライブラリの認証情報の実現は、そのリソースを {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }} と名付けます。そのため、router という名前のコンポーネントの gpt 接続上の認証情報は、ドットを含む 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— このページで説明する停止と、その出力される メッセージ。