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

.. index::
   pair: overview; deployment view

.. _overview-deployment:

Deployment view
===============

This section provides a deployment views for the functional components of Nubus for Kubernetes.

You need to know the concept of pods and jobs in Kubernetes and what a Helm Chart is.
Pods are the smallest deployable units of computing that you can create and manage.
A job creates one or more pods and continues to retry running the pods until a specified number of them successfully ends.

The deployment view of Nubus consists of several figures,
because one single figure would contain too many elements and would be hard to read.
Each component has its own deployment view.
Their common concept is the application component *Univention Nubus for Kubernetes*.

The views follow the same pattern.
A Helm Chart locates in a container registry and references Docker images in a container registry.
Helm Chart and Docker image realize a pod or a job in the Kubernetes cluster.
A pod or a job realizes an *application component* in Nubus.
The realization relationship represents that an element plays a critical role in the creation,
or operation of a more abstract element.
An *application component* belongs to a functional component that's part of Nubus for Kubernetes.

.. index::
   single: kubernetes; Pods
   single: kubernetes; Jobs
   single: kubernetes; Helm

.. seealso::


   `Pods | Kubernetes <https://kubernetes.io/docs/concepts/workloads/pods/>`_
      for more information about pods, what they are and how to work with them.

   `Jobs | Kubernetes <https://kubernetes.io/docs/concepts/workloads/controllers/job/>`_
      for more information about jobs and their role in workload management.

   `Helm | Charts <https://helm.sh/docs/topics/charts/>`_
      for more information about Helm Charts.

.. index::
   pair: notation; ArchiMate

.. 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 application layer it uses the following concepts:

   * *Application Component*
   * *Application Interface*
   * *Application Process*
   * *Application Function*
   * *Data Object*

   From the technology layer it uses the following concepts:

   * *System Software*
   * *Artifact*
   * *Node*

   From the relationships it uses the following concepts:

   * *Composition*
   * *Aggregation*
   * *Realization*
   * *Assignment*
   * *Flow*
   * *Serving*

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

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

.. index::
   single: registry; image
   single: registry; Helm Chart
   see: container registry; registry
   pair: artifacts.software-univention.de; registry
   pair: docker.software-univention.de; registry
   pair: docker.io; registry
   pair: registry.opencode.de; registry

.. _deployment-registries:

Registries for Helm Charts and images
-------------------------------------

:numref:`deployment-registries-fig` shows the container registries
that provide Helm Charts and images for Nubus.

Most Helm Charts come from ``artifacts.software-univention.de`` and
``docker.io``.
Most images come from ``artifacts.software-univention.de`` and ``docker.software-univention.de``, both operated by Univention.
Some artifacts come from ``docker.io``.

The deployment views show which registry provides the respective Helm Charts and images.

When you install Nubus for Kubernetes, Helm loads the Charts and the images from these registry locations.

.. _deployment-registries-fig:

.. figure:: /images/Deployment_Registries.*
   :target: ../_images/Deployment_Registries.svg
   :alt: ArchiMate view of the container registries that Nubus uses
   :width: 650px

   ArchiMate view of the container registries that Nubus uses

.. seealso::

   :external+uv-nubus-kubernetes-operation:ref:`nubus-deployment` in :cite:t:`uv-nubus-kubernetes-operation`
      for more information about requirements and how to install Nubus for Kubernetes.

.. index::
   pair: deployment view; authorization service
   see: guardian; authorization service

.. _deployment-authorization-service:

Authorization Service
---------------------

:numref:`deployment-authorization-service-fig` shows the deployment view for the *Authorization Service*.
For a description of the *Guardian*, refer to
:ref:`overview-components-authorization-service`

Helm Charts
   * ``guardian`` from |uv-artifacts|

Images
   From the registry |uv-docker|:

   #. ``guardian-authorization-api-authorization-api``
   #. ``guardian-management-api-management-api``
   #. ``guardian-management-ui-management-ui``
   #. ``guardian-authorization-api-opa``

   From the registry |opencode|:

   5. ``keycloak-bootstrap``

Jobs:
   ``guardian-provisioning``

Pods
   #. ``guardian-authorization-api``
   #. ``guardian-management-api``
   #. ``guardian-management-ui``
   #. ``guardian-open-policy-agent``

   The pods realize the respective *application components*
   that ultimately make up the *Authorization Service* functional component.

.. _deployment-authorization-service-fig:

.. figure:: /images/Deployment_Authorization_Service.*
   :target: ../_images/Deployment_Authorization_Service.svg
   :alt: ArchiMate view for deployment of functional component Authorization Service

   ArchiMate view for deployment of functional component *Authorization Service*

.. seealso::

   :ref:`interfaces-authorization-service` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`component-authorization-service` in components section
      for information about internal components and behavior.

.. index::
   pair: deployment view; directory manager
   see: UDM; directory manager

.. _deployment-directory-manager:

Directory Manager
-----------------

:numref:`deployment-directory-manager-fig` shows the deployment view for the *Directory Manager*.
For a description of the *Directory Manager*, refer to :ref:`overview-components-directory-manager`.

Helm Charts
   From |uv-artifacts|: ``udm-rest-api``

Images
   From |uv-artifacts|: ``udm-rest-api``

Pods
   ``udm-rest-api``

The pod realizes the *UDM HTTP REST API* application component that makes up the *Directory Manager* functional component.

.. _deployment-directory-manager-fig:

.. figure:: /images/Deployment_Directory_Manager.*
   :target: ../_images/Deployment_Directory_Manager.svg
   :alt: ArchiMate view for deployment of functional component Directory Manager
   :width: 335px

   ArchiMate view for deployment of functional component *Directory Manager*

.. seealso::

   :ref:`interfaces-directory-manager` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`component-directory-manager` in components section
      for information about internal components and behavior.

.. index::
   pair: deployment view; end user self service

.. _deployment-end-user-self-service:

End User Self Service
---------------------

:numref:`deployment-end-user-self-service-fig` shows the deployment view of the *End User Self Service*.
For a description of the *End User Self Service*, refer to
:ref:`overview-components-end-user-self-service`.

Helm Charts
   From |uv-artifacts|: ``self-service-listener``

Images
   From |uv-artifacts|: ``self-service-invitation``

Pods
   ``self-service-listener``

   The pod realizes the *Self Service Consumer* *application component* from the *End User Self Service* functional component.

.. _deployment-end-user-self-service-fig:

.. figure:: /images/Deployment_Self_Service_Consumer.*
   :target: ../_images/Deployment_Self_Service_Consumer.svg
   :width: 360px
   :alt: ArchiMate view for deployment of functional component Self Service

   ArchiMate view for deployment of functional component *Self Service*

.. seealso::

   :ref:`interfaces-identity-provider` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`component-identity-provider` in components section
      for information about internal components and behavior.

.. index::
   pair: deployment view; identity provider
   see: keycloak; identity provider

.. _deployment-identity-provider:

Identity Provider
-----------------

:numref:`deployment-identity-provider-fig` shows the deployment view of the *Identity Provider*.
For a description of the *Identity Provider*, refer to
:ref:`overview-components-identity-provider`.

Helm Charts
   From |uv-artifacts|:

   #. ``keycloak``
   #. ``keycloak-bootstrap``
   #. ``keycloak-extensions``

Images
   From |uv-artifacts|:

   #. ``keycloak-bootstrap``
   #. ``keycloak-handler``
   #. ``keycloak-proxy``

   From |uv-docker|:

   4. ``keycloak-keycloak``

Jobs
   ``keycloak-bootstrap``

Pods
   #. ``keycloak``
   #. ``keycloak-handler``
   #. ``keycloak-proxy``

   The pods realize the respective *application components*
   that ultimately make up the *Identity Provider* functional component.
   The *Keycloak Handler* and the *Keycloak Proxy* aggregate to the *Keycloak Extensions* application component.

.. _deployment-identity-provider-fig:

.. figure:: /images/Deployment_Identity_Provider.*
   :target: ../_images/Deployment_Identity_Provider.svg
   :alt: ArchiMate view for deployment of functional component Identity Provider

   ArchiMate view for deployment of functional component *Identity Provider*

.. seealso::

   :ref:`interfaces-identity-provider` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`component-identity-provider` in components section
      for information about internal components and behavior.

.. index::
   pair: deployment view; identity store and directory service
   see: openldap; identity store and directory service
   see: ldap; identity store and directory service

.. _deployment-identity-store:

Identity Store and Directory Service
------------------------------------

:numref:`deployment-identity-store-fig` shows the deployment view of the *Identity Store and Directory Service*.
For a description of the *Identity Store and Directory Service*, refer to
:ref:`overview-components-identity-store`.

Helm Charts
   From |uv-artifacts|:

   #. ``ldap-notifier``
   #. ``ldap-server``

Images
   From |uv-artifacts|:

   #. ``ldap-notifier``
   #. ``ldap-server``

Pods
   #. ``ldap-notifier``
   #. ``ldap-server-primary``
   #. ``ldap-server-secondary``
   #. ``ldap-server-proxy``

   The pods realize the respective *application components*
   that ultimately make up the *Identity Store and Directory Service* functional component.
   Nubus for Kubernetes launches multiple pods
   for each *LDAP Primary*, each *LDAP Secondary*, and each *LDAP Proxy*.

.. _deployment-identity-store-fig:

.. figure:: /images/Deployment_Identity_Store.*
   :target: ../_images/Deployment_Identity_Store.svg
   :alt: ArchiMate view for deployment of functional component Identity Store and Directory Service

   ArchiMate view for deployment of functional component *Identity Store and Directory Service*

:numref:`deployment-identity-store-stack-data-fig` shows jobs that load data through the *UDM HTTP
REST API* to the *LDAP Server*.

Helm Charts
   From |uv-artifacts|:

   #. ``stack-data-ums``
   #. ``stack-data-swp``

Images
   From |uv-artifacts|: ``data-loader``

Jobs
   #. ``stack-data-ums``
   #. ``stack-data-swp``

.. _deployment-identity-store-stack-data-fig:

.. figure:: /images/Deployment_Stack_Data.*
   :target: ../_images/Deployment_Stack_Data.svg
   :alt: ArchiMate view for deployment of Stack Data

   ArchiMate view for deployment of *Stack Data* to fill the Directory Service with initial data

.. seealso::

   :ref:`interfaces-identity-store` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`component-identity-store-directory-service` in components section
      for information about internal components and behavior.

.. TODO : Add Intercom Service to Deployment view

   .. _deployment-intercom-service:

   Intercom Service
   ----------------

.. index::
   pair: deployment view; management ui
   see: umc; management ui

.. _deployment-management-ui:

Management UI
-------------

:numref:`deployment-management-ui-fig` shows the deployment view of the *Management UI*.
For a description of the *Management UI*, refer to
:ref:`overview-components-management-ui`.

Helm Charts
   From |uv-artifacts|:

   #. ``umc-gateway``
   #. ``umc-server``

Images
   From |uv-artifacts|:

   #. ``umc-gateway``
   #. ``umc-server``

   From |docker|:

   3. ``memcached``

Pods
   #. ``umc-gateway``
   #. ``umc-server``
   #. ``umc-server-memcached``

   The pods realize the respective *application components*
   that ultimately make up the *Management UI* functional component.

.. _deployment-management-ui-fig:

.. figure:: /images/Deployment_Management_UI.*
   :target: ../_images/Deployment_Management_UI.svg
   :alt: ArchiMate view for deployment of functional component Management UI

   ArchiMate view for deployment of functional component *Management UI*

.. index::
   pair: deployment view; portal service
   see: portal; portal service

.. _deployment-portal:

Portal Service
--------------

:numref:`deployment-portal-fig` shows the deployment view of the *Portal Service*.
For a description of the *Portal Service*, refer to
:ref:`overview-components-portal-service`.

Helm Charts
   From |uv-artifacts|:

   #. ``notifications-api``
   #. ``portal-server``
   #. ``portal-frontend``
   #. ``portal-listener``

Images
   From |uv-artifacts|:

   #. ``notifications-api``
   #. ``portal-server``
   #. ``portal-frontend``
   #. ``portal-listener``

Pods
   #. ``notifications-api``
   #. ``portal-server``
   #. ``portal-listener``

   The pods realize the respective *application components*
   that ultimately make up the *Portal Service* functional component.

.. _deployment-portal-fig:

.. figure:: /images/Deployment_Portal.*
   :target: ../_images/Deployment_Portal.svg
   :alt: ArchiMate view for deployment of functional component Portal

   ArchiMate view for deployment of functional component *Portal*

.. index::
   pair: deployment view; provisioning service
   see: provisioning; provisioning service

.. _deployment-provisioning:

Provisioning Service
--------------------

:numref:`deployment-provisioning-fig` shows the deployment view of the *Provisioning Service*.
For a description of the *Provisioning Service*, refer to
:ref:`overview-components-provision-service`.

Helm Charts
   From |uv-artifacts|:

   #. ``udm-listener``
   #. ``provisioning``

Images
   From |uv-artifacts|:

   #. ``provisioning-events-and-consumer-api``
   #. ``provisioning-dispatcher``
   #. ``provisioning-udm-listener``
   #. ``provisioning-prefill``
   #. ``wait-for-dependency``
   #. ``provisioning-udm-transformer``

   From |docker|:

   7. ``nats``
   #. ``nats-server-config-reloader``
   #. ``nats-box``

Jobs
   ``provisioning-register-consumers``

Pods
   #. ``provisioning-api``
   #. ``provisioning-dispatcher``
   #. ``provisioning-listener``
   #. ``provisioning-prefill``
   #. ``provisioning-udm-transformer``
   #. ``provisioning-nats``

   The pods realize the respective *application components*
   that ultimately up the *Povisioning Service* functional component.

.. _deployment-provisioning-fig:

.. figure:: /images/Deployment_Provisioning.*
   :target: ../_images/Deployment_Provisioning.svg
   :alt: ArchiMate view for deployment of functional component Provisioning

   ArchiMate view for deployment of functional component *Provisioning*

.. index::
   pair: deployment view; 2FA helpdesk
   see: 2FA; 2FA helpdesk

.. _deployment-2fa-helpdesk:

2FA Helpdesk
------------

:numref:`deployment-2fa-helpdesk-fig` shows the deployment view of the *2FA Helpdesk*.
For a description of the *2FA Helpdesk*,
refer to :ref:`overview-components-2fa-helpdesk`.

Helm Charts
   From |uv-artifacts|: ``twofa-helpdesk``

Images
   From |uv-artifacts|:

   #. ``keycloak-bootstrap``
   #. ``wait-for-dependency``
   #. ``twofa-helpdesk-backend``
   #. ``twofa-helpdesk-frontend``

Jobs
   ``twofa-helpdesk-provisioning``

Pods
  #. ``twofa-helpdesk-backend``
  #. ``twofa-helpdesk-frontend``

.. _deployment-2fa-helpdesk-fig:

.. figure:: /images/Deployment_2FA_Helpdesk.*
   :target: ../_images/Deployment_2FA_Helpdesk.svg
   :alt: ArchiMate view of 2FA Helpdesk deployment through Nubus for Kubernetes
   :width: 700px

   ArchiMate view of 2FA Helpdesk deployment through Nubus for Kubernetes

.. _deployment-ingress:

Ingress configuration
---------------------

:numref:`deployment-ingress-fig` visualizes the Ingress configuration in Nubus for Kubernetes.
Ingress exposes HTTP and HTTPS routes from outside the Kubernetes cluster to services within the cluster.
It doesn't cover other protocols, such as LDAP.

In the default configuration, Nubus for Kubernetes uses the following subdomains:

* :samp:`id.{global.domain}` subdomain used by the *Transparent Proxy to Keycloak*.
* :samp:`portal.{global.domain}` subdomain used by all other Ingress configurations.

:envvar:`global.domain` refers to the domain setting in the deployment file for Nubus in your
Kubernetes cluster.

The Ingress configurations in Nubus for Kubernetes determine where Kubernetes routes the traffic for which URL path.
For the details of those routes, consult the Nubus Ingress configuration in your cluster.

.. _deployment-ingress-fig:

.. figure:: /images/Deployment_Ingress.*
   :target: ../_images/Deployment_Ingress.svg
   :alt: ArchiMate view for the Ingress configuration

   ArchiMate view for the Ingress configuration


.. seealso::

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

   :envvar:`global.domain`
      for information about this setting,
      see :cite:t:`uv-nubus-kubernetes-operation`.

.. index::
   pair: deployment view; database
   pair: deployment view; sql
   pair: deployment view; postgresql
   pair: sql database; postgresql
   pair: database; sql database
   pair: database; postgresql

.. _deployment-postgresql:

SQL database: PostgreSQL
------------------------

.. important::

   This section is only for your information and applies for Nubus for Kubernetes environments
   that use the PostgreSQL deployment provided by the Nubus Helm Chart
   as described in :external+uv-nubus-kubernetes-operation:ref:`nubus-deployment-all-deps` in
   :cite:t:`uv-nubus-kubernetes-operation`.

   This setup is only for testing purposes.

   ⚠️ **Univention doesn't provide support for the PostgreSQL deployment** within Nubus.

   For a production deployment and more information, see
   :external+uv-nubus-kubernetes-operation:ref:`conf-external-postgresql` in
   :cite:t:`uv-nubus-kubernetes-operation`.

:numref:`deployment-postgresql-fig` shows the deployment view for *SQL Database: PostgreSQL*.

Helm Charts
   From |docker|: ``postgresql``

Images
   From |docker|: ``postgresql``

Pods
   ``postgresql``

   The pod runs a :program:`PostgreSQL` database management system.
   For each application that uses PostgreSQL,
   the deployment setup creates corresponding databases with corresponding database users and credentials.
   The figure shows, which *application component* uses which database,
   and that the *application components* access the database management system through the *TCP to SQL database* interface.

The figure primarily uses structural relationships to show the structure and what goes where.
The *Serving* dependency relationship shows the direct dependencies between the *application components* and the databases.
:numref:`deployment-postgresql-table` shows the direct mappings between databases and *application components*.

.. _deployment-postgresql-fig:

.. figure:: /images/Deployment_Postgresql.*
   :target: ../_images/Deployment_Postgresql.svg
   :alt: ArchiMate view of PostgreSQL deployment through Nubus for Kubernetes

   ArchiMate view of PostgreSQL deployment through Nubus for Kubernetes

.. _deployment-postgresql-table:

.. list-table:: *Application components* using PostgreSQL databases
   :header-rows: 1

   * - Database
     - *Application component*
     - Functional component

   * - *PostgreSQL DB: Notifications API*
     - *Notifications API*
     - *Portal Service*

   * - *PostgreSQL DB: UMC Server*
     - *UMC Server*
     - *Management UI*

   * - *PostgreSQL DB: Keycloak*
     - *Keycloak*
     - *Identity Provider*

   * - *PostgreSQL DB: Keycloak Extensions*
     - *Keycloak Extensions*
     - *Identity Provider*

   * - *PostgreSQL DB: Guardian Management REST API*
     - *Guardian Management REST API*
     - *Authorization Service*


.. |uv-artifacts| replace:: ``artifacts.software-univention.de``
.. |uv-docker| replace:: ``docker.software-univention.de``
.. |docker| replace:: ``docker.io``
.. |opencode| replace:: ``registry.opencode.de``