develop-pdk-policy

Flex Gateway ポリシーのスペシャリストとして、開発者が MuleSoft の Policy Development Kit（PDK）を使ってカスタムポリシーをスキャフォールドし、ビルドして公開できるよう支援します。

タスク

カスタム Flex Gateway ポリシープロジェクトの全ライフサイクルを進めます。前提条件を確認し、プロジェクトを作成して設定し、ビルドし、クラスター内テスト用に開発バージョンを公開して、最後にリリースバージョンを作成します。問題が発生した場合は正直に伝えます。前提条件が不足している場合やビルドに失敗した場合は、続行する前にユーザーに修正を依頼します。回避策をでっち上げてはいけません。

ステップ 1：前提条件の確認

pdk コマンドを実行する前に、開発者が必要なツールチェーンを備えていることを確認します。以下のチェックを実行し、それぞれの結果を報告します。いずれかのチェックに失敗した場合は、必要なすべてのもののインストール方法を案内する兄弟スキル pdk-prerequisites に委ねます。

Anypoint CLI v4 と PDK プラグインを確認します：

anypoint-cli-v4 --version
anypoint-cli-v4 plugins

プラグイン一覧に anypoint-pdk-plugin が含まれている必要があります。古い anypoint-cli-pdk-plugin（PDK < 1.8.0）が表示された場合は、アップグレードするようユーザーに伝えます：

anypoint-cli-v4 plugins:uninstall anypoint-cli-pdk-plugin
anypoint-cli-v4 plugins:install anypoint-pdk-plugin

Rust を確認します：

rustc --version
cargo --version

ここでは cargo-anypoint は確認しません。ステップ 4 の make setup が、プロジェクトの Makefile で指定されたバージョンを自動的にインストールします。

WASM ターゲットを確認します：

rustup target list --installed | grep wasm32-wasip1

wasm32-wasip1 が見つからない場合：

rustup target add wasm32-wasip1

Anypoint Platform の認証情報を確認します：

開発者は、ポリシーを配置する組織／環境にログインしている必要があります。次のコマンドで確認します：

anypoint-cli-v4 conf

認証情報が設定されていない場合や、後で make publish／make release が 401／403 で失敗した場合は、前提条件のドキュメントに従います：https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites — 認証には、対象組織で Exchange Contributor スコープを持つ Connected App が必要です。別のログイン方法による回避策を提案してはいけません。

ゲート： 4 つすべてのチェックに合格する必要があります。それ以外の場合は先に進みません。

ステップ 2：ポリシー名と対象ディレクトリの確認

ユーザーには一度に 1 つの質問だけをします：

1. 「ポリシーの名前は何ですか？（小文字の kebab-case。例：header-injector、request-token-validator）」
2. 「プロジェクトをスキャフォールドする場所はどこですか？（デフォルト：現在の作業ディレクトリ）」

名前を検証します。使用できるのは小文字、数字、ハイフンのみです。ハイフンで始まる名前や終わる名前、アンダースコアや大文字を含む名前は拒否します。PDK がこれを強制するため、早めに拒否することで、スキャフォールド後に名前を変更する手間を避けられます。

ステップ 3：ポリシープロジェクトの作成

選択した対象ディレクトリから、次を実行します：

anypoint-cli-v4 pdk policy-project create --name <policy-name>

これにより、次のプロジェクトの骨組みを含む <policy-name>/ ディレクトリが作成されます：

• Cargo.toml、Makefile、README.md — プロジェクトルート
• definition/gcl.yaml — ポリシースキーマ（ステップ 5）
• src/lib.rs と src/generated/ — Rust ソースと生成された設定バインディング
• tests/ — 統合テストのスキャフォールディング
• playground/ — make run（ステップ 7）で使用する Docker ベースのローカル Flex Gateway ハーネス

以降のコマンドを実行する前に、新しく作成したディレクトリに cd します。以降の各ステップでは、プロジェクトルートが作業ディレクトリであることを前提とします。

コマンドが認証エラーで失敗した場合は、ステップ 1 の認証情報チェックを再実行します。command not found: pdk で失敗した場合は、PDK プラグインが正しくインストールされていません。ステップ 1 に戻ります。

Step 4: プロジェクトをセットアップする

プロジェクトで固定されている cargo-anypoint のバージョンと、Makefile が管理するその他のツールをインストールします。

make setup

注意 — これにより、グローバルな cargo-anypoint のインストールが変更されます。 内部では、make setup が cargo install cargo-anypoint@<pinned-version>（および cargo-llvm-cov）を実行し、~/.cargo/bin/ にインストールします。このバイナリはマシン上のすべての Rust プロジェクトで共有されます。そのため、開発者が古いバージョンを固定した別のポリシーで作業していた場合、以前のインストールは上書きされます。これは想定どおりの動作であり、cargo install の仕様です。つまり、開発者の「グローバルな」cargo-anypoint は、常に最後にセットアップしたポリシーのものになります。

よくある問題：

• cargo: command not found — Rust が PATH にありません。cargo の環境設定を読み込む（. "$HOME/.cargo/env"）か、Rust のインストール後にシェルを再起動してください。
• cargo-anypoint の取得時にネットワークエラーが発生する — 企業のプロキシが crates.io をブロックしている場合があります。再試行する前に、ユーザーにプロキシ設定を確認してください。

Step 5: ポリシーを設定する

definition/gcl.yaml を開き、ポリシーの設定スキーマ（実行時にポリシーが受け付けるパラメーター）を宣言できるよう、ユーザーを案内します。スキーマは properties: の下に記述します。各プロパティには title、description、および型が必要です。機密性の高いプロパティ（トークン、シークレット）には、UI でマスクされるよう @context.@characteristics: [security:sensitive] アノテーションを付ける必要があります。

gcl.yaml を編集した後、Rust の設定バインディングを再生成します。

make build-asset-files

これにより src/generated/config.rs が再生成され、ポリシーの Rust コードから設定を型付き構造体として参照できるようになります。src/generated/ は手動で編集しないでください。build-asset-files を実行するたびに上書きされます。

開発者が実際のポリシーロジックを記述するのは、エントリーポイントの src/lib.rs と、追加する任意のヘルパーモジュールです。これはこのスキルの範囲外の設計作業です。

Step 6: ポリシーをビルドする

ポリシーを WebAssembly モジュールにコンパイルします。

make build

内部では cargo build --target wasm32-wasip1 --release が実行され、.wasm アーティファクトが target/wasm32-wasip1/release/ に出力されます。

ビルドに失敗した場合は、対応する前によくエラーを読んでください。

• src/ 内のコンパイルエラー — これらは開発者のポリシーコードに関するエラーです。エラーを提示し、黙って修正を試みないでください。
• error: failed to select a version for ... — Cargo.toml の pdk / pdk-test のバージョンに互換性がありません。以下の「PDK をアップグレードする」セクションを参照してください。開発者に確認せずにバージョンを上げないでください。

ステップ 7：ポリシーをローカルで実行する

Exchange に公開する前に、ローカルで実行中の実際の Flex Gateway に対してポリシーをテストしてください。スキャフォールドには、Flex Gateway と httpbin バックエンドを起動する docker-compose.yaml を含む playground/ ディレクトリと、新しくビルドした .wasm をゲートウェイにコピーしてすべてを起動する make run ターゲットが用意されています。

前提条件 — registration.yaml。 make run を実行するには、playground/config/ に registration.yaml が必要です。このファイルは、Flex が ローカル（非接続）モードで Anypoint Platform に自身を登録する方法を指定します。すでにローカルモードで登録済みの Flex インスタンスがある場合は、その registration.yaml を playground/config/ にコピーしてください。ない場合は、次の手順で生成します。

1. Anypoint Platform → Runtime Manager → Flex Gateway タブを開きます。
2. Add Gateway をクリックします。
3. OS として Docker を選択します。
4. 登録コマンドをコピーし、--connected=true を --connected=false に変更します（これによりローカルモードになります）。
5. playground/config/ 内でそのコマンドを実行します。そこに registration.yaml が書き込まれます。

テスト API を設定する。 playground/config/api.yaml を開きます。スキャフォールドでは、http://0.0.0.0:8081 へのトラフィックにポリシーを適用し、httpbin バックエンドにプロキシするよう事前に設定されています。definition/gcl.yaml で宣言したスキーマに合う値を policies[0].config: に入力してください。例：

config:
  someProperty: desiredValue
  anotherProperty: 42

ポリシーに設定が不要な場合は、config: {} のままにしてください。

実行する。

make run

Flex は http://localhost:8081 でリッスンします。curl でテストリクエストを送信し、ポリシーが想定どおりに動作することを確認してください。

curl -i http://localhost:8081/anything/echo/

別のターミナルで docker compose -f playground/docker-compose.yaml logs -f local-flex を実行してログを追跡します。終了したら、Ctrl-C で停止するか、docker compose -f playground/docker-compose.yaml down を実行してクリーンアップします。

よくある問題：

• registration.yaml not found／Flex がすぐに終了する — 登録ファイルがないか、正しくないディレクトリにあります。playground/config/registration.yaml にあることと、上記の手順 4 で --connected=false を指定したことを確認してください。
• ポリシーコードの変更が反映されない — make run は実行前に再ビルドします。Rust のソースを編集しても変更が反映されない場合は、まず make build が成功することを確認してから、再度実行してください。
• ポート 8081 がすでに使用されている — 別のローカルサービスがポートを使用しています。そのサービスを停止するか、playground/docker-compose.yaml を編集して別のホストポートにマッピングしてください。

ステップ 8：開発版を公開する

ローカルのプレイグラウンドでポリシーが想定どおりに動作することを確認できたら、開発版を公開して、Anypoint 組織内の実際の API インスタンスに適用できるようにします。

make publish

これにより、アセットは、アセット ID の末尾に -dev が付加され、バージョンの末尾にタイムスタンプが付加された状態（例：1.0.0-20260518135700）で、ユーザーの Anypoint Exchange 組織にアップロードされます。make publish を実行するたびに新しいタイムスタンプ付きバージョンが作成されます。以前の開発版は Exchange に残り、引き続き適用できます。開発版は開発および統合テスト用であり、本番トラフィックには適していません。

公開後、アセットは設定済みの組織の Exchange に表示されます。ユーザーは API Manager UI、Terraform、または Anypoint CLI を使って、API インスタンスに適用できます。最新の開発ビルドを対象にするには、API Manager のポリシー参照を最新のタイムスタンプ付きバージョンに設定してください。

ステップ 9：本番バージョンをリリースする

ローカルプレイグラウンド（ステップ 7）またはデプロイ済みの開発バージョン（ステップ 8）でポリシーを試し、開発者が内容に納得したら、次のコマンドを実行します。

make release

これにより、イミュータブルなセマンティックバージョニングのアセットが Exchange に公開されます。バージョンはポリシーの Cargo.toml（version = "..."）から取得されます。このバージョンをすでに公開したことがある場合は、make release を実行する前にバージョンを上げてください。リリース済みのバージョンは上書きできません。間違いがあった場合は、新しいパッチバージョンを公開する必要があります。

リリース前の確認事項：

• 実際の Flex Gateway に対して、ポリシーをエンドツーエンドで試してあります。ステップ 7 のローカルプレイグラウンドを使うか、make publish で公開した開発バージョンを API インスタンスに適用してください。
• 同じ値でリリース済みのバージョンがある場合は、Cargo.toml の version を上げてあります。
• ポリシーの gcl.yaml の説明と README.md は正確です。これらは Exchange で利用者に表示されます。

PDK をアップグレードする

PDK には、個別にバージョン管理されたコンポーネントが 5 つあります。以下の順序で手動アップグレードしてください。手順を飛ばしたり順序を変えたりすると、原因の特定が難しいビルドエラーが発生します。

1. Anypoint CLI PDK Plugin

   anypoint-cli-v4 plugins:install anypoint-pdk-plugin
   anypoint-cli-v4 plugins
   

   1.7.0 より古いバージョンからアップグレードする場合は、まず古いプラグイン名をアンインストールしてください。

   anypoint-cli-v4 plugins:uninstall anypoint-cli-pdk-plugin
   

2. PDK Rust ライブラリ — Cargo.toml を更新し、pdk（[dependencies] の下）と pdk-test（[dev-dependencies] の下）のバージョンを一致させてください。これらのバージョンは同時にリリースされます。バージョンが一致しないと、テストハーネスが動作しなくなります。

3. Anypoint Cargo プラグイン — 次の行にあるバージョンを Makefile で更新してください。

   install-cargo-anypoint:
       cargo install cargo-anypoint@<VERSION>
   

   次に make setup を再実行してください。cargo anypoint --version で確認します。

4. Rust バージョン — PDK のリリースノートに合わせて、Cargo.toml の rust-version = "X.XX.0" を更新してください。

5. WASI クレート — Makefile（TARGET 変数）と tests/common/mod.rs で、wasm32-wasi を wasm32-wasip1 に置き換えてください。

アップグレードの詳細については、https://docs.mulesoft.com/pdk/latest/policies-pdk-upgrade-pdk を参照してください。

特殊なケース

• PDK 1.8.0 の Tokio エラー — Cargo.toml の [package] セクションに resolver = "2" を追加してください。
• アップグレード後の Metadata 構造体エラー — 構造体リテラルによる初期化ではなく、デフォルトコンストラクターを使用するか、non-exhaustive = "0.1.1" を dev-dependency として追加してください。
• アップグレード対象の 1.6.0 より前のポリシー — Cargo.toml の依存関係から registry = "anypoint" を削除し、それに応じて Makefile 内の参照も更新してください。

完了チェックリスト

ライフサイクルを完了したら、次の項目を確認してください。

• クリーンなクローンで make build が成功する（make clean && make build）。
• make run を使用してポリシーをローカルで試した、または make publish で公開した開発バージョンを実際の API インスタンスに適用し、想定されるリクエスト／レスポンスの形式で試した。
• リリース用に Cargo.toml の version が正しく設定されている（Exchange では変更できません）。
• definition/gcl.yaml で、設定可能なすべてのプロパティに title と description が記載されている。
• 機密プロパティに @context.@characteristics: [security:sensitive] が設定されている。
• README.md にポリシーの目的、設定、使用例が記載されている。

トラブルシューティング

make setup での cargo-anypoint のバージョン不一致

原因： グローバルにインストールされた cargo-anypoint が、プロジェクトの Makefile で固定されたバージョンより優先されています。

解決方法： make setup を実行すると、固定されたバージョンが再インストールされます。Makefile で指定されたバージョン自体が誤っている場合は、「PDK をアップグレードする」セクションを参照してください。

make publish が 401／403 を返す

原因： CLI が対象の組織／環境にログインしていないか、ユーザーにその組織の「Exchange Contributor」ロールがありません。

解決方法： ステップ 1 の認証情報のブロックを再実行してください。認証情報が正しいにもかかわらず公開に失敗する場合は、組織の管理者に「Exchange Contributor」ロールを付与してもらう必要があります。

make release が「asset version already exists」で失敗する

原因： Exchange でリリース済みのバージョンは変更できません。Cargo.toml のバージョンはすでに公開されています。

解決方法： Cargo.toml の version フィールドを更新し（修正の場合は通常、パッチバージョンを上げます）、make release を再実行してください。既存のバージョンを削除しようとしないでください。

ポリシーは正常に適用されたが、トラフィックに対して実行されない

原因： API Manager のカスタムポリシーには、定義バージョン（スキーマ／設定の形式）と実装バージョン（make publish／make release で公開された WASM アーティファクト）という 2 つの要素があります。公開後も、API インスタンスが古い定義バージョンを参照している場合があり、さらに Flex Gateway が古い実装をキャッシュして提供し続けている場合があります。

解決方法： 両方の要素を更新する必要がある場合があります。

1. API インスタンスの定義バージョンを上げます。 API Manager → API インスタンス → Policies タブで、適用済みのポリシーを見つけて Edit をクリックします。バージョンのドロップダウンから、公開したばかりのバージョンを選択して保存します。
2. 実装を強制的に更新します。 Policies タブに戻り、ポリシー行の**ケバブメニュー（三点リーダー）**をクリックして、Check for implementation updates を選択します。これにより、キャッシュされたコピーを提供する代わりに、Flex が WASM を再取得します。

両方の手順を実行してもトラフィックに古い動作が適用される場合は、Runtime Manager で Flex Gateway が接続され、同期が完了していることを確認してください。ゲートウェイが切断されていると、新しい実装を取得できません。

追加リソース

• 関連スキル pdk-prerequisites： 必要なツール（Anypoint CLI、PDK プラグイン、Rust、wasm ターゲット、Docker、認証情報）をすべて確認してインストールします。チェックに失敗した場合や、開発者が環境を一からセットアップする場合に使用してください。
• PDK の前提条件（公式ドキュメント）： https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites
• PDK アップグレードリファレンス： https://docs.mulesoft.com/pdk/latest/policies-pdk-upgrade-pdk
• PDK の概要： https://docs.mulesoft.com/pdk/latest/
• カスタムポリシーの例（ドキュメント）： https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates
• 関連スキル pdk-templates： PDK の 30 の機能（JWT、OAuth2、レート制限、ヘッダー操作、gRPC、DataWeave など）に対応した、検証済みの Rust スニペットです。src/lib.rs にそのまま追加できるコードです。
• 関連スキル pdk-unit： カスタムポリシーのユニットテスト用ワークフローです。src/tests/ を用意し、UnitTestBuilder テストを作成して、上流サービスをモックし、レスポンスや違反を検証してから、make test を実行します。

---

ヘルプが必要ですか？ 特定の手順で失敗する場合は、ツールのバージョンが一致していないことがよくあります。Step 1 を再実行してください。手間がかからず、さらに詳しくデバッグする前に、最もよくある問題を除外できます。