パイプラインステップを使うべきとき
FeatureRecipe には、Feature が提供する出力を形作る方法が 2 つあります。独自のドキュメントを生成する テンプレート化された FeatureRecipe と、レンダリングされた出力に対して Wasm プラグインを実行する パイプラインステップ(pipeline:)です。この 2 つは異なる問題を解決します。このページは判断のためのガイドです。パイプラインステップを使うのはちょうど 2 つのトリガーに該当する場合だけで、それ以外はすべてテンプレート化された FeatureRecipe を使います。
2 つのツール
テンプレート化された FeatureRecipe はローカルかつ生成的です。 Go テンプレートを通じて、自身の 値から 自身の ドキュメントを生成します。たとえばサイドカーの ConfigMap、ポリシー CRD、オートスケーラーオブジェクトなどです。出力されるものはすべて、Feature の values: と infra:、およびテンプレートに渡されるレンダリングコンテキストの関数です。他のエンティティの出力に手を伸ばすことはなく、自身のドキュメントを追加します。生成すべきものが Feature がすでに知っている情報から書ける場合は、テンプレート化された FeatureRecipe が適切でより簡単なツールです。プラグインもパイプラインも必要ありません。
パイプラインステップはグローバルかつ変換的です。 レンダリングの 後 に、ビルドがすでに出力した実際のドキュメントセットに対して実行されます。ホストはキー付きのドキュメントセット全体をステップに渡します。ステップは実際の 内容 を読み取り、対象とするドキュメントを選択し、その構造に対する精密な RFC 6902 パッチを返します。あるいは副作用として新しいドキュメントを出力します。ステップは Feature が宣言した内容だけでなく、実際にレンダリングされた内容に基づいて判断します。この到達範囲こそが存在理由のすべてであり、同時に控えめに使うべき理由でもあります。
パイプラインステップを使う 2 つのトリガー
パイプラインステップを使うのは、次のいずれかに該当する場合だけです。どちらにも該当しない場合は、代わりにテンプレート化された FeatureRecipe でドキュメントを生成します。
-
ホストスコープのパッチ — すでにレンダリングされた別のエンティティの構造に手を入れる必要がある場合。 典型的な例は、利用側の component のワークロード、つまり Feature 自身が作成していないドキュメントに、環境変数、ボリュームマウント、サイドカーコンテナを注入することです。テンプレート化された FeatureRecipe にはこれができません。自身のドキュメントを生成するだけで、他者のドキュメントは編集しないからです。パイプラインステップはレンダリング済みのセットに対して動作し、ホスト component のドキュメントをキーで指定できるため、これが可能です。
-
内容に依存する出力またはパッチ — 出力が レンダリング済みのセットに何が含まれているか に依存する場合。 出力するリソースや適用するパッチが、ビルドが生成した内容の関数である場合、たとえば Deployment が宣言した実際のポート、manifest に最終的に含まれたコンテナ名、chart が展開したリソースなどに依存する場合、その判断にはレンダリング済みの内容が必要です。テンプレート化された FeatureRecipe は Feature 自身の値からレンダリングし、完成したセットを見ることがないため、内容に依存する選択はできません。パイプラインステップはまず内容を読み取り、それから処理を行います。
どちらのトリガーにも共通する形があります。いずれもレンダリングの 後 にしか存在しない情報、つまり別のエンティティの構造か、出力された内容そのものを必要とします。ローカルな生成ではそうした情報は決して必要ないため、ローカルな生成にパイプラインステップが必要になることはありません。
ステップは変換し、ポリシーは検証する
パイプラインステップは トランスフォーマー であり、レンダリング済みのセットを変更します。結果が許容できるかどうかを確認する場所ではありません。ビルドを 検証 する、つまりパッチ適用後のワークロードにサイドカーがあること、平文のシークレットが出力に含まれていないこと、必須のラベルが存在することを確認するには、レンダリング段階のポリシー を付与します。これは render-verdict ロールのガバナンスプラグインで、レンダリング後に出力されたアーティファクトに対して実行され、判定を返します。halt の判定はビルドを停止し、warn または info の判定はブロックせずに助言します。
この 2 つは分けておきます。パイプラインステップに検証ロジックを組み込まないでください。また、出力を変更するためにポリシーを使わないでください。判定ロールに付与されたガバナンスプラグインは判定を返すだけでパッチは適用せず、ホストは判定ロールの出力を判断としてのみ読み取ります。ステップは出力を形作り、render-verdict ポリシーはそれを評価します。ガバナンスソケットのページでは、4 つのガバナンスロールすべてと判定の重大度を説明しています。
ステップの合成
パイプラインステップは型付きの入出力コントラクトを宣言できるため、with: の入力と返される出力は自由形式のデータではなく、検証済みの形になります。ステップは名前付きの outputs も返し、同じパイプライン内で後に宣言されたステップは、前のステップの出力を自身の with: テンプレートから .steps.<id>.outputs.<key> として読み取ります。これにより、2 部構成のパターンを結合なしに合成できます。Fetcher ステップが認証情報リソースを出力し、生成された Secret の名前を出力として公開します。Injector ステップがその名前を読み取り、利用側のワークロードにパッチを適用してそれをマウントします。各ステップは 1 つの関心事を担い、パイプラインは宣言された順序でそれらの出力を受け渡します。
相互参照
entities/featurerecipe.md—pipeline:を含む FeatureRecipe の記述面。plugins/plugin-contract.md— パイプラインステップのワイヤ形式:入力としてのキー付きドキュメントセット、出力としての RFC 6902 パッチ、副作用、診断、ステップ出力。plugins/policy-socket.md— ビルドの出力を検証するレンダリング段階の判定ロールを含む、ガバナンスソケット。templates/template-context-contract.md— 後のステップが読み取る.steps.<id>.outputsフィールド。examples/04-secrets.md— Fetcher + Injector のパイプライン形状。