Installing the DataPower Gateway subsystem

Install the DataPower Gateway subsystem

# Licensed Materials - Property of IBM
#
# (C) Copyright IBM Corporation 2020 All Rights Reserved
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with
# IBM Corp.

apiVersion: gateway.apiconnect.ibm.com/v1beta1
kind: GatewayCluster
metadata:
  name: gwv6
  labels: {
    app.kubernetes.io/instance: "gateway",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "gwv6"
  }
spec:
  version: $APP_PRODUCT_VERSION
  profile: $PROFILE
  imagePullSecrets:
  - $SECRET_NAME
  imageRegistry: $DOCKER_REGISTRY
  apicGatewayServiceV5CompatibilityMode: false
  gatewayEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    ingressClassName: $INGRESS_CLASS
    hosts:
    - name: rgw.$STACK_HOST
      secretName: gwv6-endpoint
  gatewayManagerEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    ingressClassName: $INGRESS_CLASS
    hosts:
    - name: rgwd.$STACK_HOST
      secretName: gwv6-manager-endpoint
  apicGatewayServiceTLS:
    secretName: gateway-service
  apicGatewayPeeringTLS:
    secretName: gateway-peering
  datapowerLogLevel: 3
  license:
    accept: false
    use: production
  tokenManagementService:
    enabled: true
    storage:
      storageClassName: $STORAGE_CLASS
      volumeSize: 30Gi
  adminUser:
    secretName: $ADMIN_USER_SECRET
  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

# Licensed Materials - Property of IBM
#
# (C) Copyright IBM Corporation 2020 All Rights Reserved
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with
# IBM Corp.

apiVersion: gateway.apiconnect.ibm.com/v1beta1
kind: GatewayCluster
metadata:
  name: gwv5
  labels: {
    app.kubernetes.io/instance: "gateway",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "gwv5"
  }
spec:
  version: $APP_PRODUCT_VERSION
  profile: $PROFILE
  imagePullSecrets:
  - $SECRET_NAME
  imageRegistry: $DOCKER_REGISTRY
  apicGatewayServiceV5CompatibilityMode: true
  gatewayEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    ingressClassName: $INGRESS_CLASS
    hosts:
    - name: gw.$STACK_HOST
      secretName: gwv5-endpoint
  gatewayManagerEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    ingressClassName: $INGRESS_CLASS
    hosts:
    - name: gwd.$STACK_HOST
      secretName: gwv5-manager-endpoint
  apicGatewayServiceTLS:
    secretName: gateway-service
  apicGatewayPeeringTLS:
    secretName: gateway-peering
  datapowerLogLevel: 3
  license:
    accept: false
    use: production
  adminUser:
    secretName: $ADMIN_USER_SECRET
  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

1. Edit the template CR, to replace the placeholders with values for your deployment.

   $APP_PRODUCT_VERSION

   API Connect application version for the subsystems.

   version: <version_number> 

   For example: version: 10.0.1.7-eus

   $PROFILE

   • Development profile

     profile: n1xc4.m8

     • Describes a hardware profile of 1 nodes, 4 cores, and 8 GB memory
     • Deploys a subsystem with the scale of one; a single node, non-HA subsystem.
     • Recommended use of this profile is for development and testing.
   • Production profile

     profile: n3xc4.m8

     • Describes a hardware profile of 3 nodes, 4 cores, and 8 GB memory
     • Deploys in HA mode for a production environment.
     • Supported for installation of three or more nodes. Not supported for less than three nodes.

   Note:

   • While it is possible to use n1xc4.m8 profile installations in a production deployment, it is not recommended. The n1xc4.m8 profile does not provide the failover resiliency nor the downtime guarantee that is needed to maintain high availability (HA) production deployments.
   • The only supported values for the Gateway subsystem are n1xc4.m8 and n3xc4.m8.

   $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 is an optional property 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 host names 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.

   adminUserSecret: $ADMIN_USER_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 use: to either production or nonproduction, to match the license you purchased.

   Example entry to accept the license for a production system:

     license:
       accept: true
       use: production

3. Optional: If applicable to your deployment, you can override the resource settings for CPU and memory.
   • CPU override

     When you specify spec.license.use: nonproduction and a single node Development profile profile: n1xc4.m8, the default CPU request for the gateway pod is 1 CPU. You can manually override this setting. For example, to request 4 CPUs:

     template:
       - name: datapower
         containers:
         - name: gateway
           resources:
             requests:
               cpu: 4
     

     • When you specify spec.license.use: production and a single node Development profile profile: n1xc4.m8, the default CPU request for the gateway pod is 4 CPUs.
     • The CPU limit cannot be specified separately from the CPU request. The value for the CPU request is used as both CPU request and CPU limit in the Gateway CR.
   • Memory override

     The default memory limit and request is 8Gi. The memory limit should always be greater than or equal to the memory request.

     For example, to request 10Gi and set a limit of 12Gi:

      template:
       - name: datapower
         containers:
         - name: gateway
           resources:
             limits:
               memory:  12Gi
             requests:
               cpu: 2
               memory: 10Gi

   Note: The override mechanism is specific only to the CPU and memory values, and cannot be used for other resource requests in the DataPower Gateway CR.

4. For apigateway_cr.yaml only, you can optionally enable openTracing.
   1. Edit the CR to add the following properties, and supply values for each:

      openTracing:
          enabled: false # if true provide below details
          odTracingRegistrationHostname: $OD_TRACING_REGISTRATION_HOSTNAME
          odTracingDataHostname: $OD_TRACING_HOSTNAME
          imageAgent: $AGENT_IMAGE
          imageCollector: $COLLECTOR_IMAGE

      Where:

      enabled

      enabled: true

      $OD_TRACING_REGISTRATION_HOSTNAME

      odTracingRegistrationHostname: icp4i-od.tracing.svc

      The hostname of the registration server for OpenTracing.

      $OD_TRACING_HOSTNAME

      odTracingDataHostname: od-store-od.tracing.svc

      The hostname of the data server for OpenTracing.

      $AGENT_IMAGE

      imageAgent: icp4i_od_agent:1.0.0-amd64

      Image will be pulled from the imageRegistry of this CR.

      $COLLECTOR_IMAGE

      imageCollector: icp4i_od_collector:1.0.0-amd64

      Image will be pulled from the imageRegistry of this CR.

   2. During the Open Tracing registration process, name the secret that stores credentials icp4i-od-store-cred, and add it to the cluster and into the installation namespace.
5. 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.

6. Optional: If applicable to your deployment, update the GatewayCluster CR to configure DataPowerService APIs to customize your DataPower deployment. See Customizing a DataPower deployment.
7. 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>

8. 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>-eus   <version>-<build>-eus        7m31s
   gwv6   True    2/2       <version>-eus   <version>-<build>-eus        7m32s

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