Configure Docker Registry Certificate

About this task

The local Docker registry provides secure HTTPS access using the registry API.

About this task

By default, a self-signed server certificate is generated at installation time for the registry API. For more secure access, an intermediate or Root CA-signed server certificate is strongly recommended.

To configure or update the HTTPS certificate for the local Docker registry, create a certificate named system-registry-local-certificate in the deployment namespace. The secretName attribute of this certificate’s spec must also be named system-registry-local-certificate.

See the example procedure below for creating the certificate for the local Docker registry. This example assumes you have configured a system-local-ca ClusterIssuer as described in Create a local CA Issuer.

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 and the MGMT Floating IP address for this system which MUST be specified for this certificate. Use the system addrpool-list command to get the OAM floating IP Address and MGMT floating IP Address for your system.

• The dnsNames with registry.local, registry.central and any FQDN names configured for this system’s OAM Floating IP Address in an external DNS server.

Procedure

1. Create the Docker certificate yaml configuration file.

   ~(keystone_admin)]$ cat <<EOF > docker-certificate.yaml
   ---
   apiVersion: cert-manager.io/v1alpha2
   kind: Certificate
   metadata:
     name: system-registry-local-certificate
     namespace: deployment
   spec:
     secretName: system-registry-local-certificate
     issuerRef:
       name: system-local-ca
       kind: ClusterIssuer
     duration: 2160h    # 90d
     renewBefore: 360h  # 15d
     organization:
       - <Customer org>
     subject:
       organizationalUnits:
         - StarlingX-system-registry-local
     ipAddresses:
       - <OAM_FLOATING_IP>
       - <MGMT_FLOATING_IP>
     dnsNames:
       - registry.local
       - registry.central
       - <external-FQDN-for-OAM-Floating-IP-Address, if applicable>
   

Note

IPv6 addresses ending with double-colon “::” must be included in quotes. For example:

• “2607:f160:10:9249:ce:40a:0:f402::”

• “2607:f160:10:924c:ce:40a::”

1. Apply the configuration.

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

2. Verify the configuration.

   ~(keystone_admin)]$ kubectl get certificate system-registry-local-certificate –n deployment
   

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

3. Update the platform’s trusted certificates (i.e. ssl_ca) with the Root CA associated with system-registry-local-certificate.

   See the example below where a Root CA system-local-ca was used to sign the system-registry-local-certificate, the ca.crt of the system-local-ca SECRET is extracted and added as a trusted CA for StarlingX (i.e. system certificate-install -m ssl_ca).

   ~(keystone_admin)]$ kubectl -n cert-manager get secret system-local-ca -o yaml | fgrep tls.crt | awk '{print $2}' | base64 --decode >> system-local-ca.pem
   ~(keystone_admin)]$ system certificate-install -m ssl_ca system-local-ca.pem
   

Results

The Docker registry certificate installation is now complete, and Cert-Manager will handle the lifecycle management of the certificate.