Defining multiple portal endpoints for a VMware environment

Multiple public facing endpoints (portal-www) can be defined for the portal subsystem.

About this task

You can override the single endpoint definition for portal-www, and the associated portal-www-ingress TLS certificate, to support multiple portal-www endpoints.

For information about the portal endpoints, see Preparing the portal subsystem for deployment.

The task requires accessing your portal VM and creating Kubernetes secrets. Two methods are available for creating Kubernetes secrets:

The recommended method uses a tool that exists on the portal VM called cert-manager. To use the cert-manager method, skip step 5.
If you do not want to use the cert-manager method, you can create your Kubernetes secrets manually. Follow step 5 instead of steps 3 and 4.

Procedure

Create portal-www endpoint certificates with cert-manager.

Log in to your portal virtual appliance with an SSH client, as apicadm user
```
ssh apicadm@<subsystem hostname>
```
Switch to the root user: sudo -i

Create a file called ingress-issuer.yaml and paste in the following content:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: ingress-ca
spec:
  secretName: ingress-ca
  commonName: "ingress-ca"
  usages:
  - digital signature
  - key encipherment
  - cert sign
  isCA: true
  duration: 87600h # 10 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
  issuerRef:
    name: selfsigning-issuer
    kind: Issuer
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ingress-issuer
spec:
  ca:
    secretName: ingress-ca

Run kubectl apply -f ingress-issuer.yaml.

Keep a copy of the ingress-issuer.yaml file in your project directory, so that it is included in your portal subsystem backups.

Create cert-manager certificate objects for each portal-www endpoint.

Create a file called portal-web-certs.yaml, and paste in a Certificate entry for each portal-www endpoint. In this example, two endpoints are created, so the example file contains two certificates:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  labels:
    app.kubernetes.io/instance: portal
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: web-endpoint
  name: portal-web-host1
  namespace: default
spec:
  dnsNames:
  - <FQDN of portal web endpoint 1>
  duration: 17520h0m0s
  issuerRef:
    group: cert-manager.io
    kind: Issuer
    name: ingress-issuer
  renewBefore: 720h0m0s
  privateKey:
    rotationPolicy: Always
  secretName: portal-web-host1
  usages:
  - digital signature
  - key encipherment
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  labels:
    app.kubernetes.io/instance: portal
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: web-endpoint
  name: portal-web-host2
  namespace: default
spec:
  dnsNames:
  - <FQDN of portal web endpoint 2>
  duration: 17520h0m0s
  issuerRef:
    group: cert-manager.io
    kind: Issuer
    name: ingress-issuer
  renewBefore: 720h0m0s
  privateKey:
    rotationPolicy: Always
  secretName: portal-web-host2
  usages:
  - digital signature
  - key encipherment

---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  labels:
    app.kubernetes.io/instance: portal
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: web-endpoint
  name: portal-web-host3
  namespace: default
spec:
  dnsNames:
  - <FQDN of portal web endpoint 3>
  duration: 17520h0m0s
  issuerRef:
    group: cert-manager.io
    kind: Issuer
    name: ingress-issuer
  renewBefore: 720h0m0s
  privateKey:
    rotationPolicy: Always
  secretName: portal-web-host3
  usages:
  - digital signature
  - key encipherment

Apply the file:
```
kubectl apply -f portal-web-certs.yaml
```
Keep a copy of the portal-web-certs.yaml file in your project directory, so that it is included in your portal subsystem backups.

Create portal-www without cert-manager.

Create Kubernetes secrets with OpenSSL. Follow this step instead of steps 3 and 4.

To create the secrets and certificates for each portal-www endpoint, complete the following steps:

If you are using self-signed certificates, create the TLS secrets for each portal-www endpoint by generating the certificates. The following example shows how to generate certificates for each portal-www endpoint by using OpenSSL:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ptl.host1-tls.key -out ptl.host1-tls.crt -subj "/CN=ptl.host1.example.com"
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ptl.host2-tls.key -out ptl.host2-tls.crt -subj "/CN=ptl.host2.example.com"
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ptl.host3-tls.key -out ptl.host3-tls.crt -subj "/CN=ptl.host3.example.com"

Store the SSL certificates in a secret:

Copy the certificates to the Portal virtual appliance, for example:

scp ptl.host1-tls.key ptl.host1-tls.crt ptl.host2-tls.key ptl.host2-tls.crt ptl.host3-tls.key ptl.host3-tls.crt apicadm@portal-vm-address

Log in to your portal virtual appliance with an SSH client, as apicadm user
Switch to the root user: sudo -i

Create the Kubernetes secrets:

kubectl --kubeconfig /etc/kubernetes/admin.conf create secret tls portal-web-host1 --key ptl.host1-tls.key --cert ptl.host1-tls.crt
kubectl --kubeconfig /etc/kubernetes/admin.conf create secret tls portal-web-host2 --key ptl.host2-tls.key --cert ptl.host2-tls.crt
kubectl --kubeconfig /etc/kubernetes/admin.conf create secret tls portal-web-host3 --key ptl.host3-tls.key --cert ptl.host3-tls.crt

Keep a copy of your certificate files in your project directory, so that they are included in your portal subsystem backups.

Add portal-www endpoints and secrets to your ptl-extra-values.yaml file.

Exit from the portal VM, and in your apicup project directory, create a file called ptl-extra-values.yaml with the content:

spec:
    portalUIEndpoint:
        annotations: # Remove if cert-manager not used
          cert-manager.io/issuer: ingress-issuer # Remove if cert-manager not used
        hosts:
        - name: ptl.host1.example.com
          secretName: portal-web-host1
        - name: ptl.host2.example.com
          secretName: portal-web-host2
        - name: ptl.host3.example.com
          secretName: portal-web-host3

Note: If you followed step 5 and did not use cert-manager to create your secrets, then delete the annotations section, so your ptl-extra-values.yaml contains:

spec:
    portalUIEndpoint:
        hosts:
        - name: ptl.host1.example.com
          secretName: portal-web-host1
        - name: ptl.host2.example.com
          secretName: portal-web-host2
        - name: ptl.host3.example.com
          secretName: portal-web-host3

Run the commands:

apicup subsys set <ptl_subsys> extra-values-file <path-to-ptl-extra-values-yaml-file>

apicup subsys install <ptl_subsys>

SSH back into your portal virtual appliance, and confirm that multiple hosts exist for your ptl-portal-web ingress:

sudo kubectl get ingress
NAME                  HOSTS                                                                ADDRESS   PORTS     AGE
ptl-portal-director   api.ptl.example.com                                                            80, 443   25m
ptl-portal-web        ptl.host1.example.com,ptl.host2.example.com,ptl.host3.example.com              80, 443   25m