Gateway extensions manifest

The gateway extensions manifest controls how gateway extensions are applied to the DataPower® API Gateway.

The gateway extensions manifest enables you to deploy multiple extension implementations in a single package. The manifest is a JSON file that lists the extensions .zip files to be applied and when they are to be deployed. You can also use the manifest to enable v5 policy emulation for the API Connect gateway service. V5 policy emulation enables you to deploy supported v5 built-in policies and custom policies, and manage them from API Manager without having to rewrite them for DataPower API Gateway. V5 policy emulation is supported only for policies that are applied to the Gateway service scope.

The manifest.json file must be at the root level of the extensions .zip file, along with the gateway extension files specified in the manifest. For example:

manifest.json
jws-sign-policy.zip
add_udp.zip

The manifest.json file contains the following sections.

`properties` section

The properties section determines whether to enable the v5 framework to deploy supported v5 built-in policies and custom policies and manage them from API Manager without having to rewrite them for DataPower API Gateway.

Table 1. `properties` section properties
Property	Description
`deploy-policy-emulator`	Determines whether to enable v5 framework emulation. Valid values are `true` and `false`. v5 framework emulation is enabled for the API Connect Gateway service if `deploy-policy-emulator` set to `true`, if a v5 policy is detected in the files list, or if a `deploy-policies` entry is specified.
`deploy-policies`	Contains a list of built-in policies to advertise for v5 emulation. The following policies are supported. `activity-log_1.5.0` `gatewayscript_1.0.0` `if_1.5.0` `invoke_1.5.0` `proxy_1.5.0` `redact_1.5.0` `switch_1.5.0` `validate-usernametoken_1.0.0` `xslt_1.0.0`
`defer-all-override`	An override toggle to force the deployment property of all extension entries (including V5E) to be deferred. When enabled, the user must restart the `apic-gw-service` object to apply any extension events.

`files` section

The files section is an array of file entries that reference extension implementations. Each entry must reference a file that is in the extension.zip file (or the extension is rejected).

Table 2. `files` section properties
Property	Description
`filename`	The name of the file that contains the extension implementation. This property is required and cannot be changed while the extension is deployed as part of an update.
`type`	The type of extension implementation to be deployed. This property is required. The following types are supported. `dp-import` A DataPower import used to add additional configuration and/or services to a gateway. Like the extension type, but `dp-import` persists the configuration on physical or virtual DataPowers. Note: A `dp-import` file cannot be used to change the `apic-gw-service` object. If it is configured for this purpose, the extension is rejected. `extension` A legacy API Gateway extension that can be used to add additional configuration to a gateway. `Extension` should not be used to modify objects created by the API Connect gateway service, see gwd_extension for that use case. For more information, see Gateway extension guidelines - DataPower API Gateway. `gwd_extension` A JSON file that allows users to customize objects created by the API Connect gateway service. Only one `gwd_extension` is allowed in the manifest. For more information about the `gwd_extension`, see GWD extension type. `policy-v5` A complete, valid v5 policy implementation. For more information, see Authoring policies for the DataPower Gateway (v5 compatible). `user-defined-policy` A native API Gateway policy packaged in a DataPower import zip. Using a DataPower import to apply the policy implementations allows the configuration to persist through restarts and upgrades on virtual and physical forms. The import might contain one or more policy implementations. This policy type is always global scoped. For more information, see Defining, packaging, and publishing a global-scoped policy for the API Gateway. `user-defined-policy-yaml` A YAML file that includes an assembly. This policy type is always global scope. If the assembly references another user-defined policy, that policy must already be advertised to the API Manager before it can be deployed. For more information, see Working with global policies. `v5_extension` A migrated v5 extension that the migration utility generates. Only certain parts of v5 extensions are usable in API Gateway. For more information, see Migrating gateway extensions. `v5_extension` is reserved for v5 extensions that the migration utility creates. Do not manually create this type of extension. Note: V5E is intended to allow users to migrate from V5 without editing their APIs. V5E type policies cause known performances degradations in the API gateway. To improve performance of V5E policies, it is recommended to convert them to native policies.
`deploy`	When to deploy the extension entry. If you are deploying extensions that might cause a temporary API Connect gateway service outage, it is recommended to use deferred. `immediate` Deploy the extension entry immediately when the API Connect gateway service receives it. All gateway nodes apply the extension in parallel. Warning: `immediate` can cause an outage across the cluster, dependent on what the extension does. `deferred` A managed deployment strategy that applies the extension entry after the API Connect gateway service is restarted. This value is the default. Using deferred allows the user to do a controlled roll out of the extension across the cluster. When a DRR occurs this property is ignored, and all entries are deployed immediately.
`catalog`	Indicates that a v5 policy is to be used only by certain catalogs and should not be advertised as a gateway service-level user policy. This property is valid only if the file type is `policy-v5`. The `catalog` value must be in the format `orgname_catalogname`.

Example `manifest.json`

The following example manifest.json file enables v5 policy emulation and specifies two built-in v5 policies to deploy. The files section lists two v5 policy implementation files and two extension files.

{
   "extension":{
      "properties":{
         "deploy-policy-emulator":true,
         "deploy-policies":[
            "invoke_1.5.0"
         ]
      },
      "files":[
         {
            "filename":"proxy_service.zip",
            "deploy":"immediate",
            "type":"dp-import"
         },
         {
            "filename":"add_udp.zip",
            "deploy":"deferred",
            "type":"extension"
         },
         {
            "filename":"override-parse-defaults.json",
            "type":"gwd_extension"
         },
         {
            "filename":"jws-sign-policy.zip",
            "deploy":"immediate",
            "type":"policy-v5"
         },
         {
            "filename":"jwe-decrypt-policy.zip",
            "deploy":"deferred",
            "type":"policy-v5",
            "catalog":"extension-org_ext-cat-2"
         },
         {
            "filename":"mypolicy.zip",
            "deploy":"immediate",
            "type":"user-defined-policy"
         },
         {
            "filename":"Invoke-Private-Backend-policy.yaml",
            "deploy":"immediate",
            "type":"user-defined-policy-yaml"
         }
      ]
   }
}

Gateway extensions manifest

properties section

files section

Example manifest.json

`properties` section

`files` section

Example `manifest.json`