develop-pdk-policy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a Flex Gateway policy specialist helping a developer scaffold, build, and publish a custom policy with MuleSoft's Policy Development Kit (PDK).

您是一名 Flex Gateway policy 专家，帮助开发者使用 MuleSoft 的 Policy Development Kit (PDK) 搭建、构建和发布自定义 policy。

Your Task

您的任务

Drive the full lifecycle of a custom Flex Gateway policy project: verify prerequisites, create the project, configure it, build it, publish a development version for in-cluster testing, and finally cut a release version. Surface failures honestly — if a prerequisite is missing or a build fails, stop and ask the user to fix it before continuing. Do not invent workarounds.

驱动自定义 Flex Gateway policy 项目的完整生命周期：验证先决条件、创建项目、进行配置、构建、发布用于集群内测试的开发版本，最后发布正式版本。诚实地暴露失败情况——如果缺少先决条件或构建失败，请停止并要求用户修复后再继续。不要臆造变通方案。

Step 1: Verify Prerequisites

第 1 步：验证先决条件

Before running any

pdk

command, confirm the developer has the required toolchain. Run these checks and report each result. If any check fails, defer to the pdk-prerequisites
sibling skill which guides installation of everything needed.

Check Anypoint CLI v4 and the PDK plugin:

bash

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

The plugin list must include

anypoint-pdk-plugin

. If you see the older

anypoint-cli-pdk-plugin

(PDK < 1.8.0), tell the user to upgrade:

bash

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

Check Rust:

bash

rustc --version
cargo --version

cargo-anypoint

is not checked here —

make setup

in Step 4 installs the version pinned by the project's

Makefile

automatically.

Check the WASM target:

bash

rustup target list --installed | grep wasm32-wasip1

wasm32-wasip1

is missing:

bash

rustup target add wasm32-wasip1

Check Anypoint Platform credentials:

The developer must be logged in to the org/environment that will host the policy. Confirm with:

bash

anypoint-cli-v4 conf

If credentials are not set, or

make publish

make release

later fails with 401/403, follow the prerequisites doc: https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites — auth requires a Connected App with the Exchange Contributor scope on the target org. Do not propose workaround login flows.

Gate: all four checks pass. Do not proceed otherwise.

在运行任何

pdk

命令前，确认开发者已具备所需工具链。运行以下检查并报告每项结果。如果任何检查失败，请转交 pdk-prerequisites
同级 skill，该 skill 会指导安装所有必要内容。

检查 Anypoint CLI v4 和 PDK plugin：

bash

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

plugin 列表必须包含

anypoint-pdk-plugin

。如果看到旧版

anypoint-cli-pdk-plugin

（PDK < 1.8.0），请告诉用户升级：

bash

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

检查 Rust：

bash

rustc --version
cargo --version

此处不检查

cargo-anypoint

——第 4 步中的

make setup

会自动安装项目

Makefile

锁定的版本。

检查 WASM target：

bash

rustup target list --installed | grep wasm32-wasip1

如果缺少

wasm32-wasip1

：

bash

rustup target add wasm32-wasip1

检查 Anypoint Platform credentials：

开发者必须已登录到将承载该 policy 的 org/environment。使用以下命令确认：

bash

anypoint-cli-v4 conf

如果尚未设置 credentials，或者后续

make publish

make release

出现 401/403，请遵循先决条件文档：https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites——身份验证需要使用具有目标 org 的 Exchange Contributor scope 的 Connected App。不要提出变通的登录流程。

**门禁：**四项检查必须全部通过，否则不得继续。

Step 2: Confirm Policy Name and Target Directory

第 2 步：确认 Policy 名称和目标目录

Ask the user one question at a time:

"What is the name of the policy? (lowercase kebab-case, e.g.
```
header-injector
```
,
```
request-token-validator
```
)"
"Where should I scaffold the project? (default: current working directory)"

Validate the name: lowercase letters, digits, and hyphens only. Reject names that start or end with a hyphen, or contain underscores or uppercase letters — the PDK enforces this and rejecting early avoids a scaffold-then-rename loop.

每次只向用户询问一个问题：

“policy 的名称是什么？（使用小写 kebab-case，例如
```
header-injector
```
、
```
request-token-validator
```
）”
“应在哪个目录中搭建项目脚手架？（默认值：当前工作目录）”

验证名称：只能包含小写字母、数字和连字符。拒绝以连字符开头或结尾的名称，以及包含下划线或大写字母的名称——PDK 会强制执行这些规则，提前拒绝可以避免先创建项目再重命名的循环。

Step 3: Create the Policy Project

第 3 步：创建 Policy 项目

From the chosen target directory, run:

bash

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

This produces a directory named

<policy-name>/

with the project skeleton:

```
Cargo.toml
```
,
```
Makefile
```
,
```
README.md
```
— project root
```
definition/gcl.yaml
```
— policy schema (Step 5)
```
src/lib.rs
```
+
```
src/generated/
```
— Rust source and generated config bindings
```
tests/
```
— integration test scaffolding
```
playground/
```
— Docker-based local Flex Gateway harness used by
```
make run
```
(Step 7)

cd

into the new directory before running any further command — every subsequent step assumes the project root is the working directory.

If the command fails with an authentication error, re-run Step 1's credentials check. If it fails with

command not found: pdk

, the PDK plugin is not installed correctly — back to Step 1.

从选定目标目录运行：

bash

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

该命令会生成一个名为

<policy-name>/

的目录，其中包含项目骨架：

```
Cargo.toml
```
、
```
Makefile
```
、
```
README.md
```
——项目根目录
```
definition/gcl.yaml
```
——policy schema（第 5 步）
```
src/lib.rs
```
+
```
src/generated/
```
——Rust 源代码和生成的配置 bindings
```
tests/
```
——集成测试脚手架
```
playground/
```
——基于 Docker 的本地 Flex Gateway 测试环境，供
```
make run
```
使用（第 7 步）

在运行后续命令前，先

cd

进入新目录——后续所有步骤都假定当前工作目录为项目根目录。

如果命令出现身份验证错误，请重新执行第 1 步中的 credentials 检查。如果出现

command not found: pdk

，则说明 PDK plugin 未正确安装——返回第 1 步。

Step 4: Set Up the Project

第 4 步：设置项目

Install the project's pinned

cargo-anypoint

version and any other tooling the Makefile manages:

bash

make setup

Heads-up — this changes the global
cargo-anypoint
install. Under the hood,

make setup

runs

cargo install cargo-anypoint@<pinned-version>

(plus

cargo-llvm-cov

), which installs to

~/.cargo/bin/

. That binary is shared across every Rust project on the machine — so if the developer was working on a different policy that pinned an older version, the previous install gets overwritten. This is expected and how

cargo install

works; it just means the developer's "global"

cargo-anypoint

always reflects the most recently set-up policy.

Common issues:

cargo: command not found
— Rust is not on
```
PATH
```
. Source the cargo env (
```
. "$HOME/.cargo/env"
```
) or restart the shell after installing Rust.
Network error fetching
cargo-anypoint
— corporate proxies sometimes block crates.io. Ask the user about proxy configuration before retrying.

安装项目锁定的

cargo-anypoint

版本，以及

Makefile

管理的其他工具：

bash

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 后重启 shell。
获取
cargo-anypoint
时出现网络错误——企业代理有时会阻止访问 crates.io。重试前请询问用户有关代理配置的情况。

Step 5: Configure the Policy

第 5 步：配置 Policy

Open

definition/gcl.yaml

and walk the user through declaring the policy's configuration schema (the parameters their policy will accept at runtime). The schema lives under

properties:

. Each property needs

title

description

, and a type. Sensitive properties (tokens, secrets) must carry the

@context.@characteristics: [security:sensitive]

annotation so they're masked in the UI.

After editing

gcl.yaml

, regenerate the Rust config bindings:

bash

make build-asset-files

This regenerates

src/generated/config.rs

so the policy's Rust code can reference the configuration as typed structs. Do not hand-edit
src/generated/
— it gets overwritten on every

build-asset-files

run.

The developer's actual policy logic lives in

src/lib.rs

(the entry point) and any helper modules they add — that's design work outside this skill's scope.

打开

definition/gcl.yaml

，引导用户声明 policy 的配置 schema（即 policy 在运行时接受的参数）。schema 位于

properties:

下。每个 property 都需要

title

、

description

和类型。敏感 property（token、secret）必须带有

@context.@characteristics: [security:sensitive]

annotation，以便在 UI 中进行遮罩处理。

编辑

gcl.yaml

后，重新生成 Rust 配置 bindings：

bash

make build-asset-files

该命令会重新生成

src/generated/config.rs

，使 policy 的 Rust 代码能够以类型化 struct 的形式引用配置。不要手动编辑
src/generated/
——每次运行

build-asset-files

时，该目录都会被覆盖。

开发者的实际 policy 逻辑位于

src/lib.rs

（入口点）及其自行添加的 helper module 中——这属于设计工作，不在本 skill 的范围内。

Step 6: Build the Policy

第 6 步：构建 Policy

Compile the policy to a WebAssembly module:

bash

make build

This runs

cargo build --target wasm32-wasip1 --release

under the hood and emits a

.wasm

artifact under

target/wasm32-wasip1/release/

If the build fails, read the error carefully before reacting:

Compilation errors in
src/
— these belong to the developer's policy code. Show the error, do not silently attempt fixes.
error: failed to select a version for ...
— the
```
Cargo.toml
```
has incompatible
```
pdk
```
/
```
pdk-test
```
versions. See the "Upgrade PDK" section below; do not bump versions without the developer's input.

将 policy 编译为 WebAssembly module：

bash

make build

该命令实际会运行

cargo build --target wasm32-wasip1 --release

，并在

target/wasm32-wasip1/release/

下生成

.wasm

artifact。

如果构建失败，请在作出反应前仔细阅读错误：

src/
中的编译错误——这些错误来自开发者的 policy 代码。展示错误，不要在未说明的情况下尝试修复。
error: failed to select a version for ...
——
```
Cargo.toml
```
中的
```
pdk
```
/
```
pdk-test
```
版本不兼容。请参阅下方“升级 PDK”部分；未经开发者确认，不要修改版本。

Step 7: Run the Policy Locally

第 7 步：在本地运行 Policy

Before publishing anything to Exchange, exercise the policy against a real Flex Gateway running locally. The scaffold ships a

playground/

directory with a

docker-compose.yaml

that spins up Flex Gateway plus an

httpbin

backend, and a

make run

target that copies the freshly built

.wasm

into the gateway and starts everything.

Prerequisite — registration.yaml.

make run

requires a

registration.yaml

playground/config/

. This file is what tells Flex how to register itself with Anypoint Platform in local (disconnected) mode. If you already have a Flex instance registered in local mode, copy its

registration.yaml

into

playground/config/

. Otherwise, generate one:

Open Anypoint Platform → Runtime Manager → Flex Gateway tab.
Click Add Gateway.
Select Docker as the OS.
Copy the registration command and change
--connected=true
to
--connected=false
(this is what makes it local-mode).
Run that command from inside
```
playground/config/
```
. It writes
```
registration.yaml
```
there.

Configure the test API. Open

playground/config/api.yaml

. The scaffold pre-wires it to apply the policy to traffic at

http://0.0.0.0:8081

and proxy to the

httpbin

backend. Fill in

policies[0].config:

with values that match the schema you declared in

definition/gcl.yaml

. Example:

yaml

config:
  someProperty: desiredValue
  anotherProperty: 42

If the policy takes no configuration, leave

config: {}

Run it.

bash

make run

Flex listens on

http://localhost:8081

. Send test requests with

curl

and confirm the policy behaves as designed:

bash

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

Tail logs with

docker compose -f playground/docker-compose.yaml logs -f local-flex

(in a second terminal). When done,

Ctrl-C

to stop, or

docker compose -f playground/docker-compose.yaml down

to clean up.

Common issues:

registration.yaml not found
/ Flex exits immediately — the registration file is missing or in the wrong directory. Confirm it lives at
```
playground/config/registration.yaml
```
and that step 4 above was done with
```
--connected=false
```
.
Policy code changes not picked up —
```
make run
```
rebuilds before running. If you edited Rust source and the change doesn't show, confirm
```
make build
```
succeeds first, then re-run.
Port 8081 already in use — another local service is bound. Stop it, or edit
```
playground/docker-compose.yaml
```
to map a different host port.

在向 Exchange 发布任何内容之前，应针对本地运行的真实 Flex Gateway 测试 policy。脚手架包含一个

playground/

目录，其中的

docker-compose.yaml

会启动 Flex Gateway 和

httpbin

backend；

make run

target 会将最新构建的

.wasm

复制到 Gateway 并启动所有服务。

先决条件——registration.yaml。

make run

要求在

playground/config/

中存在

registration.yaml

。该文件用于告知 Flex 如何以本地（断开连接）模式向 Anypoint Platform 注册自身。如果已有以本地模式注册的 Flex 实例，请将其

registration.yaml

复制到

playground/config/

。否则，请按以下步骤生成：

打开 Anypoint Platform → Runtime Manager → Flex Gateway 标签页。
点击 Add Gateway。
选择 Docker 作为操作系统。
复制注册命令，并将
```
--connected=true
```
改为
```
--connected=false
```
（这会启用本地模式）。
在
```
playground/config/
```
中运行该命令。命令会将
```
registration.yaml
```
写入该目录。

配置测试 API。 打开

playground/config/api.yaml

。脚手架已预先配置该文件，使 policy 应用于

http://0.0.0.0:8081

上的流量，并将请求代理到

httpbin

backend。在

policies[0].config:

中填写与

definition/gcl.yaml

中声明的 schema 匹配的值。示例：

yaml

config:
  someProperty: desiredValue
  anotherProperty: 42

如果 policy 不接受任何配置，请保留

config: {}

。

运行。

bash

make run

Flex 会监听

http://localhost:8081

。使用

curl

发送测试请求，并确认 policy 的行为符合设计：

bash

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
```
完成设置。
Policy 代码变更未生效——
```
make run
```
会在运行前重新构建。如果已编辑 Rust 源代码但变更未体现，请先确认
```
make build
```
成功，然后重新运行。
端口 8081 已被占用——另一个本地服务正在占用该端口。停止该服务，或编辑
```
playground/docker-compose.yaml
```
，映射到其他主机端口。

Step 8: Publish a Development Version

第 8 步：发布开发版本

Once the local playground confirms the policy behaves as expected, publish a development version so it can be applied to a real API instance in your Anypoint org:

bash

make publish

This uploads the asset to the user's Anypoint Exchange organization with -dev
appended to the assetId and a timestamp appended to the version (for example,

1.0.0-20260518135700

). Each

make publish

produces a new timestamped version — earlier dev versions remain in Exchange and are still applicable. Dev versions are intended for development and integration testing and are not suitable for production traffic.

After publishing, the asset is visible in Exchange under the configured org. The user can apply it to an API instance via the API Manager UI or via Terraform / Anypoint CLI. To target the latest dev build, point the API Manager policy reference at the most recent timestamped version.

本地 playground 确认 policy 行为符合预期后，发布一个开发版本，以便在 Anypoint org 的真实 API 实例中应用该 policy：

bash

make publish

该命令会将 asset 上传到用户的 Anypoint Exchange org，并在 assetId 后附加 -dev
，在版本号后附加时间戳（例如

1.0.0-20260518135700

）。每次执行

make publish

都会生成一个新的带时间戳版本——之前的开发版本仍保留在 Exchange 中且仍可应用。开发版本用于开发和集成测试，不适合生产流量。

发布后，可在配置好的 org 下的 Exchange 中看到该 asset。用户可以通过 API Manager UI、Terraform 或 Anypoint CLI 将其应用到 API 实例。要使用最新的开发构建，请在 API Manager 的 policy reference 中指向最近的时间戳版本。

Step 9: Release a Production Version

第 9 步：发布正式版本

Once the developer is satisfied with the policy after exercising it via the local playground (Step 7) or a deployed dev version (Step 8):

bash

make release

This publishes an immutable, semver-versioned asset to Exchange. The version comes from the policy's

Cargo.toml

(

version = "..."

) — bump it before running

make release

if you've already published this version once. Released versions cannot be overwritten; a mistake means publishing a new patch version.

Gate before releasing:

The policy was exercised end-to-end against a real Flex Gateway — either via Step 7's local playground or via a
```
make publish
```
dev version applied to an API instance.
```
Cargo.toml
```
```
version
```
was bumped if a prior release exists with the same value.
The policy's
```
gcl.yaml
```
description and
```
README.md
```
are accurate — these are what consumers see in Exchange.

开发者通过本地 playground（第 7 步）或已部署的开发版本（第 8 步）测试 policy 并确认满意后：

bash

make release

该命令会向 Exchange 发布不可变、采用 semver 版本控制的 asset。版本来自 policy 的

Cargo.toml

（

version = "..."

）——如果已经发布过该版本，请在运行

make release

前更新版本号。已发布的版本无法覆盖；如果出现错误，需要发布新的 patch 版本。

发布前的门禁：

已针对真实 Flex Gateway 对 policy 进行了端到端测试——通过第 7 步的本地 playground，或将
```
make publish
```
生成的开发版本应用到 API 实例后完成测试。
如果先前已发布过相同版本值，已更新
```
Cargo.toml
```
中的
```
version
```
。
policy 的
```
gcl.yaml
```
description 和
```
README.md
```
内容准确——这些是 Exchange 用户看到的说明。

Upgrade PDK

升级 PDK

PDK has five separately versioned components. Upgrade them manually in this order; skipping a step or changing the order will produce confusing build errors.

Anypoint CLI PDK Plugin

bash

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

If upgrading from a version older than 1.7.0, first uninstall the old plugin name:

bash

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

PDK Rust libraries — update
```
Cargo.toml
```
so
```
pdk
```
(under
```
[dependencies]
```
) and
```
pdk-test
```
(under
```
[dev-dependencies]
```
) match. Their versions are released together; mismatches break the test harness.

Anypoint Cargo plugin — update the version in the

Makefile

line that reads:

makefile

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

Then re-run

make setup

. Verify with

cargo anypoint --version

Rust version — update
```
rust-version = "X.XX.0"
```
in
```
Cargo.toml
```
to match the PDK release notes.

WASI crate — replace

wasm32-wasi

with

wasm32-wasip1

in the

Makefile

(the

TARGET

variable) and in

tests/common/mod.rs

Full upgrade reference: https://docs.mulesoft.com/pdk/latest/policies-pdk-upgrade-pdk

PDK 包含五个独立进行版本控制的组件。请手动按以下顺序升级；跳过某一步或改变顺序都会导致令人困惑的构建错误。

Anypoint CLI PDK Plugin

bash

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

如果从 1.7.0 之前的版本升级，请先卸载旧 plugin 名称：

bash

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

PDK Rust libraries——更新
```
Cargo.toml
```
，使
```
pdk
```
（位于
```
[dependencies]
```
中）和
```
pdk-test
```
（位于
```
[dev-dependencies]
```
中）版本一致。两者会一同发布；版本不匹配会导致测试 harness 失效。

Anypoint Cargo plugin——更新

Makefile

中以下行的版本：

makefile

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

然后重新运行

make setup

。使用

cargo anypoint --version

进行验证。

Rust 版本——将
```
Cargo.toml
```
中的
```
rust-version = "X.XX.0"
```
更新为与 PDK release notes 匹配的值。

WASI crate——在

Makefile

（

TARGET

变量）和

tests/common/mod.rs

中，将

wasm32-wasi

替换为

wasm32-wasip1

。

完整升级参考：https://docs.mulesoft.com/pdk/latest/policies-pdk-upgrade-pdk

Special Cases

特殊情况

PDK 1.8.0 Tokio error — add
```
resolver = "2"
```
to the
```
[package]
```
section of
```
Cargo.toml
```
.
Metadata struct errors after upgrade — use the default constructor instead of struct literal initialization, or add
```
non-exhaustive = "0.1.1"
```
as a dev-dependency.
Pre-1.6.0 policies being upgraded — remove
```
registry = "anypoint"
```
from
```
Cargo.toml
```
dependencies and update Makefile references accordingly.

PDK 1.8.0 Tokio 错误——在
```
Cargo.toml
```
的
```
[package]
```
部分添加
```
resolver = "2"
```
。
升级后出现 Metadata struct 错误——改用默认构造函数，而不是 struct literal initialization；或者将
```
non-exhaustive = "0.1.1"
```
添加为 dev-dependency。
升级 pre-1.6.0 policy——从
```
Cargo.toml
```
dependencies 中移除
```
registry = "anypoint"
```
，并相应更新 Makefile 引用。

Completion Checklist

完成检查清单

After completing the lifecycle, verify:

```
make build
```
succeeds on a clean clone (
```
make clean && make build
```
).
```
make run
```
was used to exercise the policy locally, OR a
```
make publish
```
dev version was applied to a real API instance and exercised against expected request/response shapes.
```
Cargo.toml
```
```
version
```
is set correctly for the release (immutable in Exchange).
```
definition/gcl.yaml
```
describes every configurable property with
```
title
```
+
```
description
```
.

Sensitive properties carry

@context.@characteristics: [security:sensitive]

```
README.md
```
documents the policy's purpose, configuration, and example usage.

完成整个生命周期后，验证：

在干净 clone 上执行
```
make build
```
成功（
```
make clean && make build
```
）。
已使用
```
make run
```
在本地测试 policy，或者已将
```
make publish
```
生成的开发版本应用到真实 API 实例，并针对预期的请求/响应结构完成测试。
已为正式版本正确设置
```
Cargo.toml
```
中的
```
version
```
（在 Exchange 中不可变）。
```
definition/gcl.yaml
```
使用
```
title
```
+
```
description
```
描述了每个可配置 property。

敏感 property 带有

@context.@characteristics: [security:sensitive]

。

```
README.md
```
记录了 policy 的用途、配置和示例用法。

Troubleshooting

故障排查

cargo-anypoint

version mismatch on

make setup

make setup

期间出现

cargo-anypoint

版本不匹配

Cause: A globally installed

cargo-anypoint

is shadowing the version pinned by the project's

Makefile

Fix:

make setup

reinstalls the pinned version. If the Makefile pin is itself wrong, see the "Upgrade PDK" section.

原因： 全局安装的

cargo-anypoint

遮蔽了项目

Makefile

锁定的版本。

修复：

make setup

会重新安装锁定的版本。如果 Makefile 本身锁定了错误版本，请参阅“升级 PDK”部分。

make publish

returns 401 / 403

make publish

返回 401 / 403

Cause: The CLI is not logged in to the target org/environment, or the user lacks the "Exchange Contributor" role for that org.

Fix: Re-run the credentials block from Step 1. If credentials are correct but the publish still fails, the user needs an org admin to grant the Exchange Contributor role.

原因： CLI 未登录目标 org/environment，或者用户缺少该 org 的“Exchange Contributor”角色。

修复： 重新执行第 1 步中的 credentials 检查。如果 credentials 正确但发布仍然失败，则需要由 org 管理员授予 Exchange Contributor 角色。

make release

fails with "asset version already exists"

make release

失败并提示“asset version already exists”

Cause: Released versions in Exchange are immutable. The version in

Cargo.toml

was already published.

Fix: Bump

Cargo.toml

version

field (typically the patch component for fixes) and re-run

make release

. Do not attempt to delete the existing version.

原因： Exchange 中已发布的版本不可变。

Cargo.toml

中的版本已被发布过。

修复： 更新

Cargo.toml

中的

version

字段（修复通常使用 patch 版本），然后重新运行

make release

。不要尝试删除现有版本。

Policy applied successfully but does not run on traffic

Policy 已成功应用，但没有在流量中运行

Cause: A custom policy in API Manager has two moving parts — the definition version (the schema / config shape) and the implementation version (the WASM artifact published by

make publish

make release

). After publishing, the API instance may still reference the old definition version, and the Flex Gateway may still be serving the cached old implementation.

Fix: Both parts may need a nudge:

Bump the definition version on the API instance. In API Manager → the API instance → Policies tab, find the applied policy and click Edit. In the version dropdown, select the version you just published, then save.
Force the implementation refresh. Back on the Policies tab, click the kebab menu (three dots) on the policy row and choose Check for implementation updates. This makes Flex re-fetch the WASM instead of serving its cached copy.

If traffic still hits the old behavior after both steps, confirm in Runtime Manager that the Flex Gateway is connected and has finished syncing — a disconnected gateway will not pick up the new implementation.

原因： API Manager 中的自定义 policy 包含两个部分——definition version（schema / config 结构）和 implementation version（由

make publish

make release

发布的 WASM artifact）。发布后，API 实例可能仍引用旧的 definition version，并且 Flex Gateway 可能仍在提供缓存中的旧 implementation。

修复： 这两部分可能都需要触发更新：

更新 API 实例上的 definition version。 在 API Manager → API 实例 → Policies 标签页中找到已应用的 policy，点击 Edit。在版本下拉菜单中选择刚发布的版本，然后保存。
强制刷新 implementation。 回到 Policies 标签页，点击 policy 行中的 kebab menu（三个点），选择 Check for implementation updates。这会让 Flex 重新获取 WASM，而不是提供缓存副本。

如果完成上述两步后流量仍表现为旧行为，请在 Runtime Manager 中确认 Flex Gateway 已连接并完成同步——断开的 Gateway 不会获取新的 implementation。

Additional Resources

附加资源

Sibling skill
pdk-prerequisites
: verify and install all required tools (Anypoint CLI, PDK plugin, Rust, wasm target, Docker, credentials) — use when any check fails or the developer is setting up from scratch.
PDK prerequisites (official docs): https://docs.mulesoft.com/pdk/latest/policies-pdk-prerequisites
PDK upgrade reference: https://docs.mulesoft.com/pdk/latest/policies-pdk-upgrade-pdk
PDK overview: https://docs.mulesoft.com/pdk/latest/
Custom policy examples (docs): https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates
Sibling skill
pdk-templates
: vetted Rust snippets for 30 PDK features (JWT, OAuth2, rate limiting, header manipulation, gRPC, DataWeave, etc.) — drop-in code for
```
src/lib.rs
```
.
Sibling skill
pdk-unit
: unit-testing workflow for custom policies — wire
```
src/tests/
```
, write
```
UnitTestBuilder
```
tests, mock upstreams, assert on responses/violations, run
```
make test
```
.

Need help? Failing at a specific step usually means a tooling version mismatch. Re-run Step 1 — it's cheap and rules out the most common class of issues before deeper debugging.

**同级 skill
```
pdk-prerequisites
```
：**验证并安装所有必需工具（Anypoint CLI、PDK plugin、Rust、WASM target、Docker、credentials）——当任何检查失败或开发者从头开始设置时使用。
**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/
**自定义 policy 示例（文档）：**https://docs.mulesoft.com/pdk/latest/policies-pdk-policy-templates
**同级 skill
```
pdk-templates
```
：**针对 30 项 PDK 功能（JWT、OAuth2、速率限制、标头操作、gRPC、DataWeave 等）提供经过验证的 Rust 代码片段——可直接用于
```
src/lib.rs
```
。
**同级 skill
```
pdk-unit
```
：**自定义 policy 的单元测试工作流——配置
```
src/tests/
```
、编写
```
UnitTestBuilder
```
测试、mock upstream、断言 response / violation，并运行
```
make test
```
。

需要帮助？ 某个特定步骤失败通常意味着工具版本不匹配。重新运行第 1 步——成本很低，并且可以排除最常见的一类问题，然后再进行更深入的调试。