Debugging Custom Policies with the PDK Debugging Playground

To test the functionality of your policy, Omni Gateway Policy Development Kit (PDK) provides a pre-configured API instance located in the <root-directory>/playground/config directory.

The PDK Debugging Playground only supports Omni Gateway running in Local Mode in a Docker container. If you plan to deploy or policy to Omni Gateway running in Connected Mode or to a different platform, you should still first test your policy in PDK by using Omni Gateway running in Local Mode in a Docker container.

You can run Omni Gateway in Local Mode on Docker in Windows only to develop and test your policies. However, Omni Gateway does not support Windows in production environments.

To test your policy, complete the following tasks:

Before You Begin
Register an Omni Gateway Instance in Local Mode
Configure the Policy
Add Additional Policies if necessary
Deploy the Policy with PDK

Before You Begin

Ensure that you have:

Register an Omni Gateway Instance in Local Mode

To begin using the make run command to debug your custom policy, register an Omni Gateway in Local Mode.

For the run command to work, an Omni Gateway registration.yaml file must exist in the <root-directory>/playground/config directory. Create this file by running the registration command in the directory, or move a registration.yaml file of a previously registered Omni Gateway to the directory.

A registration file is generated automatically when you run the debugging playground if no registration.yaml file is provided.

The make run command only supports Omni Gateways running in Local Mode in a Docker Container. To register Omni Gateway, see:

Run only the registration command. Do not run the Docker start command because the make run command completes this step.

Create a different registration file on each device testing the policy.

The registration file is ignored for storage in remote repositories and is listed in the .gitignore file located at the root of the project directory.

Configure the Policy

Depending on the configurations listed in the definition/gcl.yaml file you configured in Defining a Policy Schema Definition, you may have to configure some parameters before running the policy locally.

For example, if the gcl.yaml file is as follows:

apiVersion: gateway.mulesoft.com.v1alpha1
kind: Extension
metadata:
  labels:
    title: my-custom-policy
    category: Security
spec:
  extends:
    - name: extension-definition
  properties:
    user:
      type: string
      default: user1
    password:
      type: string
    description:
      type: string
  required:
    - user
    - password

Update the /playground/config/api.yaml file with your configuration value:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8081
  services:
    upstream:
      address: http://backend
      routes:
        - config:
            destinationPath: /anything/echo/
  policies:
    - policyRef:
        name: my-custom-policy
      config:
        password: 12345678

In this example, the user is set to the default value user1, the password is set to 12345678, and no description is provided.

Add Additional Policies

You can also apply additional policies to the test API instance to test your custom policies behavior alongside other policies.

However, your custom policy under development must be the first policy specified, for example:

  policies:
    - policyRef:
        name: my-custom-policy
      config:
        password: 12345678
    - policyRef:
        name: additional-policy
      config:

Deploy the Policy with PDK

After you complete the previous steps, run the make run command from the policy’s root directory to deploy policy:

make run

This command starts the two Docker containers in the <root-directory>/playground/docker-compose.yaml file:

Local-flex: The Omni Gateway instance Docker container that executes the custom policy. This Omni Gateway listens for requests made to localhost:8081.
Backend: The Docker Container that runs the backend service for the Omni Gateway instance. This backend service echoes any request it receives.

To stop the Docker containers, press Cmd+c or Ctrl+c depending on your device from the terminal running the containers.

Once the containers are running, you can make requests to the API instance, for example:

curl --location --request POST 'http://0.0.0.0:8081/some/route' \
--header 'Token: mytoken'

The backend service returns an echo response including the requests’s route, body, and headers sent with any modification performed by the custom policy or additional policies. Any logs included in the custom policy’s source code are visible in the terminal running the containers.

Configure the Loglevel

By default, PDK’s debugging environment enables logs with the debug loglevel configured.

To change the loglevel, edit the logging.runtimeLogs.logLevel value in <root-directory>/playground/config/logging.yaml.

To learn more about editing an Omni Gateway’s logging configuration file, see Configuring External Logs for Omni Gateway in Local Mode.

Use the Rust Debugger

Visual Studio Code (VS Code) includes a Rust debugger that can run unit tests. You cannot use the VS Code Debugger while the policy is deployed on an Omni Gateway. To create the API mocking, you must use unit tests for the specific logic you need to debug.

To debug Rust code in VS Code, you must install the CodeLLDB Debugger Extension or a different VS Code extension with the same functionality. To learn more about debugging Rust in VS Code, see Rust in Visual Studio Code.