docs/doc/source/security/kubernetes/add-a-trusted-ca.rst
Ron Stone f125a8b892 Remove spurious escapes (r8,dsR8)
This change addresses a long-standing issue in rST documentation imported from XML.
That import process added backslash escapes in front of various characters. The three
most common being '(', ')', and '_'.
These instances are removed.

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: Id43a9337ffcd505ccbdf072d7b29afdb5d2c997e
2023-03-01 11:19:04 +00:00

6.4 KiB
Raw Blame History

System Trusted CA Certificates

also supports the ability to update the trusted 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 .

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

For example, a trusted 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 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 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 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 . 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 certificate(s) to trust. The certificate(s) must be in format and the file may contain one or more certificates.

System CLI Trusted CA certificate install

After installation, adding a trusted to the 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 certificates can be added with single install command by including multiple certificates in the specified file.

The certificate must be in 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 that should be trusted by .

The system will print a list of the certificates that were successfully installed from the file and a list of certificates that were not installed from the 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 Certificate, first list the trusted by running the following command:

~(keystone_admin)]$ system certificate-list

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

Then remove a Trusted Certificate from the list of trusted 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

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.

Update/Renew trusted CA certificates

Warning

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

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

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