System Trusted CA Certificates¶

StarlingX also supports the ability to update the trusted CA certificate bundle on all nodes in the system. This is required, for example, when container images are being pulled from an external Docker registry with a certificate signed by a non-well-known CA.

Generally a trusted CA certificate needs to be added if StarlingX clients on the hosts will be connecting to server(s) secured with SSL and whose certificate is signed by an unknown CA.

For example, a trusted CA certificate is required if your Helm charts or yaml manifest files refer to images stored in a Docker registry whose certificate has been signed by an unknown Certificate Authority.

Trusted CA certificates can be added as part of the Ansible Bootstrap Playbook or by using the StarlingX/system REST API or CLI after installation.

Install/Uninstall Trusted CA certificates ¶

Trusted CA certificates can be added as part of the Ansible Bootstrap Playbook or by using the StarlingX/system REST API or CLI after installation.

Ansible Bootstrap Playbook ¶

A trusted CA certificate may need to be specified as an override parameter for the Ansible Bootstrap Playbook. Specifically, if the Docker registries, specified by the bootstrap overrides file, use a certificate signed by an unknown CA. If this is the case then the ssl_ca_cert parameter needs to be specified in the ansible overrides file, /home/sysadmin/localhost.yml, as part of bootstrap in the installation procedure.

For example:

ssl_ca_cert: /path/to/ssl_ca_cert_file

The ssl_ca_cert value is the absolute path of the file containing the CA certificate(s) to trust. The certificate(s) must be in PEM format and the file may contain one or more CA certificates.

System CLI – Trusted CA certificate install ¶

After installation, adding a trusted CA to the StarlingX system may be required. This is the case if images stored in a Docker registry, whose certificate has been signed by a not-well-known Certificate Authority, are referred to by Helm charts and/or yaml manifest files.

Multiple trusted CA certificates can be added with single install command by including multiple CA certificates in the specified PEM file.

The certificate must be in PEM file format.

From the command line, run the certificate-install command.

~(keystone_admin)]$ system certificate-install -m ssl_ca <trusted-ca-bundle-pem-file>

where <trusted-ca-bundle-pem-file> contains 1 or more public certificates of CAs that should be trusted by StarlingX.

The system will print a list of the certificates that were successfully installed from the PEM file and a list of certificates that were not installed from the PEM file due to a certificate error.

For example:

~(keystone_admin)]$ system certificate-install -m ssl_ca ext-registry-ca-certificates.pem

+-------------+------------------------------------------------+
| Property    | Value                                          |
+-------------+------------------------------------------------+
| uuid        | 5f677003-a08a-4725-9082-2b4ea81b33d5           |
| certtype    | ssl_ca                                         |
| signature   | ssl_ca_252107869940582877573916937829152170776 |
| start_date  | 2021-08-17 01:48:21+00:00                      |
| expiry_date | 2021-08-17 02:48:21+00:00                      |
+-------------+------------------------------------------------+
WARNING: Some certificates were not installed.
Error with cert number 2 in the file: certificate is not valid before 2021-08-13 14:00:21 nor after 2021-08-13 15:00:21
Error with cert number 3 in the file: certificate is not valid before 2021-08-13 14:00:21 nor after 2021-08-13 15:00:21
Error with cert number 4 in the file: certificate is not valid before 2018-08-16 20:28:20 nor after 2021-06-05 20:28:20

Note

Installing a new ssl_ca with system certificate-install -m ssl_ca or deleting an old ssl_ca with system certificate-uninstall must be followed by locking and unlocking all controller nodes for the change to take effect.

System CLI – Trusted CA certificate uninstall ¶

To remove a Trusted CA Certificate, first list the trusted CAs by running the following command:

~(keystone_admin)]$ system certificate-list

where, all entries with certtype = ssl_ca are trusted CA certificates.

Then remove a Trusted CA Certificate from the list of trusted CAs by running the following command:

~(keystone_admin)]$ system certificate-uninstall -m ssl_ca <UUID>

where, <UUID> is the UUID of the ssl_ca certtype to be removed.

Note

Update/Renew trusted CA certficates ¶

Warning

System trusted CA certificates can not be auto renewed, as they are not owned by StarlingX.

The administrator should update the trusted CA certificates following the install/uninstall procedure as requested, or when trusted CA certificates in use are approaching expiration.

For example, when the CA certificate signing an external Docker registry’s server certificate needs to be renewed, either because an external Docker registry has a new server certificate signed by a new CA, or the CA certificate signing an external Docker registry’s current server certificate approaching expiration, the administrator can update the CA certificate for the external Docker registry access by uninstalling the old one, and installing the new one.