Migrating custom policies

The migration utility migrates API Connect Version 5 user-defined custom policies to API Connect Version 10. After migration, the v5 custom policies run on a v5-compatible DataPower Gateway or the DataPower API Gateway. Custom policies can be migrated to API Gateway with limitations.

Overview of the custom policy file format

Review your custom policies in the /cloud hierarchy that is created by the migration upack. The path to custom policies in the /cloud hierarchy structure is:

provider-orgs -> <provider-org-name> -> catalogs -> <catalog-name> -> configured-gateway-services -> <gateway-name> -> policies

The following example from a /cloud hierarchy shows custom policies for the catalog policy-and-vendor-ext-test listed under the gateway service g-w-1-8f82:


./provider-orgs/onlinebanking/catalogs/policy-and-vendor-ext-test/configured-gateway-services/
└── g-w-1-8f82
    ├── configured-gateway-service.yml
    └── policies
        ├── client-i-p-filter-policy-9d58-1.0.doc.yml
        ├── client-i-p-filter-policy-9d58-1.0.meta.yml
        ├── client-i-p-filter-policy-9d58-1.0.zip
        ├── client-i-p-filter-policy-9d58-2.0.doc.yml
        ├── client-i-p-filter-policy-9d58-2.0.meta.yml
        ├── client-i-p-filter-policy-9d58-2.0.zip
        ├── validate-auto-xsd-jsv-1.0.0.doc.yml
        ├── validate-auto-xsd-jsv-1.0.0.meta.yml
        ├── validate-auto-xsd-jsv-1.0.0.zip
        ├── validate-usernametoken-5.0.0.doc.yml
        ├── validate-usernametoken-5.0.0.meta.yml
        └── validate-usernametoken-5.0.0.zip

File naming legend:

  • *.doc.yml - the policy definition files
  • *.meta.yml - metadata used only by the migration utility.
  • *.zip - the custom policy zip files

Migrating custom policies to a v5-compatible gateway

A Version 5 custom policy definition is a zip file containing the yaml description of the policy (its name and configuration parameters) and the implementation zip of DataPower configuration that runs on the gateway. The zip file is pushed onto the gateway service used by any catalog that has APIs that make use of the policy. For more information on v5 custom policies, see User-defined policies in API Connect.

The migration utility migrates both the zip file and the yaml description file. After migration, the v5 custom policies run on a v5-compatible DataPower Gateway. Note that the structure of the custom policy zip file is the same in v5-compatible gateway as in v5. The v5-compatible gateway runtime will run any custom policy that a v5 gateway runs.

Migrating custom policies to API Gateway

Important: When migrating custom policies to v10 API Gateway, the v5-emulation layer is used to ease compatibility. For more information, see v5 policy emulation limitations.

You can migrate v5 custom policies to API Gateway using the v5-emulation layer. The migration utility bundles custom policies and groups them by gateway service during the port step. During the push step, the custom policies are pushed to the Gateway Service with instructions for DataPower to enable the v5-emulation layer, along with any v5-emulated or wrapped policies that were specified during the port step, such as invoke_1.5.0 or gatewayscript_1.0.0.

v5 policy emulation is deployed by the API Connect Gateway Service using a Gateway extensions manifest. For more information, see Gateway extensions manifest.

Note: If porting to API Gateway using the custom-policies-scope=catalog parameter, and spaces are contained in the v5 backup, then any duplicate custom policies found will be discarded. The final remaining custom policy out of the duplicates when pushed using archive:push will be pushed to all spaces within the same catalog. This is the correct behavior of the v10 API migration utility. For more details about pushing custom policies at the catalog (space) scope, see Importing a user-defined policy into a Catalog.