Configure REST API Applications and Web Administration Server certificate

About this task

StarlingX provides support for secure HTTPS external connections used for StarlingX REST API application endpoints (Keystone, Barbican and StarlingX) and the StarlingX web administration server. By default, HTTPS access to StarlingX REST and Web Server endpoints is disabled. They are accessible via HTTP only. To enable secure HTTPS access, an x509 certificate and key must be configured.

You can update the certificate used for HTTPS access at any time.

To configure or update the HTTPS certificate for the StarlingX REST API and Web Server endpoints, create a certificate named system-restapi-gui-certificate in the deployment namespace. The secretName attribute of this certificate’s spec must also be named system-restapi-gui-certificate.

See the example procedure below for creating the certificate for the StarlingX REST API and Web Server endpoints.

Update the following fields:

• The duration and renewBefore dates for the expiry and renewal times you desire. The system will automatically renew and re-install the certificate.

  Note

  The Certificate usage of Cert-manager Documentation (https://cert-manager.io/docs/usage/certificate/) states that one should “Take care when setting the renewBefore field to be very close to the duration as this can lead to a renewal loop, where the Certificate is always in the renewal period.”

  In the light of the statement above, you must not set renewBefore to a value very close to the “duration” value, such as a renewBefore of 29 days and a duration of 30 days. Instead, you could set values such as renewBefore=15 days and duration=30 days to avoid renewal loops.

• The subject fields to identify your particular system.

• The ipAddresses with the OAM Floating IP Address for this system.

• The dnsNames with any FQDN names configured for this system in an external DNS server.

Note

If you plan to use the container-based remote CLIs, due to a limitation in the Python2 SSL certificate validation, the certificate used for the system-restapi-gui-certificate certificate must either have:

• CN=IPADDRESS and SANs=IPADDRESS

or

• CN=FQDN and SANs=FQDN

where IPADDRESS and FQDN are for the OAM Floating IP Address.

Procedure

1. Create the REST API certificate yaml configuration file.

   ~(keystone_admin)]$ cat <<EOF > restapi-certificate.yaml
   ---
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: system-restapi-gui-certificate
     namespace: deployment
   spec:
     secretName: system-restapi-gui-certificate
     issuerRef:
       name: system-local-ca
       kind: ClusterIssuer
     duration: 2160h    # 90 days
     renewBefore: 360h  # 15 days
     commonName:  < oam floating IP Address or FQDN >
     subject:
       organizations:
         - ABC-Company
       organizationalUnits:
         - StarlingX-system-restapi-gui
     ipAddresses:
       -  < oam floating IP address >
     dnsNames:
       - < oam floating FQDN >
   EOF
   

2. Apply the configuration.

   ~(keystone_admin)]$ kubectl apply -f restapi-certificate.yaml
   

3. Verify the configuration.

   ~(keystone_admin)]$ kubectl get certificate system-restapi-gui-certificate -n deployment
   

   If configuration was successful, the certificate’s Ready status will be True.

Results

The REST and Web Server certificate installation is now complete, and Cert-Manager will handle the lifecycle management of the certificate.

Limitations for using IPv6 addresses related to management and OAM networks

Cert-manager accepts only short-hand IPv6 addresses.

Workaround: You must use the following rules when defining IPv6 addresses to be used by Cert-manager.

• all letters must be in lower case

• each group of hexadecimal values must not have any leading 0s (use :12: instead of :0012:)

• the longest sequence of consecutive all-zero fields must be short-handed with ::

• :: must not be used to short-hand an IPv6 address with 7 groups of hexadecimal

  values, use :0: instead of ::

Note

Use the rules above to set the IPv6 address related to the management and OAM network in the Ansible bootstrap overrides file, localhost.yml.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
    name: oidc-auth-apps-certificate
    namespace: test
spec:
    secretName: oidc-auth-apps-certificate
    dnsNames:
    - ahost.com
    ipAddresses:
    - fe80:12:903a:1c1a:e802::11e4
    issuerRef:
        name: cloudplatform-interca-issuer
        kind: Issuer