Install Custom Kubernetes Root CA Certificate¶
By default, the K8S Root CA certificate and key are auto-generated and result in the other Kubernetes certificates being signed by an internal not well-known CA; for example, for the Kubernetes API server certificate.
It is optional that you update the Kubernetes Root CA with a custom Root CA certificate and key, generated by yourself, and trusted by external servers connecting to the StarlingX’s Kubernetes API endpoint
The installation of the custom Kubernetes Root CA certificate can only be done during system deployment by using bootstrap overrides.
See Create Certificates Locally using openssl for how to create a private Root CA certificate and key.
Caution
The default duration for the generated Kubernetes Root CA certificate is 10 years. Replacing the Root CA certificate is a complex process, so the custom certificate expiry should be set for a long period, if possible. StarlingX recommends setting the Root CA certificate with an expiry of at least 5-10 years.
The administrator can also provide values to add to the Kubernetes API server certificate Subject Alternative Name list using the apiserver_cert_sans override parameter.
Use the bootstrap override values <k8s_root_ca_cert> and <k8s_root_ca_key>, as part of the installation procedure to specify the certificate and key for the Kubernetes Root CA.
<k8s_root_ca_cert>
Specifies the certificate for the Kubernetes Root CA. The <k8s_root_ca_cert> value is the absolute path of the certificate file. The certificate must be in PEM format and the value must be provided as part of a pair with <k8s_root_ca_key>.
<k8s_root_ca_key>
Specifies the key for the Kubernetes Root CA. The <k8s_root_ca_key> value is the absolute path of the certificate file. The certificate must be in PEM format and the value must be provided as part of a pair with <k8s_root_ca_cert>.
Note
Ensure the certificates have RSA key length >= 2048 bits. The
StarlingX Release r9.0 provides a new version of openssl
which
requires a minimum of 2048-bit keys for RSA for better security / encryption
strength.
You can check the key length by running openssl x509 -in <the certificate file> -noout -text
and looking for the “Public-Key” in the output. For more information see
Create Certificates Locally using openssl.
For example:
k8s_root_ca_cert: /home/sysadmin/mystarlingx-k8s-rootca-certificate.pem
k8s_root_ca_key: /home/sysadmin/mystarlingx-k8s-rootca-certificate-key.pem
The playbook will not proceed if only one value is provided.
Caution
The default duration for the generated Kubernetes Root CA certificate is 10 years. Replacing the Root CA certificate is an involved process so the custom certificate expiry should be as long as possible. We recommend ensuring Root CA certificate has an expiry of at least 5-10 years.
The administrator can also provide values to add to the Kubernetes API server certificate Subject Alternative Name list using the <apiserver_cert_sans> override parameter.
apiserver_cert_sans
Specifies a list of Subject Alternative Name entries that will be added to the Kubernetes API server certificate. Each entry in the list must be an IP address or domain name. For example:
apiserver_cert_sans:
- hostname.domain
- 198.51.100.75
StarlingX automatically updates this parameter to include IP records for the OAM floating IP and both OAM unit IP addresses. Any DNS names associated with the OAM floating IP address should be added.
Postrequisites
Make the K8S Root CA certificate available to any remote server wanting to
connect remotely to the StarlingX’s Kubernetes API, e.g. through kubectl
or
Helm. This Kubernetes Root CA certificate should be configured as a trusted
CA on the remote server.
See the step 2.b in Install Kubectl and Helm Clients Directly on a Host.