Installing the portal subsystem

Install the portal subsystem by creating and applying the ingress-ca, common-issuer, and portal_cr yaml files.

Before you begin

Important: When you install the portal subsystem, you must configure the portal 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 <portal namespace>

Create a file called common-issuer.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

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

Confirm that the issuers were created and are in ready state:


oc get issuers -n <portal namespace>
NAME                 READY
ingress-issuer       True
selfsigning-issuer   True

About this task

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

Procedure

Create a file that is called portal_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: portal.apiconnect.ibm.com/v1beta1
kind: PortalCluster
metadata:
  name: portal
  labels:
    app.kubernetes.io/instance: portal
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: portal
  annotations:
    apiconnect-operator/cp4i: "false"
spec:
  version: $APP_PRODUCT_VERSION
  profile: $PROFILE
  mgmtPlatformEndpointCASecret:
    secretName: ingress-ca
  mgmtConsumerEndpointCASecret:
    secretName: ingress-ca
  mgmtPlatformEndpointSvcCASecret:
    secretName: management-ca
  mgmtConsumerEndpointSvcCASecret:
    secretName: management-ca
  portalAdminEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: api.portal.$STACK_HOST
      secretName: portal-admin
  portalUIEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: portal.$STACK_HOST
      secretName: portal-web
  databaseVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 200Gi
  databaseLogsVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 12Gi
  webVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 200Gi
  backupVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 120Gi
  adminVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 20Gi
  certVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 4Gi
  adminClientSubjectDN: CN=portal-admin-client,O=cert-manager
  microServiceSecurity: certManager
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  license:
    accept: $LICENSE_ACCEPTANCE
    use: $LICENSE_USE
    license: '$LICENSE_ID'

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 portal 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 you specify 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, for a subdomain of myhost.subnet.example.com:
  
  portalAdminEndpoint: < ... > hosts: - name: api.portal.myhost.subnet.example.com secret: portal-admin portalUIEndpoint: < ... > hosts: - name: portal.myhost.subnet.example.com secret: portal-web
- Complete hostname customization
  Change both the predefined prefixes and the $STACK_HOST subdomain to match your desired hostnames.
  
  For example, for portalAdminEndpoint, you can replace api.portal.$STACK_HOST with my.api.portal.myhost.subnet.example.com, where my.api.portal replaces api.portal, and myhost.subnet.example.com replaces $STACK_HOST:
  
  portalAdminEndpoint: < ... > hosts: - name: my.api.portal.myhost.subnet.example.com secret: cm-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: oc get sc. For example, for local storage:
```
databaseVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 200Gi
databaseLogsVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 12Gi
webVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 200Gi
backupVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS 
    volumeSize: 300Gi
adminVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 20Gi
certVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 4Gi
```
Note:

The databaseVolumeClaimTemplate has a minimum value of 30Gi. The webVolumeClaimTemplate has a minimum value of 20Gi. The backupVolumeClaimTemplate has a minimum value of 30Gi. However, all three need to be sized according to the installation. For more information on planning your portal PV requirements, see Portal subsystem.

The adminVolumeClaimTemplate and databaseLogsVolumeClaimTemplate in this example have their minimum values and you do not need to change them.

The certVolumeClaimTemplate is used by the nginx pod and in 2DCDR mode it is also by the tunnel, db-remote and www-remote pods. It can be sized small, just like the adminVolumeClaimTemplate, and does not need to be increased based on the number of sites.
$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.
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 you want to disable mTLS for communications between the management and portal, and enable JWT instead, then add and set the properties mtlsValidateClient and jwksUrl.
```
spec:
  ...
  mtlsValidateClient: false
  jwksUrl: <JWKS URL>
```
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.
Install the portal subsystem by applying the modified CR with the following command:
```
oc apply -f portal_cr.yaml -n <namespace>
```
Verify that the portal subsystem is fully installed:
```
oc get PortalCluster -n <namespace>
```
The installation is complete when STATUS reports Running, Ready reports that all services are online (3/3), and MESSAGE reports Ready for API Cloud Manager service registration, for example:
```
NAME           READY   STATUS    VERSION    RECONCILED VERSION   MESSAGE                               AGE
portal         3/3     Running   <version>  <version>            Ready for API Cloud Manager service registration   2h
```
You do not need to wait for the portal installation to complete before you move on to the next subsystem installation.

Verify that you can access the portal web endpoint by browsing to the portalUIEndpoint.hosts.name as configured in your yaml file:

curl -k https://portal.$STACK_HOST
<!DOCTYPE html>
<html>
<head>
<title>Developer Portal is ready to create sites!</title>
<style>
    body {
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
</head>
<body>Developer Portal is ready to create sites!</h1>
<p>If you see this page, the web server is successfully installed and
working. Further configuration is required.</p>
</body>
</html>

It is highly recommend that you retain the portal subsystem encryption secret in a safe location, in case you need to restore the portal subsystem during a disaster recovery scenario.

The encryption secret is created when the portal subsystem is initially deployed. You can obtain the name of the encryption secret from the portal subsystem custom resource after the installation is complete:
1. Obtain the name of the encryptionSecret:
```
oc get ptl portal -o yaml -n <namespace> | grep encryptionSecret
encryptionSecret: portal-enc-key
```
  The name of encryption secret is portal-enc-key.
2. Save the secret yaml in a safe location:
```
oc get secret portal-enc-key -o yaml -n <namespace> > portal-enc-key.yaml
```
Backup the portal installation. See Backing up and restoring the developer portal.

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.