.. 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*.