cb0245cfab
Modified the note to include <the certificate file> Removed trailing spaces and fixed Patchset 7 comments Updated Patchset 6 comments and removed the word platform Fixed formatting issues Updated Patchset 4 comments Added additional notes in multiple topics listed in the review Updated the Security / Upgrade Guide with a note Change-Id: If0a88e88268b2a4540b6abf97bc7b5ca9049747c Signed-off-by: Juanita Balaraj <juanita.balaraj@windriver.com> Change-Id: I5686cda10f4ac9b184f5ac1e6ceec003b09155d2
116 lines
4.4 KiB
ReStructuredText
116 lines
4.4 KiB
ReStructuredText
|
||
.. imj1570020645091
|
||
.. _kubernetes-root-ca-certificate:
|
||
|
||
=============================================
|
||
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 |prod|’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 :ref:`Create Certificates Locally using openssl
|
||
<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. |org|
|
||
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
|
||
|prod-long| Release |this-ver| 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
|
||
:ref:`Create Certificates Locally using openssl <create-certificates-locally-using-openssl>`.
|
||
|
||
For example:
|
||
|
||
.. code-block:: none
|
||
|
||
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:
|
||
|
||
.. code-block:: none
|
||
|
||
apiserver_cert_sans:
|
||
- hostname.domain
|
||
- 198.51.100.75
|
||
|
||
|prod| 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.
|
||
|
||
|
||
.. _kubernetes-root-ca-certificate-section-g1j-45b-jmb:
|
||
|
||
.. rubric:: |postreq|
|
||
|
||
Make the K8S Root |CA| certificate available to any remote server wanting to
|
||
connect remotely to the |prod|'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 :ref:`2.b
|
||
<security-install-kubectl-and-helm-clients-directly-on-a-host>` in
|
||
*Install Kubectl and Helm Clients Directly on a Host*.
|