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.

1. Log in to your API Connect Cloud Manager server as an administrator, using the following command:

   apic login --server <cloud-manager_endpoint_url> --username <admin_user_ID> --password <admin_password> --realm admin/<identity_provider>

   where:

   • <cloud-manager_endpoint_url> is the Cloud Manager endpoint URL; for example: mgmt-admin.<myserver>.com.
   • <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 mgmt-admin.myserver.com --username admin --password my-admin-password --realm admin/myldap

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 <cloud-manager_endpoint_url>

   where:

   • <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.
   • <cloud-manager_endpoint_url> is the Cloud Manager endpoint URL.

   For example:

   apic gateway-extensions:create myextension.zip --scope org --org admin --gateway-service mygatewayservice --availability-zone availability-zone-default --server mgt-admin.myserver.com

   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 <cloud-manager_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 <cloud-manager_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 mgt-admin.myserver.com --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 mynewextension.zip --scope org --org admin --gateway-service mygatewayservice --availability-zone myavailabilityzone --server platform-api.myserver.com

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.

Results

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: If 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.