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

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 <portal namespace>
  2. 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
  3. Apply the above yaml file with: oc apply -f common-issuer.yaml -n <portal namespace>
  4. 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

  1. 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"
      }
    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: 15Gi
      databaseLogsVolumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: 6Gi
      webVolumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: 8Gi
      backupVolumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: 15Gi
      adminVolumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: 6Gi
      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'
  2. 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.3

    $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 Planning your deployment topology.

    $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: 120Gi
    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.
    • 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 (two data center disaster recovery) mode it is also used 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.
  3. 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 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.
  4. Install the Portal subsystem by applying the modified CR with the following command:
    oc apply -f portal_cr.yaml -n <namespace>
  5. 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.
  6. 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>
    
  7. 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
  8. Backup the Portal installation. See Backing up and restoring Developer Portal on OpenShift and Cloud Pak for Integration.

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.