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

誰も書いていない Features をアタッチするポリシー: `annotation-transform` で注入されるアノテーション

あるガバナンスポリシーが、ショップのすべてのコンポーネントにプラットフォームの監視と AWS IAM ロールを与えます。ポリシーはアノテーションを追加することでこれを行います。Manifest は 2 つのアノテーションキーを 2 つの Features にバインドしており、バインドされたキーの下にあるアノテーションは Feature のアタッチメントに展開されます。そのため、ポリシーが追加するアノテーションによって、各コンポーネントに Prometheus ServiceMonitor と Kubernetes ServiceAccount がもたらされ、Aggregate も Release もそのどちらも記述しません。

ポリシーは annotation-transform ロールに、CLI に組み込まれたポリシーエンジン(Rego と CEL)ごとに 1 回ずつアタッチされます。中心となる証明は、同じアノテーションを手で記述した対照用の Release です。ポリシーなしでビルドすると、それはポリシーがアノテーションを付ける Release とバイト単位で同じファイルをレンダリングします。

構築されるもの

インスタンスカタログの Componentrelease.yaml で持つもの
apiexample/compute/service何も送信しない
workerexample/compute/service何も送信しない
gatewayexample/compute/service独自の監視アノテーション、間隔は 10 秒

3 つとも Helm を通じて Kubernetes 向けに dist/shop/helm/ へコンパイルされます。example/compute/service は標準ライブラリのカタログにあるデモ用の Component です。そのすべてのインスタンスは core/prometheus-exporter のアタッチメントを持たなければなりません。これは Component が定め、ビルドが確認する要件です。

2 つのアノテーションバインディング

manifest.yaml は 2 つのアノテーションキーに意味を与えます。

features:
type:
core/prometheus-exporter: helm/prometheus-exporter:1.0.0
core/aws-irsa: helm/aws-irsa:1.0.0
annotations:
feature.aggrega.ai/monitoring:
feature: core/prometheus-exporter
maps:
infra:
- interval
- port
- path
aws-role:
feature: core/aws-irsa
maps:
infra:
- role_arn

複数のサブキーをルーティングするバインディングは、その各サブキーを名指しするオブジェクトを値として受け取ります。そのため feature.aggrega.ai/monitoring は {interval: …, port: …, path: …} を受け取ります。1 つのサブキーをルーティングするバインディングは文字列を受け取るため、aws-role はロールの ARN を受け取ります。アノテーションが展開されてできるアタッチメントには、そのキーに基づく名前が付きます。core/aws-irsa は ServiceAccount にアタッチメントの名前を付けるため、このキーにはドットもスラッシュも含まれていません。

ポリシーのアタッチ

.aggrega-config.yaml はレジストリとして hub を指定し、カタログのディレクトリは指定せず、ガバナンスのアタッチメントも宣言しません。ポリシーは、ビルドが --config で指定するファイルによってアタッチされます。Rego エンジンには governance-rego.yaml、CEL エンジンには governance-cel.yaml です。Rego 用のファイルの内容は次のとおりです。

plugins:
governance:
- uri: governance/rego:0.9.0
role: annotation-transform
with:
sources:
- policies/platform-defaults.rego

--config はその実行で使うグローバル設定ファイルを指定し、マシンが本来読み込むファイルの代わりになります。このワークスペースの .aggrega-config.yaml は引き続きその上に重ねられます。

0.9.0 は、hub が各エンジンの Plugin エンティティを公開しているバージョンであるため、アタッチメントはワークスペースが読み込むレジストリから、またはそれを含むそのリリースの aggrega バイナリから解決されます。実際に動くエンジンは、アタッチメントがどのバージョンを指定していても、ビルドを実行している aggrega バイナリに組み込まれたものです。監視アノテーションが受け取るオブジェクトには、サブキーのオブジェクトを注入できるエンジンが必要であり、0.8.7 より前のリリースのエンジンにはそれができません。

annotation-transform ポリシーが読み取るもの

annotation-transform のポリシーは 2 つのものを読み取ります。

  • input.targets は、アノテーションを付与できるすべてのコンポーネントを列挙します。各ターゲットは boundary_path、component_name、そして Release がそのコンポーネントに書いた annotations を持ち、各値は書かれたとおりです。
  • input.binding_keys は、Manifest がバインドするアノテーションキーを列挙します。

aggrega build --release <release> --dry-run --policy-input <dir> は、各ロールが受け取るペイロードを <dir> に書き出し、それ以外は何も書き出しません。release.yaml のビルドでロックファイルが埋まった後に実行します。

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '.binding_keys' payloads/annotation-transform.json
# ["feature.aggrega.ai/monitoring","aws-role"]
jq -c '.targets[]' payloads/annotation-transform.json
# {"boundary_path":"shop","component_name":"api","annotations":{}}
# {"boundary_path":"shop","component_name":"worker","annotations":{}}
# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}

ターゲットの annotations には、Release がコンポーネント自体に書いた内容が入ります。境界の aggrega.ai/namespace はそこに含まれません。

ポリシー

policies/platform-defaults.rego は、アノテーションごとに 1 つの決定を annotations の下に集めます。各決定は、ターゲットを読み取ったときの 2 つのフィールドでターゲットを指定し、続いてキーと値を示します。

annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": monitoring,
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
monitoring in input.binding_keys
some t in input.targets
not monitoring in object.keys(t.annotations)
}
annotations contains {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": role,
"annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),
} if {
role in input.binding_keys
some t in input.targets
not role in object.keys(t.annotations)
}

各ルールは input.binding_keys に含まれるキーに対してのみ発火するため、ポリシーは Manifest が意味を与えていないものを何も追加しません。各ルールは、すでにそのキーを持つターゲットもスキップします。コンポーネントがすでに持つキーに対する決定は、Release が書いた値を置き換えます。この判定がなければ、gateway の 10 秒間隔はポリシーの 30 秒に置き換えられてしまいます。

policies/platform-defaults.cel は、同じ 2 つの決定を 1 つの式で表し、2 つのリストを + で連結します。この式言語には sprintf がないため、マップのキーは object.keys ではなく in で判定し、ロールの ARN は + で連結します。式のうちロールに関する半分は次のとおりです。

+ input.targets
.filter(t, "aws-role" in input.binding_keys
&& !("aws-role" in t.annotations))
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "aws-role",
"annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name,
}),

ビルドがレンダリングするもの

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

dist/shop/helm/ の下に 12 個のファイルを書き出します。各コンポーネントの Deployment と Service、監視アノテーションが展開されてできる ServiceMonitor、そして aws-role アノテーションが展開されてできる ServiceAccount です。ポリシーが注入したアノテーションから生成された、api の ServiceMonitor の spec は次のとおりです。

spec:
selector:
matchLabels:
app.kubernetes.io/name: api
endpoints:
- port: metrics
interval: 30s
path: /metrics

gateway のものは、その Release エントリが書いた値である interval: 10s を持ちます。api が実行時に使う ServiceAccount は、注入された aws-role から次のように生成されます。

apiVersion: v1
kind: ServiceAccount
metadata:
name: api-aws-role
namespace: shop
annotations:
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api"
aggrega.ai/boundary-path: shop
aggrega.ai/recipe-uri: "aws-irsa:1.0.0"
[… omitted: the labels, which carry the version of the aggrega binary that built the file]

注入しても手書きしても同じファイル

release-by-hand.yaml は、ポリシーが注入するアノテーションを各コンポーネントに手書きした release.yaml です。ポリシーをアタッチせずにビルドすると、

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

どちらのエンジンでポリシーをアタッチした release.yaml とも、バイト単位で同じ 12 個のファイルを書き出します。この比較から除外されるものはありません。アノテーションが注入されたかどうかは、レンダリングされたどのファイルにも記録されません。check.sh は実行のたびにツリーを比較します。

ビルドは、注入された値を Release に書かれた同じ値とまったく同じように読み取るため、その値は同じアタッチメントに展開されます。

注入が記録される場所

ビルドグラフがそれを記録し、--ir-graph がグラフを出力します。注入されたアノテーションを受け取ったすべてのコンポーネントは、Release のアノテーションの中に、プラグイン名を示す aggrega.ai/injected-by を持ちます。aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph の後、api は次のようになります。

"release_annotations": {
"aggrega.ai/namespace": "shop",
"aws-role": "arn:aws:iam::123456789012:role/shop-api",
"aggrega.ai/injected-by": "governance/rego"
},

記録はキー単位ではなくコンポーネント単位です。gateway も、その aws-role のためにこれを持ちます。アノテーションが展開されてできた各アタッチメントは、手書きのアノテーションの場合と同様に、グラフ内で "origin": "annotation" を持ちます。

Helm ターゲットは aggrega.ai/injected-by アノテーションをレンダリングせず、その旨を伝えます。このビルドでは、注入を受けたコンポーネントごとに 3 つの警告が出力に加わります。api の最初の警告は次のとおりです。

warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it

--no-unsupported-field-warnings はこの種類の警告を抑止し、ビルドが書き出す内容は何も変えません。

このロールはアノテーションを追加するだけで、それ以外は何もしない

決定は 1 つのコンポーネント、1 つのアノテーションキー、その値を指定します。決定の中には、コンポーネントを追加したり、ラベルを変更したり、Feature を直接アタッチしたりするものは何もありません。ポリシーが Feature に到達できるのは Manifest がバインドするキーを通じてだけであり、それがどの Feature かは Manifest が決めます。

決定はアノテーションを削除することもできません。その値は文字列またはサブキーのオブジェクトであり、null はその注入を名指しして拒否されます。null は、作成者がコンポーネントを継承されるはずのアノテーションから外すための手段だからです。

バインディングが 3 つのサブキーをルーティングする場所に文字列がある場合

governance-monitoring-as-string.yaml は policies/monitoring-as-string.rego をアタッチし、これは監視キーの下に文字列 "30s" を注入します。このバインディングは 3 つのサブキーをルーティングしますが、文字列はそのどれも指定しないため、

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

停止し、1 で終了し、dist/ を書き出しません。ポリシーは api と worker にこの文字列を注入しており、それぞれが拒否されます。各拒否メッセージは値を注入したプラグインと、それがアタッチされたロールを示すため、値は誰も書いていない Release の行ではなく、それを決定したポリシーまでたどれます:

[… omitted: a warning that the attachment is in the global configuration named with --config]
[OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")
---
[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations
a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")

ポリシーがない場合

ガバナンスのアタッチメントなしでビルドした release.yaml は、

Terminal window
aggrega build --release release.yaml --auto-pull

停止します。その Component は core/prometheus-exporter アタッチメントを要求しますが、api にも worker にもそれを与えるものがありません。

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker
missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")

gateway が名指しされないのは、その Release エントリが独自の監視を書いているためです。ポリシーをアタッチすると、同じ Release がビルドできます。注入されたアノテーションが展開されてできたアタッチメントは、手書きのものと同様に要件を満たします。

ロックファイルに記録される内容

annotation-transform のアタッチメントはビルドがレンダリングする内容を変えるため、ロックファイルがそれを固定します。Rego でのビルド後、release.lock は mutators: の下にアタッチメントを持ち、そのプラグイン、ロール、ポリシーファイルの内容とダイジェストを記録します。

mutators:
- plugin: governance/rego
role: annotation-transform
sources:
- content: |
[… omitted: the policy file, as written]
digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b
path: platform-defaults.rego

さらに plugins: の下にプラグインを固定します。

plugins:
- uri: governance/rego
[… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice]
referenced_from:
- governance/rego:0.9.0

アタッチメントは hub が公開しているバージョンを指定しているため、固定はワークスペースが読み込むレジストリを通じて、またはそのリリースの aggrega バイナリから解決されます。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example policy-annotation-transform

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd policy-annotation-transform

ビルド

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

標準ライブラリのカタログが、ここにあるすべての Component、Feature、Recipe、FeatureRecipe と、両エンジンの Plugin エンティティを提供します。 これらは、.aggrega-config.yaml が指定するデフォルトのレジストリである hub.aggrega.ai から解決されます。--catalog でカタログのチェックアウト(入手方法)を指定すると、レジストリからは何も取得しないため、ビルドはオフラインで動作します。--auto-pull はビルド中に各 Release のロックファイルを埋めます。ロックファイルとレンダリング結果は生成されるものであり、同梱はされません。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `policy-annotation-transform` フォルダーがない場合は、`example` を `policy-annotation-transform` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `policy-annotation-transform` フォルダーに例が書き込まれます。次に、`aggrega build` を実行してその `--config` フラグを受け付ける `cli-build` ツールを、`workspace_root` を `policy-annotation-transform`、`release` を `release.yaml`、`auto_pull` を true、`config` を `governance-rego.yaml` に設定して呼び出し、続いて同じ方法で `config` を `governance-cel.yaml` に設定してもう一度呼び出してください。最後に、`workspace_root` を `policy-annotation-transform`、`release` を `release-by-hand.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。各ビルドが書き込んだファイルを教えてください。それらは `policy-annotation-transform/dist/` の下にあります。

すべてのビルドの確認

このセルフチェックは、使用する共有ビルドヘルパーを含むドキュメントリポジトリのチェックアウトで実行されます。aggrega scaffold --example が書き出したコピーには、そのヘルパーは含まれません。

Terminal window
./check.sh

check.sh は build-release ヘルパーを通じて 5 つのビルドを行い、各結果をこのページが説明するものと照合します。

  • ポリシーなしの release-by-hand.yaml が基準です。アノテーションが展開されてできる 6 つのファイルをレンダリングしなければなりません。
  • ポリシーなしの release.yaml は、api と worker について E0162 で停止しなければならず、それ以外のコンポーネントについて停止してはなりません。
  • ポリシー付きの release.yaml は、各エンジンで 1 回ずつビルドされます。各ビルドは、基準のファイルをバイト単位で同じに書き出し、ロックファイルにプラグインを固定し、3 つのコンポーネントすべてをそのプラグインによる注入として記録しなければなりません。
  • 仕込んだ文字列を含む release.yaml は、上記の拒否で停止しなければなりません。

ビルドごとに 1 行を出力し、続いて 2 つのバインディングがレンダリングしたファイルを出力します。いずれかの結果が異なれば、そのビルドの出力を表示して 1 で終了します。

POLICY RELEASE EXIT EXPECTED VERDICT
----------------------------------------------------------------------------------------------------
none release-by-hand.yaml 0 reference OK: the six attachments' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml:
shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml
shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml
shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml
shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml
shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml
shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.

各ビルドは、一時ディレクトリに作成したこのワークスペースのコピーの中で実行されます。コピーの .aggrega-config.yaml にあるカタログのパスは、そこからでも解決できるよう絶対パスに書き換えられます。このディレクトリには何も書き込まれません。build-release ヘルパーが解決するバイナリを使うため、AGGREGA_BIN でそれを選択でき、-- 以降の引数はすべてのビルドに渡されます。終了ステータスが判定のすべてです。

コンパイラが解釈しない箇所

コンパイラは、コンポーネントとバインドされたキーをポリシーに渡します。ポリシーが決定したアノテーションを追加し、他のアノテーションと同じように Manifest のバインディングを通じてそれらを展開します。サービスを監視すべきであること、スクレイプ間隔とは何か、コンポーネントをどの IAM ロールで実行すべきかは、コンパイラは知りません。それらの意味はポリシーと Manifest に属します。ロール、ペイロード、決定キーについてはガバナンスソケットを参照してください。ポリシーを使わないアノテーションの展開については annotation-driven-monitoring を参照してください。

ファイル

  • aggregate.yaml — 3 つのサービス。アノテーションはありません。
  • manifest.yaml — コンポーネント型と 2 つの Features をそれぞれの Helm Recipes に、2 つのアノテーションキーを 2 つの Features にバインドします。
  • release.yaml — ポリシーがアノテーションを付ける Release。アノテーションを書いているのは gateway だけです。
  • release-by-hand.yaml — 対照群。すべてのアノテーションを手書きしています。
  • .aggrega-config.yaml — デフォルトのレジストリ。ガバナンスのアタッチメントはありません。
  • governance-rego.yaml、governance-cel.yaml — 各エンジンを通じて annotation-transform にアタッチされるポリシー。それぞれ --config で指定します。
  • governance-monitoring-as-string.yaml — 仕込んだ誤り。--config で指定します。
  • policies/platform-defaults.rego、policies/platform-defaults.cel — ポリシー。エンジンごとに 1 つです。
  • policies/monitoring-as-string.rego — 仕込んだ誤り。
  • build-release.sh — 1 つの Release をビルドし、同等の aggrega build コマンドを表示します。
  • check.sh — 5 つのビルドを行い、各結果を確認します。