Configuring your Gateway server extensions

You can add extra DataPower enforcement capabilities to a gateway service by uploading a .zip file that defines the required extension behavior, and then enabling the extension in DataPower.

• To upload a Gateway server extension to a Gateway service by using the Cloud Manager user interface, complete the following steps:
  1. In the Cloud Manager user interface, click Topology.
  2. Alongside the required Gateway service, click the options icon , then click Configure gateway extension.
  3. Click Add.
     Note: You cannot upload more than one Gateway extension .zip file to the same Gateway service. If a Gateway server extension has previously been uploaded, the Add button is not available; you can replace the previous extension by clicking the options icon alongside gateway-extension, then clicking Edit.
  4. Upload the extension as indicated, either by dragging and dropping the .zip file, or by browsing and selecting it.
  5. Click Save when done.
• To upload a Gateway server extension by using the developer toolkit CLI, complete the following steps:
  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 availability-zone-default --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 the toolkit CLI reference documentation.

     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 mgt-admin.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 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.
  4. 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.

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.