Contact Us 1-800-596-4880
  1. Homepage
  2. Omni Gateway Policy Development Kit (PDK) (1.10)

  3. Upgrading PDK (1.10)

Upgrading PDK

To update a custom policy project, you must update each of these separately versioned Omni Gateway Policy Development Kit (PDK) components:

  • Anypoint CLI PDK plugin

  • PDK Rust libraries

  • Anypoint Cargo plugin

  • Policy Rust Version

  • WASI Crate

When you upgrade your Anypoint CLI PDK plugin, you must manually upgrade the PDK Rust libraries and Anypoint Cargo plugin to be compatible with the new plugin version. All the PDK custom policies on your device use the same Anypoint CLI PDK plugin. When you create a new custom policy project, the PDK Rust libraries and Anypoint Cargo plugin versions are the same as the Anypoint CLI PDK plugin used to create the project and are independent from other policy projects.

To upgrade a custom policy project created with an earlier version of the Anypoint CLI PDK plugin:

  1. Upgrade the Anypoint CLI PDK Plugin

  2. Upgrade the PDK Rust Libraries

  3. Upgrade the Anypoint Cargo Plugin

  4. Upgrade a Policy’s Rust Version

  5. Upgrade a Policy’s WASI Crate

Upgrade the Anypoint CLI PDK Plugin

When editing a custom policy created with an earlier plugin version, ensure your PDK Rust libraries and Anypoint Cargo plugin match your Anypoint CLI PDK plugin version.

To upgrade your Anypoint CLI PDK plugin to the latest version, execute the following command:

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

+ NOTE: In PDK 1.7.0, the name of the Anypoint CLI PDK plugin changes from anypoint-cli-pdk-plugin to anypoint-pdk-plugin. To install the new plugin, see Upgrade the Anypoint CLI PDK Plugin for Policies with Versions Earlier Than 1.7.0.

To verify your current plugin version, execute the following command:

anypoint-cli-v4 plugins

For example, the following PDK plugin version is 1.7.0:

anypoint-pdk-plugin 1.7.0
├─ anypoint-cli-command 1.5.2
│  └─ @oclif/plugin-help 5.1.12
└─ @oclif/plugin-version 1.0.4

Upgrade the PDK Rust Libraries

The PDK Rust library is the Rust code library used by a specific custom policy. Different custom policies might use different PDK library versions.

To upgrade the PDK Rust code libraries, modify the pdk dependency and pdk-test dev-dependency versions in the cargo.toml file of the custom policy. The pdk and pdk-test versions must match and your Anypoint CLI PDK plugin must support the specified version.

In the following example, both dependency versions are 1.6.0. Modify it to your required version:

[dependencies]
pdk = { version = "1.6.0" }

[dev-dependencies]
pdk-test = { version = "1.6.0" }

Upgrade the Anypoint Cargo Plugin

The Anypoint Cargo plugin extends the functionality of Cargo for use with the PDK Rust Libraries.

To upgrade your Anypoint Cargo plugin:

  1. Open the Makefile of your custom policy.

  2. Find the install-cargo-anypoint target, for example:

    install-cargo-anypoint:
	cargo install cargo-anypoint@1.6.0

  3. Change the version after the @ character to the required version.

  4. Save the Makefile.

  5. Execute the make setup command:

    make setup
    Executing the make setup command for a certain policy installs that policy’s Anypoint Cargo plugin version.

  6. Execute the following command to verify the correct version is installed:

    cargo anypoint --version

Upgrade a Policy’s Rust Version

To upgrade your Policy’s Rust version:

  1. Ensure the Rust version is downloaded on your device.

    To update Rust, see Rust Requirements for Using PDK.

  2. Open the cargo.toml of your custom policy.

  3. Find your Rust version. For example:

    rust-version = "1.87.0"

  4. Update your Rust version. For example:

    rust-version = "1.88.0"

  5. Save the cargo.toml file.

Upgrade a Policy’s WASI Crate

To upgrade your Rust WebAssembly System Interface (WASI) Crate from wasm32-wasi to wasm32-wasip1:

  1. Open the Makefile of your custom policy.

  2. Find this line:

    TARGET                	:= wasm32-wasi

  3. Replace wasm32-wasi with wasm32-wasip1:

    TARGET                	:= wasm32-wasip1

  4. Save the Makefile.

  5. Open the tests/common/mod.rs of your custom policy.

  6. Find the this line:

    pub const POLICY_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/target/wasm32-wasi/release");

  7. Replace wasm32-wasi with wasm32-wasip1:

    pub const POLICY_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/target/wasm32-wasip1/release");

  8. Save the mod.rs file.

Upgrade the Anypoint CLI PDK Plugin for Policies with Versions Earlier Than 1.8.0

Depending on you configuration, when upgrading to 1.8.0 you might experience these issues:

Tokio Runtime Feature Compatibility Error

When using a Tokio runtime for testing, sometimes a compilation occurs similar to this error when building for WebAssembly:

error: Only features sync,macros,io-util,rt,time are supported on wasm.
   --> /Users/test-user/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/tokio-1.51.1/src/lib.rs:478:1
    |
478 | compile_error!("Only features sync,macros,io-util,rt,time are supported on wasm.");

To solve this error, under the [package] section of your policy’s Cargo.toml, add resolver = "2". This enables your compiler resolve dependencies separately for production code and for test dependencies.

[package]
name = "my_policy"
version = "1.0.0"
rust-version = "1.88.0"
edition = "2018"
resolver = "2"

Compilation Error When Constructing Metadata-Related Structs

When constructing Metadata-related structs, sometimes an error similar to this one occurs:

error[E0639]: cannot create non-exhaustive struct using struct expression
  --> test-policy/src/lib.rs:90:32
   |
90 |                   flex_metadata: FlexMetadata {
   |  ________________________________^
91 | |                     flex_name: "test_flex_name".to_string(),
92 | |                     flex_version: "1.0.0".to_string(),
93 | |                 },
   | |_________________^

PDK 1.8.0 marks metadata-related structs as #[non_exhaustive] so that you can add new metadata fields without breaking changes.

When constructing these structs manually in tests, use one of these approaches:

  • Use the new default constructor and set each field to the value you need. For example:

    let mut metadata = FlexMetadata::default();
metadata.flex_name = "test_flex_name".to_string();
metadata.flex_version = "1.0.0".to_string();

  • Add the non_exhaustive! macro from the non-exhaustive crate to the [dev-dependencies] in your cargo.toml files:

    [dev-dependencies]
non-exhaustive = "0.1.1"

    This enables you to use the default construct as shown in this example:

    use non_exhaustive::non_exhaustive;
// ...

let metadata = non_exhaustive!(FlexMetadata {
    flex_name: "test_flex_name".to_string(),
    flex_version: "1.0.0".to_string(),
});

Upgrade the Anypoint CLI PDK Plugin for Policies with Versions Earlier Than 1.7.0

In PDK 1.7.0, the name of the Anypoint CLI PDK plugin changes from anypoint-cli-pdk-plugin to anypoint-pdk-plugin. To upgrade your earlier versions, uninstall the old plugin before installing the new one:

  1. Uninstall the old plugin:

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

  2. Install the new plugin:

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

Upgrade Policies with Versions Earlier Than 1.6.0

In PDK 1.6.0, the PDK libraries moved from the Anypoint platform to crates.io. When upgrading from versions earlier than 1.6.0, you must update the dependencies to point to the new location. To upgrade policies with versions earlier than 1.6.0:

  1. Upgrade the Anypoint CLI PDK plugin.

  2. Upgrade the PDK Rust libraries.

  3. Upgrade the PDK Rust libraries:

    1. Locate the dependencies and dev-dependencies in your policy’s cargo.toml:

      [dependencies]
pdk = { version = "1.5.0", registry = "anypoint" }

[dev-dependencies]
pdk-test = { version = "1.5.0", registry = "anypoint" }

    2. Update the version and remove the registry = "anypoint":

      [dependencies]
pdk = { version = "1.6.0" }

[dev-dependencies]
pdk-test = { version = "1.6.0" }

    3. Save the cargo.toml file.

  4. Upgrade the Anypoint Cargo Plugin:

    1. Open the Makefile of your custom policy.

    2. Find the install-cargo-anypoint target, for example:

      install-cargo-anypoint:
	cargo install cargo-anypoint@1.5.0 --registry anypoint --config .cargo/config.toml

    3. Update the version and remove the --registry and --config flags:

      install-cargo-anypoint:
	cargo install cargo-anypoint@1.6.0

    4. Save the Makefile file.

  5. Remove the Anypoint Platform registry references from your setup command:

    1. Open the Makefile of your custom policy.

    2. Find the setup target, for example:

      .PHONY: setup
setup: registry-creds login install-cargo-anypoint ## Setup all required tools to build
	cargo fetch

    3. Remove the Anypoint Platform registry references:

      .PHONY: setup
setup: install-cargo-anypoint ## Setup all required tools to build
	cargo fetch

    4. Delete the login and registry-creds targets. For example:

      To find an example of the targets, see the login and registry-creds targets in the Certification Policy.

    5. Save the Makefile file.

  6. Execute make setup to install the updated versions.

See Also