Installing the Gateway subsystem

Install the Gateway subsystem by creating and applying the ingress-ca, common-issuer, gateway-certs and gateway_cr YAML files.

Before you begin

Important: When you install the gateway subsystem, you must configure the gateway subsystem so that communication from the management subsystem is secured with either mTLS or JWT. For more information on inter-subsystem communication, see Network requirements for inter-subsystem communication.

When installing subsystems in different namespaces you must first create the cert-manager issuers and certificates required by that subsystem in the same namespace.

  1. Using the file obtained from Extracting the Management ingress-ca certificates, run: oc apply -f ingress-ca.yaml -n <gateway namespace>
  2. Create a file called common-issuer-and-gateway-certs.yaml and paste in these contents:
    #
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

---

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigning-issuer
  labels: {
    app.kubernetes.io/instance: "management",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "selfsigning-issuer"
  }
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ingress-issuer
  labels: {
    app.kubernetes.io/instance: "management",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "ingress-issuer"
  }
spec:
  ca:
    secretName: ingress-ca
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: gateway-service
  labels: {
    app.kubernetes.io/instance: "gatewaycluster",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "gateway-service"
  }
spec:
  commonName: gateway-service
  secretName: gateway-service
  issuerRef:
    name: ingress-issuer
  usages:
  - "client auth"
  - "signing"
  - "key encipherment"
  duration: 17520h # 2 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: gateway-peering
  labels: {
    app.kubernetes.io/instance: "gatewaycluster",
    app.kubernetes.io/managed-by: "ibm-apiconnect",
    app.kubernetes.io/name: "gateway-peering"
  }
spec:
  commonName: gateway-peering
  secretName: gateway-peering
  issuerRef:
    name: ingress-issuer
  usages:
  - "server auth"
  - "client auth"
  - "signing"
  - "key encipherment"
  duration: 17520h # 2 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
  3. Apply the above YAML file with: oc apply -f common-issuer-and-gateway-certs.yaml -n <gateway_namespace>
  4. Confirm that the issuers were created and are in ready state: 
    
oc get issuers -n <gateway namespace>
NAME                 READY
ingress-issuer       True
selfsigning-issuer   True
  5. Confirm that the gateway secrets were created with oc get secrets -n <gateway namespace>:
    oc get secrets -n <gateway namespace>
NAME                       TYPE                                  DATA   AGE
...
gateway-peering            kubernetes.io/tls                     3      2m
gateway-service            kubernetes.io/tls                     3      2m3s
...

About this task

Use the OpenShift CLI to edit the custom resource template for the Gateway, apply the resource, verify that the pods are up and running.

Procedure

  1. Create the gateway admin secret with: oc -n <gateway namespace> create secret generic admin-secret --from-literal=password=admin
  2. If you are installing the API Gateway (v6), create a yaml file that is called apigateway_cr.yaml and paste in these contents: 
    #
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#


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
  apicGatewayServiceV5CompatibilityMode: false
  mgmtPlatformEndpointCASecret:
    secretName: ingress-ca
  mgmtPlatformEndpointSvcCASecret:
    secretName: management-ca
  gatewayEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: rgw.$STACK_HOST
      secretName: gwv6-endpoint
  gatewayManagerEndpoint:
    annotations:
      cert-manager.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: $LICENSE_ACCEPTANCE
    use: $LICENSE_USE
    license: '$LICENSE_ID'
  tokenManagementService:
    enabled: true
    storage:
      storageClassName: $STORAGE_CLASS
      volumeSize: 30Gi
  adminUser:
    secretName: admin-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
    If you are installing the v5 Gateway, create a YAML file that is called v5gateway_cr.yaml and paste in these contents:
    #
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#


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
  apicGatewayServiceV5CompatibilityMode: true
  gatewayEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: gw.$STACK_HOST
      secretName: gwv5-endpoint
  gatewayManagerEndpoint:
    annotations:
      cert-manager.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: $LICENSE_ACCEPTANCE
    use: $LICENSE_USE
    license: '$LICENSE_ID'
  adminUser:
    secretName: admin-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
  3. Edit the YAML file and set the variables:
    $APP_PRODUCT_VERSION
    API Connect application version for the subsystems. 
    version: <version_number>

    Example version number: 10.0.5.9

    $PROFILE

    Specify your Gateway subsystem 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 Planning your deployment topology.

    $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 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 host name customization

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

      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 OCP storage class to be used for Persistent Volume Claims. Find the available storage classes in the target cluster by running the following command: oc get sc.
    storageClassName: local-storage
    $LICENSE_ACCEPTANCE
    Set accept to true. You must accept the license to successfully deploy API Connect.
    $LICENSE_USE
    Set use to either production or nonproduction to match the license that you purchased.
    $LICENSE_ID
    Set license: to the license ID for the version of API Connect that you purchased. See API Connect licenses.
    syslogConfig
    To enable this feature uncomment this section, set enabled: true, and set the properties:
    $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 you are installing Cloud Pak for Integration 2022.2.1 or 2022.4.1 and don't want to have Zen endpoints, add the following annotation to the metadata section of the CR: 
    metadata:
  annotations:
    apiconnect-operator/cp4i: "false"
  5. Optional: If applicable to your deployment, update the gateway CR file to configure DataPowerService APIs to customize your DataPower deployment. See Customizing a DataPower deployment.
  6. 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.
    Note: In releases previous to 10.0.5.3, this property is called validateApimClient.
  7. Optional: If you want to enable JWT security for communications between the management and gateway, add and set the property jwksUrl. 
    spec:
  ...
  jwksUrl: <JWKS URL>
    where <JWKS URL> is the URL of the JWKS endpoint 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 on JWT security, see Enable JWT security instead of mTLS.
    Datapower version 10.5.0.4 only: To enable JWT on the gateway to analytics communications flow, you also must add a dataPowerOverride section to the gateway CR:
       
spec:
  jwksUrl: <JWKS URL>
  dataPowerOverride:
     image: customregistry.com/custom-image-datapower:10.5.0.5
     version: 10.5.0.5
     license: X-XXXX-XXXXXX
  8. Optional: Update the gateway CR file to 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 yaml file:
    For a DataPower® API Gateway, run the following command:
    oc apply -f apigateway_cr.yaml -n <namespace>
    For a DataPower Gateway (v5 compatible), run the following command:
    oc apply -f v5cgateway_cr.yaml -n <namespace>
  10. To verify that the Gateway subsystem is fully installed, run the following command: 
    oc get GatewayCluster -n <namespace>

    The installation is complete 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
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 next subsystem installation.
  11. Verify that the gateway is ready to be registered with the Management subsystem by calling the health api on the gatewayManagerEndpoint.hosts.name defined in your YAML file: https://gwd.$STACK_HOST/health. 
    curl -k https://gwd.example.com/health
{"status":"ok"}

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.