Installing the gateway subsystem

Install the DataPower gateway subsystem

1. Edit the template CR, either apigateway_cr.yaml or v5cgateway_cr.yaml, to replace the placeholders with values for your deployment.

   $APP_PRODUCT_VERSION

   API Connect application version for the subsystems.

   version: <version_number>

   Example version number: 10.0.8.2-ifix2

   $PROFILE

   Specify your gateway profile, where n indicates number of replicas, c number of cores, and m is the minimum memory allocation in GB. For more information on profiles, see Deployment and component profiles.

   $SECRET_NAME

   Use for image pull.

   
   imagePullSecrets:
     - apic-registry-secret

   $DOCKER_REGISTRY

   The host name of the Docker Registry to which you uploaded the installation images. For example:

   my.docker.registry.domain.example.com.

   $INGRESS_CLASS

   The ingress class that you want the endpoint to use. This property is optional and if not specified, the ingress class with annotation ingressclass.kubernetes.io/is-default-class: true is used. If such an ingress class does not exist in the Kubernetes environment, then nginx is used. If you do set this value, it must refer to a valid ingress class configured in your Kubernetes system.

   Note: This property is commented out in the template CR file. If you set this value, make sure to also uncomment it.

   $STACK_HOST

   The desired ingress subdomain for the API Connect stack. Used when specifying endpoints. Domain names that are used for endpoints cannot contain the underscore "_" character. You can do one of the following:

   • Subdomain customization only

     Accept the prefixes predefined for the ingress hostnames to use and just replace all instances of STACK_HOST to be the desired ingress subdomain for the API Connect stack. For example, if your host is myhost.subnet.example.com:

     gatewayEndpoint:
         < ... >
       hosts: 
       - name: rgw.myhost.subnet.example.com
         secret: gwv6-endpoint
       
     gatewayManagerEndpoint:
          < ... >
       hosts: 
       - name: rgwd.myhost.subnet.example.com
         secret: gwv6-manager-endpoint
       

   • Complete hostname customization

     Change both the predefined prefixes and the STACK_HOST subdomain to match your desired hostnames.

     For example, for gatewayEndpoint, you can replace rgw.$STACK_HOST with my.gateway.endpoint.myhost.subnet.example.com, where my.gateway.endpoint replaces rgw, and myhost.subnet.example.com replaces $STACK_HOST:

     gatewayEndpoint:
            < ... >
         hosts: 
         - name: my.gateway.endpoint.myhost.subnet.example.com
           secret: gwv6-endpoint

     You can do this for some or all of the hostnames, depending on your customization requirements.

   $STORAGE_CLASS

   The Kubernetes storage class to be used for Persistent Volume Claims. Find the available storage classes in the target cluster by running the following command: kubectl get sc.

   storageClassName: local-storage

   $ADMIN_USER_SECRET

   Edit $ADMIN_USER_SECRET to set the value you created in Deploying operators and cert-manager.

   adminUserSecret: $ADMIN_USER_SECRET

   $PLATFORM_CA_SECRET

   Set to ingress-ca. The $PLATFORM_CA_SECRET contains the CA certificate for the platform REST API endpoint. The gateway makes calls to the platform REST API and this property must be set so that the gateway can verify the server certificate.

   mgmtPlatformEndpointCASecret:
     secretName: $PLATFORM_CA_SECRET

2. Edit the license: setting:
   1. Set accept: to true to accept the license. Note that the default value is false. If you do not accept the license, the Operator will not install the subsystem.
   2. Set metric: to track your product usage. Enter the unit of measure that is used for your program license:
      • PROCESSOR_VALUE_UNIT - Default value. If you leave the field blank, this value is used.
      • MONTHLY_API_CALL - Applies only to the IBM API Connect Hybrid Entitlement program.

      For information on tracking monthly call volume, see Tracking API volume for auditing and compliance.

   3. Set use: to either production or nonproduction, to match the license you purchased.
   4. Set license: to the License ID for the version of API Connect that you purchased. See API Connect licenses.

   Example entry to accept the license for a production system:

     license:
       accept: true
       metric: PROCESSOR_VALUE_UNIT 
       use: production
       license: L-RJON-BZ5LSE

3. Enable or disable syslogConfig.

   syslogConfig:
       enabled: false # if true, provide below details
       # remoteHost: $DATAPOWER_SYSLOG_TCP_REMOTE_HOST # must be a string
       # remotePort: $DATAPOWER_SYSLOG_TCP_REMOTE_PORT # must be an int
       # secretName: $DATAPOWER_SYSLOG_TCP_TLS_SECRET # must be a string

   • To disable syslog, remove the syslogConfig block from apigateway_cr.yaml and v5cgateway_cr.yaml. Alternatively, you can set syslogConfig.enabled to false.
   • To enable syslogConfig in the gateways, set the following values in apigateway_cr.yaml and v5cgateway_cr.yaml:

     enabled

     enabled: true

     $DATAPOWER_SYSLOG_TCP_REMOTE_HOST

     remoteHost: <remote.host>

     String. The hostname of the server for syslogConfig.

     $DATAPOWER_SYSLOG_TCP_REMOTE_PORT

     remotePort: <remote_port_number>

     Integer. The port number of the server for syslogConfig.

     $DATAPOWER_SYSLOG_TCP_TLS_SECRET

     secretName: <secret>

     String. The TLS secret name of the server for syslogConfig.

4. Optional: If applicable to your deployment, update the GatewayCluster CR to configure DataPowerService APIs to customize your DataPower deployment. See Customizing a DataPower deployment.
5. Enable mutual TLS between the management client and the gateway service’s manager endpoint, add mtlsValidateClient to the spec section:
   Important: Do not skip this step, if you do not want to use mTLS for management to gateway communication, then you can enable JWT instead.

   spec:
     mtlsValidateClient: true

   This ensures that the gateway service authenticates incoming requests from the API Manager, such as gateway service registration, and publishing APIs to the gateway service. Specifically, the gateway service requires that incoming requests present a certificate that was signed by the same CA that was used to sign the gateway service management endpoint. The gateway service management endpoint secret is specified under gatewayManagerEndpoint.hosts.secretName. The API Manager’s gateway client’s TLS credentials are specified in the ManagementCluster CR under gateway.client.secretName.

6. Optional: If you want to enable JWT security for communications between the management and gateway, add and set the property jwksUrl, and set spec.mtlsValidateClient to false.

   spec:
     ...
     jwksUrl: <JWKS URL>
     mtlsValidateClient: false

   where <JWKS URL> is the URL of the JWKS endpoint that is hosted on the management subsystems. To find out the jwksUrl, describe the management CR and check the status: section:

   kubectl describe mgmt -n <namespace>
   ...
   status:
     - name: jwksUrl
       secretName: api-endpoint
       type: API
       uri: https://api.apic.acme.com/api/cloud/oauth2/certs

   For more information about JWT security, see Enable JWT security instead of mTLS.
7. Optional: If you want to use the In-cluster inter-subsystem communication feature, then uncomment the mgmtPlatformEndpointSvcCASecret section, and set the secretName:

     mgmtPlatformEndpointSvcCASecret:
       secretName: management-ca  # Usually management-ca

   Unless you customized your internal certificates, this is always management-ca.
8. Optional: Enable autoscaling of gateway pods to ensure high availability of DataPower pods. See Enabling autoscaling of gateway pods.
9. Install the gateway Custom Resource by applying the gateway template file:
   For a DataPower API Gateway, run the following command:

   kubectl apply -f apigateway_cr.yaml -n <namespace>

   For a DataPower Gateway (v5 compatible), run the following command:

   kubectl apply -f v5cgateway_cr.yaml -n <namespace>

10. To verify that the gateway subsystem(s) are fully installed, run the following command:

    kubectl get GatewayCluster -n <namespace>

    The installation has completed when the READY status is True, and the SUMMARY reports that all services are online ( 2/2) for all the gateway subsystems that were installed. Example:

    NAME   READY   SUMMARY   VERSION    RECONCILED VERSION   AGE
    gwv5   True    2/2       <version>  <version-build>      7m31s
    gwv6   True    2/2       <version>  <version-build>      7m32s

    There is no need to wait for the READY status to be True before moving on to the next Subsystem installation.