Configure Docker Registry Certificate¶
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
andrenewBefore
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
withregistry.local
,registry.central
and any FQDN names configured for this system’s OAM Floating IP Address in an external DNS server.
Procedure
Create the Docker certificate yaml configuration file.
~(keystone_admin)]$ cat <<EOF > docker-certificate.yaml --- apiVersion: cert-manager.io/v1 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 subject: organizations: - <customer-org> 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>
Apply the configuration.
~(keystone_admin)]$ kubectl apply -f docker-certificate.yaml
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
.Update the platform’s trusted certificates (i.e.
ssl_ca
) with the Root CA associated withsystem-registry-local-certificate
.See the example below where a Root CA
system-local-ca
was used to sign thesystem-registry-local-certificate
, theca.crt
of thesystem-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.
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 hexadecimalvalues, 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