Configuring your Gateway server extensions

You can add extra IBM® DataPower® enforcement capabilities to a Gateway service by using API Connect CLI commands to upload a .zip file that defines the required extension behavior, and then enabling the extension in IBM DataPower.

About this task

You upload Gateway server extensions by using the developer toolkit CLI.


  1. Log in to your API Connect Management server as an administrator, by using the following command:
    apic login --server mgmt_endpoint_url --username admin_user_ID --password admin_password --realm admin/identity_provider
    • mgmt_endpoint_url is the platform API endpoint URL.
    • admin_user_ID is the user ID of your administrator account, and is the same as the user ID that you use to log in to the Cloud Manager user interface.
    • admin_password is the password for your administrator account.
    • identity_provider is the identity provider that is used to authenticate administrative users.
    For example:
    apic login --server --username admin --password password --realm admin/myldap

    For full details on how to log in to your management server from the CLI, see Logging in to the management server.

  2. Upload the Gateway extension .zip file by using the following command:
    apic gateway-extensions:create extension_zip_file --scope org --org admin --gateway-service gateway_service --availability-zone availability-zone --server mgmt_endpoint_url
    • extension_zip_file is the Gateway extension .zip file that you want to upload.
    • gateway_service is the name of the Gateway service that you want add the extension to.
    • availability-zone is the name of the availability zone that contains the Gateway service.
    • mgmt_endpoint_url is the platform API endpoint URL.
    For example:
    apic gateway-extensions:create --scope org --org admin --gateway-service mygatewayservice --availability-zone availability-zone-default --server
    This example uses the default supplied availability zone name of availability-zone-default, which will be the required value if you have not configured your own availability zones. To check the names of the currently configured availability zones, use the following command:
    apic availability-zones:list --org admin --server mgmt_endpoint_url
    For details on configuring availability zones, see Creating an Availability Zone.
    To check the names of the currently configured gateway services, use the following command:
    apic gateway-services:list --org admin --availability-zone availability-zone --server mgmt_endpoint_url
    You can confirm that the extension has been added to the Gateway service by using the gateway-extensions:get command; for example:
    apic gateway-extensions:get --scope org --org admin --gateway-service mygatewayservice --availability-zone amyavailabilityzone --server --output -
    (the parameter setting --output - writes the details of the Gateway extension object to the command window. You can specify the name of an existing folder to have the details written to a .yaml file in that folder.)

    For reference details of the apic gateway-extensions commands, see apic gateway-extensions.

    Note: You cannot upload more than one Gateway extension .zip file to the same Gateway service. If you want add further extensions later, update the original .zip file, then use the apic gateway-extensions:update command to replace the previous gateway extensions file with the revised one; for example:
    apic gateway-extensions:update --scope org --org admin --gateway-service mygatewayservice --availability-zone myavailabilityzone --server
  3. Apply the extension to each server by restarting the API Connect gateway service object; complete the following steps on each Gateway server in the Gateway service:
    Note: In Kubernetes environments, the following steps can be accomplished by issuing kubectl delete pod on each gateway pod. Be sure to wait until each pod gets back to the ready state before deleting the next gateway pod.
    1. Remove the Gateway server from the load balancing group.
    2. Disable, then enable the API Connect gateway service object. You can do this by using either the DataPower administrative user interface in a web browser, or by using the DataPower CLI.
      • By using the administrative user interface:
        1. Log in to the DataPower administrative user interface; for the Graphical Interface, select WebGUI rather than Blueprint Console.
        2. Switch to the DataPower application domain for API Connect if necessary.
        3. Search for API Connect Gateway Service.
        4. Set the Administrative State to disabled.
        5. Apply the changes.
        6. Set the Administrative State to enabled.
        7. Apply the changes.
      • By using the CLI:
        1. Enter configuration mode by entering the command configure.
        2. Navigate to the DataPower application domain for API Connect by entering the command switch api_connect_domain_name, where api_connect_domain_name is the name of your API Connect application domain.
        3. Disable the API Connect gateway service object by entering the following command:
          apic-gw-service; admin-state disabled; exit
        4. Enable the API Connect gateway service object by entering the following command:
          apic-gw-service; admin-state enabled; exit
    3. Ensure that the gateway service object initialization has completed.
    4. Re-add the Gateway server to the load balancing group.


The extension is uploaded and applied to each of the servers in the Gateway service, and the associated enforcement capabilities are applied to all incoming API resource requests.
Warning: DataPower Gateway (Classic)
onlyIf you upload an extension to the DataPower Gateway (v5 compatible), a status file called extension_import_response.xml is written to the local:/ext folder in the gateway file system. Do not remove this file, otherwise if your gateway extension is subsequently removed then the referenced objects cannot be reverted to their original state automatically, and you will therefore have to either complete these clean up tasks manually, or re-add the gateway extension to regenerate the extension_import_response.xml file and then remove the gateway extension again. If the extension_import_response.xml exists and there is a cleanup failure for any object, a failure file is written to the local:/ext folder, with the failure details.