Registering a gateway service

A gateway service is required to handle incoming traffic for APIs.

Before you begin

Before registering a DataPower® gateway service in Cloud Manager, the API Connect Gateway subsystem must be installed as a subsystem in your Kubernetes cluster, or enabled on the DataPower appliance. For a Kubernetes environment, see DataPower Gateway subsystem on Kubernetes. For appliances, see Configuring the API Connect Gateway Service in the appropriate version of the DataPower documentation.

About this task

A gateway service represents a cluster of gateway servers that host published APIs and provide the API endpoints used by client applications. Gateways execute API proxy invocations to backend systems and enforce API policies including client identification, security and rate limiting.

One of the following roles is required to register and manage DataPower gateway services:

Administrator
Topology Administrator
Owner
A custom role with the Topology:Manage permission

Note: You can also register, and manage, DataPower gateway services using the developer toolkit CLI; for details, see the toolkit CLI reference documentation.

Procedure

Complete the following steps to configure a DataPower gateway service for your cloud:

In the Cloud Manager, click Topology.
From the availability zone that will contain the DataPower gateway service, select Register Service.
On the Configure Service page, select DataPower Gateway as the service type. Select the gateway type that you want to create, either DataPower Gateway (v5 compatible) or DataPower API Gateway. For a description of the gateway types, see API Connect gateway types.

Note: The option to enable LDAP connection pooling is only supported with the DataPower API Gateway v10.6.0.0 or later.
Enter the values to configure the DataPower gateway service. Obtain the endpoints from your deployment configuration. For a Kubernetes environment, the endpoints are configured by the following values in the CR (custom resource) file. For an appliance, the endpoint is configured in DataPower.

Field	Description
Title (required)	Enter a descriptive display title for the DataPower gateway service.
Name (required)	This field is populated for and is used as the internal field name.
Summary (optional)	Enter a brief description.
Management endpoint on the gateway service: Endpoint (required)	Enter the API Connect Gateway Service endpoint. For a Kubernetes environment, the Management Endpoint is the endpoint created in the CR (custom resource). See DataPower Gateway subsystem on Kubernetes for more information. For an appliance, the Management Endpoint is the Management address to the API Connect Gateway Service shown in the gateway service connection diagram. For one gateway, this takes the form https://<ip-address-for-gateway>:3000. For multiple gateways, it would be the address:port of the load balancer If you are using `in-cluster` communication, set this to the service endpoint URL for the gateway, which has the format: `https://<name>.<namespace>.svc` where: `<name>` is the `name` property from the gateway subsystem CR. If you are using the top-level CR this is `<apic instance name>-gw` `<namespace>` is the namespace that the gateway CR exists in.
Management endpoint on the gateway service: TLS client profile (required)	Specify the TLS client profile to use when the management subsystem initiates communication with the gateway. The client profile contains the TLS client certificate that is presented to the gateway when establishing a secure connection. Important: Do not leave this property unset. You must specify a client profile for secure management to gateway communication (mTLS). If you do not want to use mTLS, then you can configure JWT instead: Use JWT instead of mTLS on VMware. Use JWT instead of mTLS on Kubernetes and OpenShift. The default profile to use is Gateway management client TLS client profile:1.0.0. On a Kubernetes or OpenShift deployment where the management and gateway subsystems are in the same namespace, the gateway service is automatically configured (during installation) to trust the Gateway management client TLS client profile:1.0.0. If you want to use a different client certificate, do not update the Gateway management client TLS client profile:1.0.0, create a new client profile that uses the certificate you want. See Creating a TLS client profile. If you are registering a gateway appliance, then configure your gateway to trust the client profile that you select. For more information about configuring TLS on your gateway appliance, see ../com.ibm.apic.install.doc/tapic_install_datapower_gateway_apigwy.html. ../com.ibm.apic.install.doc/tapic_install_datapower_gateway_v5compat.html. Do not configure your gateway appliances with client authentication disabled.
Management endpoint on the gateway service: Use in-cluster communucation	If you want to use `in-cluster` communication between the management and gateway subsystems, then enable this switch. For more information about this option, see In-cluster or external communication between subsystems. If you are not sure, then leave this switch disabled (the default).
Management endpoint on the gateway service: Use JWT for gateway authentication to analytics service	If you plan to associate an analytics service with this gateway, and you want to use JWT authentication between the gateway and analytics service, then enable this switch. If this switch is not enabled, then mutual TLS authentication is used between the gateway and analytics service. For more information about JWT security, see Enable JWT security instead of mTLS
Use LDAP connection pool	Enable this option when you want to optimize LDAP user registry processing by enabling LDAP connection pooling. Connection pooling reduces overhead and improves performance by maintaining a pool of connections and assigning them as needed. When a connection is closed, it is returned to the connection pool for future use. Note: LDAP connection pooling is supported only with the DataPower API Gateway v10.6.0.0 or later. You cannot enable LDAP connection pooling during the initial registration of the DataPower API Gateway service. Instead, complete the registration steps and click Save; then edit the registration to enable the use of connection pools. Configure the following settings for the connection pool: Max pool size: (Defaults to 35 connections) The maximum number of connections for an LDAP `server:port:BindDN` combination in the LDAP connection pool. For example, if the LDAP connection pool has six combinations and this value is 10, each combination supports 10 connections and the connection pool can have 60 connections. Idle timeout: (Defaults to 120 seconds) The length of time, in seconds, before an idle connection is removed from the connection pool. Document cache size: (Defaults to 0 bytes) The maximum size of the LDAP cache, in bytes. The largest supported cache size is 2147483647 bytes. Using a cache improves performance by reducing the number of times that the LDAP server must be contacted.
Enable AI Gateway	For the new DataPower API Gateway service, AI Gateway is enabled by default in API Connect v10.0.8.1. If you are upgrading to v10.0.8.1 from the previous versions, this property is disabled for all existing DataPower API Gateway services. When AI Gateway service is enabled, it allows you to access AI Gateway policies directly on the DataPower API Gateway. For details, see Using the AI Gateway to support APIs for AI applications. When you disable AI Gateway, the following actions occur: AI Gateway policies that were not used by any published APIs are deleted. AI Gateway policies that were used by any published APIs remain intact.
API invocation endpoint: API endpoint base (required)	Enter the base portion of the URL that maps to the base portion of the URL for incoming API traffic. It is a public FQDN with additional paths that are specific to your API calls. For example: https://api.mycompany.com Note: If you are using the DataPower API Gateway, HTTP/2 is enabled automatically on the API invocation endpoint. If you are using the DataPower Gateway (v5 compatible), HTTP/2 is not supported on the API invocation endpoint.
API invocation endpoint: Server Name Indication (SNI) - Host name	For supporting Server Name Indication (SNI) at the API Endpoint Base. The default hostname of '' is required to allow all hosts. Enter other host names as needed. Wild card format is supported. The SNI capability enables you to serve multiple TLS secure host names through the same Gateway service, using the same IP address and port, without requiring them to use the same TLS profile. Note: To allow requests from clients that don't support SNI, you must* include a host name value of '*'.
API invocation endpoint: Server Name Indication (SNI) - TLS server profile	The TLS server profile that supports the given hostname for SNI. The server profile that is selected here contains the server certificate that is presented to callers of the APIs you publish on the gateway. By default this profile is set to Default TLS server profile. Best practice is to create your own TLS server profile that contains the certificate you want on your API invocation endpoint. For more information about configuring TLS server profiles, see TLS profiles overview. Restriction: If you are using the DataPower API Gateway, HTTP/2 is enabled automatically on the API invocation endpoint. Therefore, using a TLS server profile that supports only TLS protocol version 1.3 is not supported and will result in the gateway being unable to receive API traffic. You must use a TLS server profile that includes TLS protocol version 1.2 as one of its supported protocols. This restriction does not apply if you are using the DataPower Gateway (v5 compatible), which does not support HTTP/2.
OAuth shared secret (optional)	For sites using native OAuth providers, enter the shared secret that will be used by all API calls going through the gateway. Note: The specified shared secret must be 64 characters (64 bytes) in length, prefixed with `0x`, and must consist only of hexadecimal characters. For example: `0xa354282f227c10250511ae9c9e8c7ed9f4f1bd0d7c04cb6d5bd178f8c62296e3` Note: If you change the shared secret, all the previously issued tokens become invalid.

The following diagram illustrates the DataPower gateway service connection:

When you are finished, click Save.
If you want, you can delete the gateway service as follows;
1. If the gateway service is already in use by any of the catalogs, you must disable the gateway service as follows:
  1. Log in to API Manager.
  2. Click Manage, then select the catalog.
  3. Click Catalog settings.
  4. Click Gateway services.
  5. Click Edit.
  6. Remove the checkmark from the corresponding gateway service.
  7. Click Save.
2. Log in to the Cloud Manager user interface.
3. In the navigation list, click Topology.
4. Click the options menu icon alongside the corresponding gateway service, then select Delete.
5. Click Delete on the confirmation prompt.

Results

The DataPower gateway service is added to the appropriate availability zone for your cloud.

What to do next

Associate the DataPower gateway service with an analytics service, and set the visibility for the gateway. Add additional DataPower gateway services, or add one or more event gateway services, analytics services, or portal services.