.. SPDX-FileCopyrightText: 2024 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _overview-tls:

Transport security with TLS
===========================

This section provides information about transport security with TLS and certificate handling in Nubus for Kubernetes.
Knowing the concept of ingress and how Kubernetes handles certificates is helpful for the understanding.

In general, Nubus follows the concepts regarding TLS as described in the Kubernetes concepts and best practices.
The cluster network within the Nubus for Kubernetes namespace doesn't use transport security.
However, Nubus for Kubernetes exposes HTTP to the outside of the cluster network through Ingress.
Ingress terminates TLS connections to Nubus and routes the HTTP traffic to the appropriate service.
Rules defined on the Ingress resource control the traffic routing.
For more information about the external perspective on the interfaces, refer to :numref:`interfaces-external-perspective`.

.. dropdown:: Information about used notation
   :color: info

   This section uses concepts from the ArchiMate enterprise architecture modeling notation across
   the application and technology layers.

   From the business layer it uses the following concepts:

   * *Business Actor*
   * *Business Role*
   * *Business Service*

   From the application layer it uses the following concepts:

   * *Application Component*
   * *Application Interface*
   * *Application Service*
   * *Data Object*

   From the technology layer it uses the following concepts:

   * *System Software*
   * *Artifact*

   From the relationships it uses the following concepts:

   * *Composition*
   * *Aggregation*
   * *Realization*
   * *Assignment*
   * *Serving*
   * *Access*

   For more information on these ArchiMate concepts,
   refer to the following sections in :cite:t:`uv-architecture`:

   * :external+uv-architecture:ref:`notation-archimate-business-layer`
   * :external+uv-architecture:ref:`notation-archimate-application-layer`
   * :external+uv-architecture:ref:`notation-archimate-technology-layer`
   * :external+uv-architecture:ref:`notation-archimate-relationships`

Nubus doesn't handle certificates.
It delegates this task to a certificate manager.

A *Certificate Authority (CA)* issues certificates.
Such certificate issuers are public or private organizations, for example *Let's Encrypt*.
A certificate manager uses issuers to obtain certificates.
For TLS termination, the ingress resource needs a certificate and an instance
to handle the certificate lifecycle, such as requesting a certificate and ensuring the certificate renewal.
These tasks are the responsibility of a certificate manager, as shown in :numref:`overview-tls-fig`.
Nubus for Kubernetes needs a certificate for the FQDNs of *Keycloak* and of the *Portal Service*.

To deploy Nubus, the cluster operator must provide the name of the certificate issuer
for the Helm custom values file
so that the certificate manager knows which issuer to use to obtain the certificates.
The certificate manager needs a proper configuration of the issuer so that Nubus can use it.

For more information about what certificate manager Nubus requires, see
:external+uv-nubus-kubernetes-operation:ref:`requirements-kubernetes-certificates` in :cite:t:`uv-nubus-kubernetes-operation`.

.. _overview-tls-fig:

.. figure:: /images/Certificate-manager_overview.*
   :target: ../_images/Certificate-manager_overview.svg
   :alt: ArchiMate view showing the certificate manager creating the certificates

   ArchiMate view showing the certificate manager creating the certificates

:numref:`overview-tls-detail-fig` shows the details of the relationship between the certificate manager and Nubus for Kubernetes.
The Nubus for Kubernetes Helm Chart defines the following ingress resources with TLS termination:

* *TLS Termination for Proxy in Keycloak Extensions* for the *Transparent Proxy to Keycloak* interface of the *Keycloak Proxy* of the *Keycloak Extensions*.

* *TLS Termination for Nubus* for the *HTTP to Nubus* interface.

Kubernetes realizes the TLS termination through the defined ingress resources,
visualized through *Ingress resource with TLS definition*.
The TLS termination services use the certificates from the certificate manager.
The application components themselves, such as the transparent proxy to Keycloak or the Portal, don't deal with certificates.
Therefore, they don't need to consider certificate lifecycle tasks.

.. _overview-tls-detail-fig:

.. figure:: /images/Certificate-manager.*
   :target: ../_images/Certificate-manager.svg
   :alt: ArchiMate view showing the certificate manager and its relationship to Nubus for Kubernetes

   ArchiMate view showing the certificate manager and its relationship to Nubus for Kubernetes

.. seealso::

   `Ingress | Kubernetes <https://kubernetes.io/docs/concepts/services-networking/ingress/>`_
      for more information about the Ingress API object.

   `Certificate resource - cert-manager Documentation <https://cert-manager.io/docs/usage/certificate/>`_
      for more information about the *Certificate resource*.