Installing the developer portal subsystem

Install the developer portal subsystem.

About this task

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.

Important:

To enable effective high availability for your portal service, you need a latency that is less than 50 ms between all portal-db pods to avoid the risk of performance degradation. Servers with uniform specifications are required, as any write actions occur at the speed of the slowest portal-db pod, as the write actions are synchronous across the cluster of portal-db pods. It is recommended that there are three servers in each cluster of portal-db pods for the high availability configuration. The three servers can be situated in the same availability zone, or across three availability zones to ensure the best availability. However, you can configure high availability with two availability zones.
The portal does not do certain operations if the free space on certain volumes falls beneath predefined limits. In particular:
The databaseVolumeClaimTemplate needs at least 4GB of free space to create new sites, restore site backups, or upgrade or change the URL of existing sites.

The webVolumeClaimTemplate needs at least 256MB free space to create new sites, restore site backups, or upgrade or change the URL of existing sites.
Ensure that your kernel or Kubernetes node has the value of its inotify watches set high enough so that the Developer Portal can monitor and maintain the files for each Developer Portal site. If set too low, the Developer Portal containers might fail to start or go into a non-ready state when this limit is reached. If you have many Developer Portal sites, or if your sites contain a lot of content, for example, many custom modules and themes, then a larger number of inotify watches are required. You can start with a value of 65,000, but for large deployments, this value might need to go up as high as 1,000,000. The Developer Portal containers take inotify watches only when they need them. The full number is not reserved or held, so it is acceptable to set this value high.
Ensure that your kernel or Kubernetes node has a value of nproc (maximum number of processes) that applies to the user ID of the portal pods that have been assigned, and that it is high enough to allow all of the portal processes to execute. For smaller installations this might be as low as 16384, but for larger installations that have more concurrent web calls, you might need as many as 125205. If the number is too low, you will see errors like "fork: retry: Resource temporarily unavailable" in the portal logs. Note that this value might need to be even higher if other, non-portal, pods are sharing the same user ID.
Ensure that your kernel or Kubernetes node has a value of nofiles (maximum number of open file descriptors) that applies to the user ID of the portal pods that have been assigned, and that it is high enough to allow the portal to open all of the files that it requires. For smaller installations this might be as low as 16384, but for larger installations that have more concurrent web calls and portal web sites, you might need as many as 1048576. If the number is too low, you will see errors like "too many open files" in the portal logs. Note that this value might need to be even higher if other, non-portal, pods are sharing the same user ID.

The portal endpoints values are used when you configure a portal service in the Cloud Manager. See Registering a Portal service.

portalAdminEndpoint - This is the Management Endpoint that is defined in Cloud Manager, which is used for communicating with API Manager.
portalUIEndpoint - This is the portal website URL defined in Cloud Manager. It determines the URL for the site that is created for each catalog. It is used for public access to the portal from a browser.

Important: The endpoints defined here must be the ones used by the Management subsystem when registering the portal, and portal users when accessing portal sites. Do not attempt to proxy these endpoints. You will not be able to register the portal service nor access portal sites using any other endpoint URLs than those defined here.

Procedure

Edit the portal_cr template CR to replace the placeholders with values for your deployment.
$APP_PRODUCT_VERSION
API Connect application version for the subsystems.
```
version: <version_number>
```
Example version number: 10.0.8.2-ifix2
$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.

$SECRET_NAME
Use for image pull.
```
imagePullSecrets:
  - apic-registry-secret
```
$DOCKER_REGISTRY
The host name of the Docker Registry to which you uploaded the installation images. For example:
```
my.docker.registry.domain.example.com.
```
$INGRESS_CLASS

The ingress class that you want the endpoint to use. This property is optional and if not specified, the ingress class with annotation ingressclass.kubernetes.io/is-default-class: true is used. If such an ingress class does not exist in the Kubernetes environment, then nginx is used. If you do set this value, it must refer to a valid ingress class configured in your Kubernetes system.
Note: This property is commented out in the template CR file. If you set this value, make sure to also uncomment it.

$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: kubectl 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: 120Gi
adminVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 20Gi
certVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
    volumeSize: 4Gi
```
$PLATFORM_CA_SECRET
Set to ingress-ca. The $PLATFORM_CA_SECRET contains the CA certificate for the platform REST API endpoint. The portal makes calls to the platform REST API and this property must be set so that the portal can verify the server certificate.
```
mgmtPlatformEndpointCASecret:
  secretName: $PLATFORM_CA_SECRET
```
$CONSUMER_CA_SECRET
Set to ingress-ca. The $CONSUMER_CA_SECRET contains the CA certificate for the consumer REST API endpoint. The portal makes calls to the consumer REST API and this property must be set so that the portal can verify the server certificate.
```
mgmtConsumerEndpointCASecret:
  secretName: $CONSUMER_CA_SECRET
```
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.
Edit the license: setting:
1. Set accept: to true to accept the license. Note that the default value is false. If you do not accept the license, the Operator will not install the subsystem.
2. Set metric: to track your product usage. Enter the unit of measure that is used for your program license:
  - PROCESSOR_VALUE_UNIT - Default value. If you leave the field blank, this value is used.
  - MONTHLY_API_CALL - Applies only to the IBM API Connect Hybrid Entitlement program.
  For information on tracking monthly call volume, see Tracking API volume for auditing and compliance.
3. Set use: to either production or nonproduction, to match the license you purchased.
4. Set license: to the License ID for the version of API Connect that you purchased. See API Connect licenses.
Example entry to accept the license for a production system:
```
  license:
    accept: true
    metric: PROCESSOR_VALUE_UNIT 
    use: production
    license: L-RJON-BZ5LSE
```
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.
Optional: If you want to use the In-cluster inter-subsystem communication feature, then uncomment the mgmtPlatformEndpointSvcCASecret and the mgmtConsumerEndpointSvcCASecret sections, and set the secretName for both:
```
  mgmtPlatformEndpointSvcCASecret:
    secretName: management-ca  # Usually management-ca
  mgmtConsumerEndpointSvcCASecret:
    secretName: management-ca  # Usually management-ca
```
Unless you customized your internal certificates, these secrets are always management-ca.
Optional: If you are installing as part of a two data center disaster recovery set up, complete the steps in Installing a two data center deployment on Kubernetes before you apply the edited file.
Install the portal Custom Resource, replacing <namespace> with the target installation namespace in the Kubernetes cluster:
```
kubectl apply -f portal_cr.yaml -n <namespace>
```
Verify that the portal subsystem is fully installed:
```
kubectl 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.
We 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 once the installation is complete. For example:
1. Obtain the name of the encryptionSecret:
```
kubectl get ptl portal -o yaml | grep encryptionSecret
encryptionSecret: portal-enc-key
```
  The name of encryption secret is portal-enc-key.
2. Save the secret yaml in a safe location:
```
kubectl get secret portal-enc-key -o yaml > portal-enc-key.yaml
```
Backup the portal installation. See Backing up and restoring the developer portal.
Note:
When you create or register a Developer Portal service, the portal subsystem checks that the portal web endpoint is accessible. However sometimes, for example due to the complexity of public and private networks, the endpoint cannot be reached. The following example shows the errors that you might see in the portal-www pod, admin container logs, if the endpoint cannot be reached:
An error occurred contacting the provided portal web endpoint: example.com The provided Portal web endpoint example.com returned HTTP status code 504
In this instance, you can disable the portal web endpoint check so that the Developer Portal service can be created successfully.
To disable the endpoint check, complete the following update:

On Kubernetes, OpenShift, and IBM® Cloud Pak for Integration

Add the following section to the portal custom resource (CR) template:
spec: template: - containers: - env: - name: PORTAL_SKIP_WEB_ENDPOINT_VALIDATION value: "true" name: admin name: www

What to do next

If you are creating a new deployment of API Connect, install other subsystems as needed.

When you completed the installation of all the 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.