コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

命名の慣例

この章では、Aggrega で記述するコンテンツに適用される命名と大文字・小文字の規則を扱います。ユーザーが記述するインスタンス名のパターン、DSL におけるフィールド名の大文字・小文字の使い分け、ユーザーではなくプラットフォームが定義する識別子に使われる大文字・小文字の表記、そして YAML の記述面で使用するコメント構文です。

インスタンス名

ユーザーが記述するインスタンス名(開発者が component、feature、aggregate、サブシステム、boundary、そして uses ソケットとエイリアスに対して記述するキー)は、すべて単一のパターン ^[a-zA-Z0-9_-]+$ に一致します。kebab-case(pii-filter、my-agent)と snake_case(openai_key、db_credentials)のどちらも有効です。チームはどちらでも好みの慣例を採用できます。

使用できる文字: 英数字(a-z、A-Z、0-9)、ハイフン(-)、アンダースコア(_)。その他の文字は使用できません。

例:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
パターン適用範囲例
^[a-zA-Z0-9_-]+$ユーザーが記述するすべてのインスタンス名web-server, openai_key, pii-filter

このパターンは、解決時に JSON Schema の patternProperties によって強制されます。

component 名のコストと、一部のターゲットで大文字のコストが高くなる理由

上記のパターンは、何を記述できるかを示します。名前のコストは別の問題であり、component がデプロイされるターゲットによって異なります。そのため、ビルドが名前を拒否した時点ではなく、名前を選ぶ前に知っておく価値があります。

component の名前は、それが出力するすべてのリソースに付与されるアイデンティティとなり、各ターゲットはそのアイデンティティから独自の名前を導出します。チャートインストーラーはリリース名を導出し、コンテナオーケストレーターはサービス名を導出します。パターンより狭い文字セットを持つターゲットは、許容しない文字を保持できません。また、Aggrega はそのような文字を類似の文字に黙って置き換えることはしません。作成者が区別できる 2 つの名前が、クラスター内で 1 つの名前になってはならないからです。そのため、ターゲットが許容しない文字は代わりにエスケープとして書き出され、エスケープは置き換える文字より長くなります。

実際の帰結として、大文字は一部のターゲットではコストがかからず、他のターゲットではコストが高くなります。

  • 名前に大文字を許容するターゲット(たとえばコンテナオーケストレーションの compose ファイル)では、PaymentsAPI は記述したとおりにそのまま引き継がれ、コストは 11 文字です。
  • 名前が小文字のみのターゲット(チャートインストーラーのリリース名)では、すべての大文字がエスケープされ、大文字 6 文字だけの名前でも、そのターゲットが受け入れる長さをすでに超えます。

2 つ目の影響があり、こちらのほうが深刻です。エスケープはハイフンで始まります。そのため、名前が小文字またはは数字で始まることを要求するターゲットは、最初の文字が許容されない文字である名前を、残りがどれほど短くても拒否します。どれだけ短くしても解決しません。

ガイダンスはこの 2 つの影響から導かれます。 小文字と数字を使い、単語の間にはハイフンを入れ、名前は小文字で始めてください。payments-api は、Aggrega が provider を提供するすべてのターゲットで変更されずに引き継がれます。payments_api は compose ファイルでは引き継がれますが、helm ターゲットでは引き継がれません。helm ターゲットのリソース名はアンダースコアを許容しないため、component にちなんで命名される Service、ワークロード、リリースは payments-zuapi と綴られます。PaymentsAPI はそこでさらにコストが高くなります。そのようなリソースのアドレスを公開する Recipe は、ターゲット自身の綴りを予測するのではなく読み取ります。templates/rendered-resource-names.md を参照してください。

先頭の数字は記述可能で、compose ファイルではコストがかかりませんが、helm ターゲットは拒否します。Kubernetes の Service 名は文字で始まる必要があり、チャートや合成されたワークロードが出力する Service は component にちなんで命名されます。そのため、1cache という名前の component は、クラスターが拒否する Service をレンダリングするのではなく、helm ビルドを停止させます。この拒否では component が示され、Service 名は文字で始まる必要があると述べられます。

これはいずれも、コンパイラが独自に適用する規則ではありません。コンパイラはどのターゲットの命名規則も保持せず、制限を作り出すこともありません。各ターゲットの provider が自身の名前について責任を持つため、名前が拒否されるのは、component が実際にデプロイされるターゲットがその名前を使用できないと示した場合のみです。その拒否には当該ターゲット自身の理由が含まれ、記述した spec.components のキーを指し示します。あるターゲットでは問題なく、別のターゲットでは拒否される名前は、不整合ではなく想定どおりの動作です。

Aggrega 自身が組み立てる名前(たとえば boundary に付加された feature のアイデンティティ)は逆の方法で扱われます。拒否されるのではなく、ターゲットに収まるよう短縮されます。これらは複数の場所で記述された部分から組み立てられ、どの作成者も単独ではその長さを把握できないためです。拒否されるのは、記述した名前だけです。

予約済みパス区切り文字としてのドット

ピリオド文字(.)は、ユーザーが記述するすべてのインスタンス名で使用が予約されています。ドットは、aggregate をまたぐ component 参照のためにコンパイラが生成するパス区切り文字という構造上の役割を担います。

ルートの Aggregate が、main-db という名前の component を含む data-layer という名前のサブ aggregate をインポートすると、コンパイラは aggregate のインスタンス名と component のインスタンス名をドットで連結し、平坦化された絶対 ID data-layer.main-db を構築します。このドット付きパスは次の箇所に現れます。

  • 開発者の uses ターゲット: target: data-layer.public_db — ネストされた aggregate からエクスポートされた component を参照します。
  • ビルド自身の診断: その component に関する停止や警告は、ドット付きパスでその component を示すため、目にする名前でそのままドキュメント内を検索できます。

区切り文字は名前には及びません

ドット付きパスはドキュメント内のアドレスであり、デプロイ先のターゲットが受け付ける名前ではありません。Kubernetes の Service 名はドットを一切受け付けません。さらに、クラスタのアドレス内のドットはサービスとその所属する名前空間を区切るものであるため、ドット付きの名前をホストとしてコンシューマーに渡すと、失敗するのではなく別のサービスに解決されてしまいます。

そのため、区切り文字は、ビルドが component のアイデンティティから導出するすべての名前とラベルから書き出されます。置き換えではなく書き出しです:data-layer.main-db は data-layer-zdmain-db になります。ターゲットが受け付ける文字で置き換えると、2 つの異なる component が 1 つの名前に行き着いてしまいます — data-layer.main-db と、誰かが data-layer-main-db と記述した component です — そして 2 つの component が行き着く名前はどちらも識別しません。

これが及ぶ範囲と、及ばない範囲は次のとおりです。

  • アイデンティティから導出される名前とラベルに及びます — Aggrega が合成するリソースの metadata.name、aggrega.ai/component-id ラベルと app.kubernetes.io/name ラベル、それらに一致するセレクター、出力されるファイル名、{{ .context.instance_id }}、そして helm の release 名のように provider が自ら導出する名前です。これらは連動して変わるため、Recipe がリソースを示すキーから組み立てるアドレス — ターゲットがアイデンティティにちなんで名前を付ける場合は .context.instance_id、ターゲットが独自の名前を報告する場合は .context.rendered_name — は、ビルドが出力するリソースを引き続き正しく示します。
  • 記述した名前には及びません。 区切り文字を含まない component 名はバイト単位でそのまま戻るため、出力でドキュメントと異なる綴りになるのは、インポートされた Aggregate が提供する component だけです。
  • 作成者が提供した chart やフラグメント内の名前には及びません。 それらは記述した人のものであり、サードパーティの chart から持ち込まれた名前 — ドットが正当である <plural>.<group> 形式のカスタムリソース名など — は、その chart が記述したとおりに出力されます。

🔴 この最後の点は、Recipe が何を公開すべきかに影響し、このページで最も間違えやすい点です。 提供された chart 自身のテンプレートは、プラットフォームが渡すアイデンティティ — 上記のアルファベットではなくそのプラットフォーム独自のアルファベットで書かれた release 名 — にちなんでリソースに名前を付け、helm ターゲットは合成する workload にも同じ release 名にちなんだ名前を付けます。そのため、提供したソースからレンダリングされた出力や、そのようなターゲットの下で合成された workload では、{{ .context.instance_id }} はそれらのリソースが持つ名前ではなく、2 つのアルファベットが異なる場合、それから公開したアドレスは何も示しません。プラットフォームの名前を持つキーと、それを報告する provider については templates/rendered-resource-names.md を参照してください。

区切り文字の書き出しは文字数を消費し、長さに上限のある名前では文字数が足りなくなることがあります。 区切り文字は 1 文字ではなく短いエスケープに置き換えられるため、修飾されたアイデンティティは、書き出された形ではドキュメント上の見た目より少し長くなります。これが問題になるのは、変換後の名前に上限がある場合だけです。component をレンダリングするターゲットは受け付けるラベル値の長さを示し、書き出されたアイデンティティがそれを超える場合、ビルドはターゲットに拒否される値を出力するのではなく停止します。停止時には、アイデンティティ自体が収まるべき長さ — 書き出される前の長さであり、その範囲内で選んだ名前は一度で通ります — が示されます。対処法は、作成した部分を短くすることです:インポート側のドキュメントがサブ aggregate に付ける名前か、その中の component 自身の名前です。

区切り文字は名前が見た目より長く書き出される主な理由ですが、唯一の理由ではありません。作成した名前が正当に取りうる形のうち 2 つも、そのままにするとエスケープが曖昧になるため、記述どおりには持ち込めません:ハイフンで終わる名前と、ハイフンの直後に z が続く名前です。どちらも同じ方法、同じコストで書き出されます。それ以外の作成された名前はすべてバイト単位でそのまま戻るため、英字、数字、アンダースコア、単語間のハイフンで構成した名前はこれらの影響を一切受けません。

コンポーネント自身の uses ブロック内のソケット名は、カタログエンティティの usesSchema のキー(宣言されたソケット)に一致するか、開発者独自のアドホックなソケットを指します。後者は、usesSchema をまったく宣言していないエンティティでもビルドできます。宣言されたソケットと 1 文字違いの名前には、両方の綴りを示す警告が出ます。Release のエッジごとの uses と Feature のアタッチメントの同様の指定では、エンティティが宣言するソケットしか指定できず、それ以外の名前は unknown-uses-socket 検証エラーで失敗します。

フィールドの大文字・小文字表記

DSL は、開発者向けの YAML(人が記述するもの)と、コンパイラ内部のコントラクト(テンプレートやツールが利用するもの)を分離しています。

  • 開発者向け YAML(camelCase): Aggregate、Release、Component、Feature、Recipe、FeatureRecipe、Manifest、Plugin の各スキーマにおける複数語のフィールド名は camelCase を使います。例: exportedComponents、syncWave、subDirectory、featuresSchema、usesSchema、valuesMapping、injectMapping、executionScope、appliesTo、appliesToAnyOf、conflictsWith。Kubernetes API の慣例に従います。
  • 内部コントラクト(snake_case): IR Graph スキーマと Template Context スキーマにおける複数語のフィールド名は snake_case を使います。Recipe の作成者が目にするユーザー向けの例: instance_id(.context.instance_id 内。Recipe のアイデンティティ)、inject_raw(.inject_raw 内。.context の下のキーではなく .inject と並ぶトップレベルの柱で、変更されていない注入コントラクト)、attachment_name(アタッチメントの FeatureRecipe のコンテキスト内。アタッチメントが埋めるスロット、またはアタッチ時に使われた名前を識別します)。JSON API の慣例に従い、Go の JSON 構造体タグの生成とも整合します。
  • 単一語のフィールド: コンテキストにかかわらず小文字です。例: values、infra、inject、provides、locals、features、labels、annotations、boundaries、components、subsystems、pipeline、source。

開発者が自分で記述する YAML で snake_case に出会うことはなく、テンプレート作成者が Go テンプレートで camelCase に出会うこともありません。スキーマへの追加はこれらの慣例に従います。

1 つの記述で交差する 3 つの表記

Recipe の記述では、1 つの記述の中で 3 つの表記の慣例すべてが日常的に交差します。スキーマで定義された DSL フィールドは camelCase、ユーザーが記述するインスタンス名は kebab-case または snake_case、テンプレートコンテキストの参照は snake_case を使います。これらの交差をそれぞれ別の慣例として認識する作成者は、結果の YAML をすっきり読めます。表記を 1 つの慣例として合理化しようとする作成者は、その境界で苦労します。

代表的な実例は、Recipe の valuesMapping: テンプレートが、テンプレートコンテキストを通じてレンダリング対象の Component インスタンスを参照する場合です。

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

3 つの表記、1 つの記述:

  • valuesMapping — camelCase。Recipe のマッピングテンプレートのためにスキーマが定義する DSL フィールド名です。言語の開発者向け YAML が Kubernetes API の慣例に従うため、camel になります。
  • web-server(レンダリング対象の component を通じて間接的に参照)— kebab-case。Aggregate 内でユーザーが記述したインスタンス名で、開発者がハイフン付きの形を選んでいます。web_server(snake_case)でもかまいません。どちらもインスタンス名のパターン上有効です。
  • instance_id、image — snake_case。テンプレートコンテキスト内のフィールド名です(.context.instance_id、.values.image)。IR Graph とテンプレートコンテキストが JSON-API の慣例に従い、Go の JSON 構造体タグの生成と整合するため、snake になります。

3 つの表記は互換ではありません。Recipe の作成者が {{ .context.instanceId }}(camelCase)と書くと、ビルドは停止します。.context は自身のキーを宣言しており、instanceId はそのいずれでもないため、何かがレンダリングされる前に参照が拒否され、診断には .context が実際に定義するキーが一覧表示されます。errors/fatal-halts.md の「Template references a root the render context does not define(テンプレートがレンダーコンテキストで定義されていないルートを参照しています)」を参照してください。開発者が web.server(ドット付き)と書くと、ドットはパス区切り文字として予約されているため、インスタンス名のパターンによって拒否されます。目指すべきは、読むときも書くときも 3 つの慣例を念頭に置き、どの表記が適用されるかは境界(YAML とテンプレートのどこにいるか)で判断することです。

プラットフォーム定義の識別子

ここまでの内容はすべて、オーサリング面での名前を対象としています。つまり、自分で選ぶインスタンス名、言語が定義して値を埋めるスキーマフィールド、読み取るテンプレートコンテキストのキーです。これとは別に、プラットフォーム自身が定義し、利用者は読み返すか入力するだけの識別子を扱う区分が 2 つあります。両者が分かれているのは役割が異なるためであり、その役割が形を決めます。

記述的な区分:一律に kebab-case。 この区分の識別子は、何を指すかを言葉で表すため、何も調べずに読んで対処できます。CLI フラグ、公開時 lint のルール ID、診断クラスコード、停止条件が登録されるコードはすべてこの区分に属します。

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

診断クラスに抑制フラグがある場合、コードとフラグは同じ語を同じ順序で使います。unsupported-field は --no-unsupported-field-warnings で抑制されます。そのため、一致したクラスから使うべきフラグがわかり、読み替える必要はありません。クラスコードは、ツールがメッセージ本文を解析せずに検出結果を識別するために照合する安定した名前です。メッセージの文言は改善されることがありますが、コードは変わりません。

短縮コードの区分:文字 E と 4 桁の数字。 停止条件は短縮コード(E0007)も持ち、これは kebab-case でない唯一のプラットフォーム定義識別子です。理由は位置にあります。このコードはすべての停止診断の先頭に、カテゴリの横、これから読むファイルと行の前に置かれます。

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

記述的なコードはそこに置けません。最も長いものは、それだけで狭い端末の幅を埋めてしまい、どこを見るべきかを示す位置情報より前に来てしまいます。そこで先頭には幅を基準に選んだ識別子を置きます。このトレードオフは意図的なものです。4 桁の数字は条件について何も語らないため、すべての短縮コードは、それが指す条件とその条件が出力するテキストとともにエラーセンチネルのリファレンスに掲載されています。短縮コードは報告に引用し、検索に入力し、そこで解決してください。

2 つの区分は同じ条件を 2 つの方向から名付けるもので、どちらも他方を置き換えるものではありません。条件をキーにするツールを書くときは記述的なコードと照合し、人と条件について話すときは短縮コードを引用してください。

こことインスタンス名の両方に kebab-case が現れることは衝突ではありません。 インスタンス名のパターンは、書くことが許されるものについての規定です。そこでは kebab-case と snake_case のどちらも有効で、チームがどちらかを選びます。この区分は、プラットフォームが実際に書くものについてであり、選ぶ余地はありません。lint ルール ID の綴りを利用者が選ぶことはなく、プラットフォームがコンポーネント名の綴りを選ぶこともありません。

フィールドの大文字小文字の規則は変わりません。 オーサリングするスキーマフィールドは camelCase のまま、テンプレートコンテキストのキーは snake_case のままです。この区分の識別子はいずれも、どちらの面のフィールドでもありません。フラグ、ルール、検出結果のクラスを表す短く安定した名前です。そのため、診断コードが kebab-case であることは、スキーマフィールドの綴りについて何も意味しません。

ドキュメントパスの命名サフィックスの規律

言語全体の一部のフィールドは、ドキュメントパスの値を持ちます。これは別のドキュメント内の位置を指す文字列です(レンダリングされた Workload の volumes セクション、Component の featuresSchema エントリ、Manifest の mappings 層など)。値は RFC 6901 JSON Pointer の構文に従います。これは対象ドキュメント内のパスを識別する、スラッシュ区切りのトークンです。

RFC 6901 は、Aggrega におけるすべてのドキュメントパスのサーフェスに共通するパス文法の基準です。 Wasm プラグイン契約は、パスが RFC 6901 のポインターである RFC 6902 JSON Patch ドキュメントを受け取ります(plugins/plugin-contract.md の label-transform ロールの JSONPatch 出力を参照)。URI 文法のフォーマット文字列一覧は、Go テンプレート構文および Sprig ヘルパーと並べて RFC 6901 を挙げています(vocabulary/uri-grammar.md の「Format-string inventory」を参照)。Recipe ごとの .locals エクスポートは RFC 6901 を使い、Wasm Injector プラグインがプラグインパイプライン内で自身のステップの with ペイロードを通じて受け取る、合成された Workload 内の位置を指します。文法は 1 つで、それを利用するサーフェスは複数あります。

命名サフィックスの規律は、上記の Field Casing セクション全体と揃えた意図的なサフィックスの使い分けによって、これらのパス値をオーサリングする 2 つの側を区別します。

  • RFC 6901 JSON Pointer を持つスキーマフィールドは、camelCase の *Path サフィックスを使います。これらのフィールドは開発者向けの YAML スキーマの一部であるため、camelCase の慣例に従います。そのようなフィールドを宣言するエンティティのスキーマはありません。作成者が記述するドキュメントパスは、以下の .locals エクスポートキーです。
  • RFC 6901 JSON Pointer を持つ .locals のエクスポートキーは、snake_case の *_path サフィックスを使います。これらのキーは Recipe の内部エクスポートサーフェスの一部であり、その Recipe 自身の後続テンプレートと、.locals を参照する pipeline[].with ペイロードを通じて Wasm プラグインパイプラインによって読み取られます。そのため snake_case の慣例に従います。例:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" は、合成された Workload の volumes 配列の位置を公開します。
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" は、containers 配列の位置を公開します。
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" は、Terraform ネイティブのリソースパスを公開します。
    • root_path — .locals.root_path: "/data" は、レンダラーのパイプが利用するルートパスを公開します。

2 つのサフィックスの慣例は、Field Casing セクションの 2 層の慣例を反映しています。スキーマで定義されたフィールドは camelCase を使い、ユーザーがオーサリングした識別子や Recipe 固有の識別子は snake_case(または kebab-case)を使います。*Path / *_path のサフィックスの規律により、値がパス文法であることが識別子のレベルで見えるようになります。どちらかのサフィックスを目にした読み手は、値そのものを調べなくても、その値が RFC 6901 の構文に従うことがわかります。

具体例: Recipe の *_path エクスポートを利用する Wasm Injector。

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

*_path キーは Recipe 固有のエクスポートであり、containers_path / volumes_path の値は RFC 6901 JSON Pointer の文字列です。Injector プラグインはこれらの文字列を使って、レンダリングされた Workload の AST に対する JSONPatch 出力の位置を決めます。アタッチメントは自身の .locals ピラーでこれらに到達します。.context.uses[].locals というフィールドは存在しないため、利用側は uses エッジを越えて対象の locals を読み取ることはできません。エッジを越えるのは対象の provides です。

より広いフォーマット文字列一覧(Go テンプレート構文、Sprig 関数、SemVer 正規表現やラベルセレクタ文法と並ぶ JSON Pointer)については、vocabulary/uri-grammar.md の「Format-string inventory」を参照してください。RFC 6901 のポインターでアドレス指定される RFC 6902 のパッチを受け取る Wasm プラグイン契約のサーフェスについては、plugins/plugin-contract.md を参照してください。

コメント構文

コメント文字は周囲の言語によって異なります。

  • YAML コンテキスト(すべての Aggrega エンティティの既定の記述面):# を使用します
  • Go テンプレートコンテキスト(Recipe の valuesMapping: ブロックスカラー、FeatureRecipe の injectMapping: ブロックスカラー、MappingLibrary のマッピングエントリ、アサーションブロックの assertions: 本体の内部):テンプレートエンジンが認識してレンダリング時に除去するテンプレートコメントには {{/* ... */}} を、テンプレート本体の外側の YAML レベルのコメントには # を使用します。

schema:、usesSchema:、featuresSchema:、parameters: の下にあるコンパクト形式のスキーマは全体が YAML です。インラインのフィールドドキュメントには、フィールドごとの description: アノテーションが文書化された記述面です(port: { type: integer, description: "TCP listen port" })。