Configuring user-defined policies on the API Gateway in a Kubernetes deployment

For a Kubernetes deployment that uses the DataPower API Gateway, user-defined Policies are externally configured. To distribute the user-defined policies on the DataPower API Gateway, you create a Kubernetes ConfigMap that is installed using the extra values file. The ConfigMap ensures the policies are available to the Management server.

About this task

When to use the instructions in this task
Use the instructions in this topic for distributing user-defined policies when both of the following two conditions are met:
  • Your Gateway services is deployed on Kubernetes. The Management service is also usually deployed on Kubernetes.
  • Your topology uses the DataPower API Gateway, not the DataPower Gateway (v5 Compatible).

For an explanation of gateway types, see API Connect gateway types.

For a Kubernetes deployment with the DataPower® API Gateway, you can configure user-defined policies on the Gateway subsystem for distribution to API Manager as part of the deployment process, or you can configure user-defined policies at any time, on any platform, after the deployment process is complete. With the DataPower Gateway (v5 compatible) you can configure user-defined policies only after the deployment process is complete. For details of how to configure user-defined policies after deployment with either gateway type, see Authoring policies.

To configure user-defined policies on the Gateway subsystem for distribution to API Manager during deployment, you create a Kubernetes ConfigMap containing the code for the policy and then add an entry in the extra values file to point to the ConfigMap. When the APICUP installation command is executed, the externally-configured policies will be loaded into the DataPower configuration at start-up and then shared with the API Manager, which makes them available in the assembly palette. A Kubernetes ConfigMap ensures that the externally configured user-defined policies are available when the Gateway is started, across upgrades and restarts of the Gateway, and when scaling the number of pods in a cluster. The policies are uploaded directly to the apic-gw-service object, which was installed using the APICUP installer. See Installing the Gateway subsystem in a Kubernetes environment for instructions on installing the Gateway, including how to install the extra values file.

In cases where non-standard charts or other types of virtual or physical deployments, these policies must be mounted or placed on all the members of the Gateway service.

For topologies using a virtual or physical gateway with the DataPower API Gateway

If your topology uses a virtual (OVA) or physical DataPower Gateway and the DataPower API Gateway, then refer to the DataPower documentation for configuring an assembly function available here: Configuring an assembly function.


  • Create a configuration files containing the user-defined policies. In the following example, a configuration file named my-echo-policy.cfg defines a policy that sets the content of a response body from the value of a parameter.
    1. Define the policy in a file named, for example, my-echo-policy.cfg.

      The following DataPower configuration commands create an assembly-function object that represents the user-defined policy that will be advertised to the Management server in the ConfigMap. This example writes the value of the msg parameter provided as input to the user-defined policy to the message.body that is returned on the API invocation.

      assembly-setvar "my-echo-policy_1.0.0_assembly-setvar"
          action set
          name "message.body"
          type string
          value "$(local.parameter.msg)"
          action set
          name "message.headers.content-type"
          type string
          value "text/plain"
      api-rule "my-echo-policy_1.0.0_api-rule"
        action my-echo-policy_1.0.0_assembly-setvar
      assembly "my-echo-policy_1.0.0_assembly"
        rule my-echo-policy_1.0.0_api-rule
      assembly-function "my-echo-policy_1.0.0"
        summary "my-echo-policy_1.0.0"
        title "My Echo Policy"
          name "msg"
          description "The message string"
          value-type string
        assembly my-echo-policy_1.0.0_assembly
        user-defined-policies my-echo-policy_1.0.0
  • Add the configuration file to the ConfigMap.
    1. To make the .cfg files available to the Gateway subsystem, create a Kubernetes ConfigMap named, for example, custom-dp-config:
      kubectl create configmap custom-dp-config --from-file=my-echo-policy.cfg
  • Optionally, you can add your configuration files directly to the Helm chart.
    1. You create a directory for dynamic-gateway-service/config and place your configuration into a compressed tar file.
    2. Use apicup commands as shown below to place <your_config> into the Helm chart, so that it can be referenced by the values.yaml.

      For example:

      Figure 1. Using apicup to install configuration into the Helm Chart
      mkdir -p dynamic-gateway-service/config
      cp <your_config> dynamic-gateway-service/config/
      apicup subsys install gateway --out <dir>
      gunzip <dir>/helm/dynamic-gateway-service-X.X.XX.tgz
      tar -rf <dir>/helm/dynamic-gateway-service-X.X.XX.tar dynamic-gateway-service
      gzip <dir>/helm/dynamic-gateway-service-X.X.XX.tar
      mv <dir>/helm/dynamic-gateway-service-X.X.XX.tar.gz <dir>/helm/dynamic-gateway-service-X.X.XX.tgz
    3. In the extra values file, specify:
        -  domain: <some-domain>
           config: config/<your config>
    4. Run the following commands to install the gateway with the specified configuration:
      apicup subsys set gateway extra-values-file <extra values file>
      apicup subsys install gateway --plan-dir <dir>
    5. If you are updating an existing install, you also need to restart the pod by running the following command:
      kubectl delete pod/<gateway_pod_name> -n <namespace>
      The new gateway pod is then automatically created with the new configuration.
  • Optionally, you can add local files directly to the Helm charts.

    Local files can be added into the gateway deployment (Helm chart) by use of the datapower.additionalLocalTar value. This value is a path to a tar file which contains all the files you wish to add. This tar file should be a well formatted DataPower local: directory where files intended for the default domain are on the top level and all files intended for a different domain are in a subdirectory named for that domain.

    Use the same task flow as shown in Figure 1, but for the local path use local.tar.gz.

  • Optionally, you can add certificates to the ConfigMap.

    Certificates and other crypto files can be added to the cert: directory by use of the datapower.additionalCerts value. This value takes the form of a list of domain-secret pairs. The secrets are Kubernetes secrets which contain the crypto files you wish to use. To create the secrets from an existing crypto key-cert pair:

    1. Create the secrets from a specified file:
      kubectl create secret generic my-secret --from-file=/path/to/key.pem --from-file=/path/to/cert.pem
    2. Reference the secret in the extra values file by specifying:
        - domain: "default"
          secret: "some-default-cert-secret"
        - domain: "apiconnect"
          secret: "some-apiconnect-cert-secret"
  • Install the ConfigMap containing the policies using the extra values file and the APICUP installer.
    1. In order to configure the Gateway to use the custom policies in the custom-dp-config ConfigMap, set the customDatapowerConfig value to point to the ConfigMap in the extra values file:
      For information on the extra values file, see Creating an extra values file in a Kubernetes environment.
        customDatapowerConfig: "custom-dp-config"
    2. Point to the extra values file from the Gateway subsystem by entering apicup subsys set gwy extra-values-file path/file.
    3. Execute the apicup subsys install gwy command to install the Gateway with the extra values file containing the ConfigMap entry.
  • Use the externally-configured user-defined policy in an API.
    1. To use the externally-configured policy in the example from an API, create an assembly that resembles the following:
            - my-echo-policy:
                title: Echo msg
                version: 1.0.0
                msg: $(request.parameters.msg)
    2. A request against that API should have ?msg=<text> as a query parameter, and the response body should be equal to <text>, which is the value of the msg query parameter.