Installing the portal subsystem in a shared namespace

Install the portal subsystem by creating and applying the portal_cr.yaml file.

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
     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'
   

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.9.0

   $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.

3. 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.

4. 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.
5. Install the portal subsystem by applying the modified CR with the following command:

   oc apply -f portal_cr.yaml -n <namespace>

6. 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.
7. 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>
   

8. 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

9. Backup the portal installation. See Backing up and restoring the developer portal.