Installing the DataPower Gateway subsystem

Install the DataPower Gateway subsystem

Before you begin

Restriction: If you plan to install the Gateway subsystem in a remote cluster, you must install both the API Connect and the DataPower operators. The versions of the operators on the remote cluster and the version of the Gateway operand must exactly match the versions used in the main cluster.

About this task

Note: An alternate deployment scenario is to use a physical DataPower appliance for the gateway. If you are using an appliance for the gateway, do not install using API Connect Kubernetes CRs, since you do not need to configure a gateway subsystem in your Kubernetes cluster when using an appliance. For an appliance-based gateway, you must configure two endpoints in DataPower to be used as the Gateway Service Management Endpoint and the API invocation Endpoint. Enter these endpoints in the Configure Gateway Service screen in Cloud Manager. See Configuring DataPower Gateway for API Connect for instructions for configuring a DataPower appliance.

The installation folder where the helper_files.zip was extracted contains two templates for Gateway service. The v5cgateway_cr.yaml template is for the v5 compatible Gateway, and the apigateway_cr.yaml template is for the API Gateway.

Sample custom resource for API Gateway, apigateway_cr.yaml:

# 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:
      certmanager.k8s.io/issuer: ingress-issuer
    hosts:
    - name: rgw.$STACK_HOST
      secretName: gwv6-endpoint
  gatewayManagerEndpoint:
    annotations:
      certmanager.k8s.io/issuer: ingress-issuer
    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

Sample custom resource for v5-compatible Gateway, v5cgateway_cr:

# 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:
      certmanager.k8s.io/issuer: ingress-issuer
    hosts:
    - name: gw.$STACK_HOST
      secretName: gwv5-endpoint
  gatewayManagerEndpoint:
    annotations:
      certmanager.k8s.io/issuer: ingress-issuer
    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
Note: The DataPower Operator supports multiple instances of DataPower in the same cluster, separated by namespace. When deploying into multiple namespaces, ensure that any cluster-scoped resources are created with unique names for separate installations, such that they are not overwritten by subsequent installations. For example, DataPower cluster-scoped resources include ClusterRoleBindings.

Procedure

  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.5-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.
    $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.
    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: v10.0.1.2-ifix2 or later - 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 2 CPUs:

      template:
        - name: datapower
          containers:
          - name: gateway
            resources:
              requests:
                cpu: 2
      
      • 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 OpenTracing 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       10.0.1.5-eus   10.0.1.5-xxxx-eus        7m31s
    gwv6   True    2/2       10.0.1.5-eus   10.0.1.5-xxxx-eus        7m32s
    There is no need to wait for the READY status to be True before moving on to the next Subsystem installation.

What to do next

If you are creating a new deployment of API Connect, install other subsystems as needed.

When you have completed the installation of all required API Connect subsystems, you can proceed to defining your API Connect configuration by using the API Connect Cloud Manager; refer to the Cloud Manager configuration checklist.