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.

Using the file obtained from Extracting the management ingress-ca certificates, run: oc apply -f ingress-ca.yaml -n <gateway namespace>

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

Apply the above yaml file with: oc apply -f common-issuer-and-gateway-certs.yaml -n <gateway namespace>

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

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

Create the gateway admin secret with: oc -n <gateway namespace> create secret generic admin-secret --from-literal=password=admin

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
  annotations:
    apiconnect-operator/cp4i: "false"
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
  mtlsValidateClient: true
  # 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
  mtlsValidateClient: true
  # 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

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.8.1
$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 Deployment and component profiles.

$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 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 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.
Optional: If Cloud Pak for Integration is installed, and you want your API Connect installation to be integrated with it, then set metadata.annotations.apiconnect-operator/cp4i to true.

This annotation enables integration with Cloud Pak for Integration.
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.
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.
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.
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>
```
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.
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.