docs/doc/source/security/kubernetes/https-access-overview.rst

.. ddq1552672412979
.. _https-access-overview:

==========================================
HTTPS and Certificates Management Overview
==========================================

Certificates are required for secure HTTPS access and authentication on |prod|
platform.

This table lists all the platform certificates, and indicates which
certificates are automatically created/renewed by the system versus which
certificates must be manually created/renewed by the system administrator.

Platform certificates that are associated with optional platform components are
only present if the optional platform component is configured (e.g. |OIDC|).

Platform certificates that are associated with Distributed Cloud are only
present on |DC| SystemController systems or |DC| Subclouds.

.. table::
    :widths: auto

    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Certificate / synonyms                                              |  Description                                                                                                                                                       | Auto Created                                                                 | Renewal Status                                                                                           |
    +=====================================================================+==================================================================================================================+=================================================+==============================================================================+==========================================================================================================+
    | **Etcd:**                                                                                                                                                                                                                                                                                                                                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | etcd Root CA certificate                                            |  Certificate that signs etcd server and client certificates, and kube-apiserver etcd client certificates                                                           | Yes                                                                          | NOT AUTO-RENEWED; Default expiry is set at 10 years. When an override is provided, it is recommended to  |
    |                                                                     |                                                                                                                                                                    |                                                                              | to use a CA certificate with a long remaining validity (~5-10 years).                                    |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | etcd server certificate                                             |  Certificate used by etcd server to identify itself over HTTPS. Services such as kube-apiserver that access                                                        | Yes                                                                          | auto-renewed by cron job                                                                                 |
    |                                                                     |  etcd verify this serving certificate with etcd Root |CA| certificate.                                                                                             |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | etcd client certificate                                             |  Certificate used by clients to identify themselves while connecting to etcd by HTTPS                                                                              | Yes                                                                          | auto-renewed by cron job                                                                                 |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kube-apiserver-etcd-client certificate                              |  Certificate used by kube-apiserver to identify itself while connecting to etcd by HTTPS                                                                           | Yes                                                                          | auto-renewed by cron job                                                                                 |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **Kubernetes:**                                                                                                                                                                                                                                                                                                                                                                                                                    |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Kubernetes-root-ca                                                  |  Kubernetes root |CA| certificate used to sign all other K8s server and client certificates. This certificate is automatically generated during bootstrap,         | Yes                                                                          | NOT AUTO-RENEWED; Default expiry is set at 10 years; MUST be renewed via CLI. When an override is        |
    |                                                                     |  with a default expiration period of 10 years. While bootstrap overrides remain supported, their usage is deprecated and will be phased out in future releases.    |                                                                              | provided, it is recommended to to use a CA certificate with a long remaining validity (~5-10 years).     |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Cluster Admin client certificate used by kubectl / admin.conf       |  Client certificate used to access kubernetes-admin credentials for kubernetes API used by kubectl and other python API clients. Its privileges are determined by  | Yes                                                                          | auto-renewed by cron job                                                                                 |
    |                                                                     |  the built-in cluster-admin ClusterRole.                                                                                                                           |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Cluster Super Admin client certificate / super-admin.conf           |  The client certificate provides access to the kubernetes-super-admin credentials—a break-glass superuser group that bypasses the standard authorization layer     | Yes                                                                          | auto-renewed by cron job                                                                                 |
    |                                                                     |  (e.g., RBAC). It is reserved for emergency recovery scenarios, such as when RBAC is misconfigured or non-functional.                                              |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kube-controller-manager client certificate/controller-manager.conf  |  Client certificate used by kube-controller-manager pod to identify itself to kube-apiserver                                                                       | Yes                                                                          | auto-renewed by cron job                                                                                 |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kube-scheduler client certificate / scheduler.conf                  |  Client certificate used by kube-scheduler pod to identify itself to kube-apiserver                                                                                | Yes                                                                          | auto-renewed by cron job                                                                                 |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kube-apiserver certificate                                          |  The certificate is used by the kube-apiserver to authenticate itself internally over HTTPS. Internal clients verify this certificate using the Kubernetes root CA.| Yes                                                                          | auto-renewed by cron job                                                                                 |
    |                                                                     |  For external clients, the ssl(restapi/gui)/system-restapi-gui-certificate is presented to identify the system's kube-apiserver. This approach allows external     |                                                                              |                                                                                                          |
    |                                                                     |  clients to rely solely on the system-local-ca to validate all HTTPS-based endpoints exposed externally.                                                           |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kube-apiserver-kubelet client certificate                           |  Kube-apiserver's client certificate used for communication with kubelet                                                                                           | Yes                                                                          | auto-renewed by cron job                                                                                 |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | kubelet client certificate                                          |  Client certificate used by kubelet to identify itself while connecting to kube-apiserver                                                                          | Yes                                                                          | auto-renewed by kubelet. Feature enabled by default                                                      |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | front-proxy-client                                                  |  Client certificate signed by front-proxy root |CA| certificate. It is used by kube-apiserver/aggregator                                                           | Yes                                                                          | auto-renewed by cron job                                                                                 |
    |                                                                     |  to connect to aggregated apiserver (extension APIserver).                                                                                                         |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | front-proxy-ca                                                      |  The front-proxy Root |CA| certificate                                                                                                                             | Yes                                                                          | NOT AUTO-RENEWED; Default expiry is set at 10 years                                                      |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | |prod|                                                                                                                                                                                                                                                                                                                                                                                                                             |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | system-local-ca                                                     |  The |CA| certificate used to create Cert-Manager ClusterIssuer for signing a variety of StarlingX server certificates.                                            | Yes                                                                          | NOT AUTO-RENEWED. MUST be renewed via CLI. It is recommended to to use a CA certificate with a long      |
    |                                                                     |  For Laboratory environment, K8s Root CA Certificate is used by default. For product environment, the |CA| certificate should be set                               |                                                                              | remaining validity (~5-10 years).                                                                        |
    |                                                                     |  to an Intermediate |CA| Cert/Key that has been signed by an external public Root |CA| at bootstrap through overrides or through the proper update procedure.      |                                                                              |                                                                                                          |
    |                                                                     |  For information on ``system-local-ca``, see :ref:`system-local-ca-issuer-9196c5794834`.                                                                           |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | system-openldap-local-certificate                                   |  Certificate used by OpenLDAP server to identify itself over HTTPS. It is signed by **system-local-ca**. Services such as                                          | Yes                                                                          | auto-renewed by cert-manager, as long as system-local-ca is valid                                        |
    |                                                                     |  |SSH|/|SSSD| that access OpenLDAP verify this serving certificate with **system-local-ca**.                                                                       |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | ssl(restapi/gui)/system-restapi-gui-certificate                     |  Certificate used by |prod| RESTAPI endpoints, GUI (Horizon), and K8s kube-apiserver (to external clients through HAproxy) to identify itself                      | Yes                                                                          | auto-renewed by cert-manager, as long as system-local-ca is valid                                        |
    |                                                                     |  over HTTPS. It is signed by **system-local-ca**. Services such as external RESTAPI clients or external browsers that access |prod| RESTAPI endpoints,             |                                                                              |                                                                                                          |
    |                                                                     |  (i.e. kube-api-server), and / or |prod| GUI (Horizon), verify this serving certificate with **system-local-ca**.                                                  |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | docker_registry/system-registry-local-certificate                   |  Certificate used by Docker distribution server (registry.local ) to identify itself over HTTPS.                                                                   | Yes                                                                          | auto-renewed by cert-manager, as long as system-local-ca is valid                                        |
    |                                                                     |                                                                                                                                                                    |                                                                              |                                                                                                          |
    |                                                                     |  It is signed by **system-local-ca**. Services such as internal and/or external clients of registry                                                                |                                                                              |                                                                                                          |
    |                                                                     |  that access registry.local verify this serving certificate with **system-local-ca**.                                                                              |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **OIDC:**                                                                                                                                                                                                                                                                                                                                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | OIDC Client and Dex Server Certificate/oidc-auth-apps-certificate   |  Certificate used by both the |OIDC| client server and the DEX |OIDC| server to identify themselves over HTTPS.                                                    | No                                                                           | auto-renewed if configured with cert-manager;                                                            |
    |                                                                     |                                                                                                                                                                    |                                                                              | NOT AUTO-RENEWED if configured with an externally generated certificate. MUST be renewed via CLI.        |
    |                                                                     |  It is typically signed by **system-local-ca**. Services such as external clients that access |OIDC| client server/DEX |OIDC| server                               |                                                                              |                                                                                                          |
    |                                                                     |  verify this serving certificate with **system-local-ca**.                                                                                                         |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | OIDC Client and Dex Server CA certificate                           |  The |CA| certificate that signs the |OIDC| client server certificate and the DEX |OIDC| server certificate. In the recommended                                    |  No                                                                          | NOT AUTO-RENEWED. MUST be renewed via CLI.                                                               |
    |                                                                     |  configurations, the |CA| certificate  is **system-local-ca**.                                                                                                     |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | OIDC Remote WAD CA Certificate                                      |  The |CA| certificate that signs the remote Windows Active Directory configured in the ``oidc-auth-apps`` application. The DEX server                              |  No                                                                          | NOT AUTO-RENEWED. MUST be renewed via CLI.                                                               |
    |                                                                     |  uses this |CA| certificate to validate the remote Windows Active Directory's server certificate.                                                                  |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **Vault:**                                                                                                                                                                                                                                                                                                                                                                                                                         |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Vault Server Certificate                                            |  Certificate used by Vault server to identify itself over HTTPS. It is typically signed by **system-local-ca**. Vault RESTAPIs or applications                     | Yes                                                                          | NOT AUTO-RENEWED; MUST be renewed via CLI.                                                               |
    |                                                                     |  using Vault verify this serving certificate with **system-local-ca**.                                                                                             |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Vault Root CA certificate                                           |  The |CA| certificate that signs the Vault Server certificate. In the recommended configurations, the |CA| certificate is **system-local-ca**.                     | Yes                                                                          | NOT AUTO-RENEWED; MUST be renewed via CLI.                                                               |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **Portieris:**                                                                                                                                                                                                                                                                                                                                                                                                                     |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Portieris Server Certificate                                        |  Certificate used by Portieris Admission-Control server to identify itself over HTTPS. It is typically signed by **system-local-ca**.                              | Yes                                                                          | Auto renewed by cert-manager; BUT CUSTOMER MUST restart Portieris after the certificate is renewed       |
    |                                                                     |  The Portieris kubernetes admission webhook, which makes request to Portieris Admission-Control server                                                             |                                                                              |                                                                                                          |
    |                                                                     |  verifies this serving certificate with **system-local-ca**.                                                                                                       |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | Portieris remote registry and notary server CA Certificate          |  The |CA| certificate that signs the Portieris Admission Control server certificate.                                                                               | No                                                                           | NOT AUTO-RENEWED; CUSTOMER MUST renew via CLIs                                                           |
    |                                                                     |  In the recommended configurations, the |CA| certificate is **system-local-ca**.                                                                                   |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **DC Admin Endpoints:**                                                                                                                                                                                                                                                                                                                                                                                                            |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | DC-AdminEp-RootCA / dc-adminep-root-ca-certificate /                |  The |CA| certificate that signs the dc-adminep-certificate. On SystemController, it is called dc-adminep-root-ca-certificate.                                     | Yes                                                                          | auto-renewed by cert-manager                                                                             |
    | sc-adminep-root-ca-certificate                                      |  On subcloud, it is called sc-adminep-root-ca-certificate.                                                                                                         |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | DC-AdminEp-InterCA / <uuid>-adminep-ca-certificate /                |  Each subcloud has its own unique <uuid>-adminep-ca-certificate, issued by the DC-AdminEp-RootCA. However, the sc-adminep-ca-certificate is not utilized by the    | Yes                                                                          | auto-renewed by cert-manager, as long as DC-AdminEp-RootCA is valid                                      |
    | sc-adminep-ca-certificate                                           |  System Controller, which means tools like show-certs.sh and system certificate-list will not display it on the controller. Instead, each subcloud stores a copy   |                                                                              |                                                                                                          |
    |                                                                     |  of its respective certificate locally as sc-adminep-ca-certificate.                                                                                               |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | DC-AdminEp-Server / dc-adminep-certificate / sc-adminep-certificate |  On the System Controller, it is called dc-adminep-certificate and is issued by dc-adminep-root-ca-certificate. On the subcloud, it is called                      | Yes                                                                          | auto-renewed by cert-manager, as long as sc-adminep-ca-certificate is valid                              |
    |                                                                     |  sc-adminep-certificate issued by sc-adminep-certificate.                                                                                                          |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | **System trusted CA Certificates (ssl_ca)**                         |  One or more (typically external) |CA| certificates to identify remote servers. Example: when using an external Container Registry, the certificate of the         |  No                                                                          | NOT AUTO-RENEWED as these are certificates that are not necessarily owned by the platform                |
    |                                                                     |  |CA| that signed the external Container Registry's certificate must be configured to validate the identity of the external Container Registry.                    |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
    | IPsec certificate                                                   |  This certificate is utilized by StrongSwan/IPsec to secure and authenticate data exchanged between nodes across the internal management network. It is signed by  |  Yes                                                                         | IPsec certificate is auto-renewed by cron job, as long as system-local-ca is valid                       |
    |                                                                     |  the system-local-ca and is automatically generated during the initial IPsec authentication process when new nodes are added to the system.                        |                                                                              |                                                                                                          |
    +---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+


Where:

-   Auto created: the certificate is generated during system deployment or
    triggered by certain operations.

-   Renewal Status: whether the certificate is renewed automatically by the system
    when expiry date approaches.

The specific certificates, and details such as expiration date, that are
present on a |prod| system can be displayed with a local script, :command:`sudo
show-certs.sh`, see :ref:`utility-script-to-display-certificates`.

|prod| monitors the installed certificates on the system by raising alarms for
expired certificates and certificates that will expire soon, see
:ref:`alarm-expiring-soon-and-expired-certificates-baf5b8f73009`.

The following sections provide details on managing these certificates:

-   :ref:`starlingx-rest-api-applications-and-the-web-administration-server-deprecated`

-   :ref:`Kubernetes Certificates <kubernetes-certificates-f4196d7cae9c>`

-   :ref:`configure-docker-registry-certificate-after-installation-c519edbfe90a`

-   :ref:`System Trusted CA Certificates <add-a-trusted-ca>`

For further information about certificates expiration date or other certificates
information, see :ref:`Display Certificates Installed on a System <utility-script-to-display-certificates>`.

In addition, |prod| monitors the installed certificates on the system by raising
alarms for expire-soon certificates and for expired certificates on the system,
see :ref:`Expiring-Soon and Expired Certificate Alarms
<alarm-expiring-soon-and-expired-certificates-baf5b8f73009>`.