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

.. _overview-scalability:

Scalability
===========

Some components in Nubus for Kubernetes have a stronger need for scalability than others.
In general, scalability is a measure to improve performance for application components
or to provide high availability.
However, not every application component is capable of both
high availability and performance
improvements through scalability,
but rather one or the other.

This section describes which functional components use the workload management capability of Kubernetes.
For the configuration of the component's scalability, refer to
:external+uv-nubus-kubernetes-operation:ref:`conf-scalability`
in :cite:t:`uv-nubus-kubernetes-operation`.

Kubernetes has extensive capabilities to manage workload in a cluster.
Nubus for Kubernetes uses the capabilities to scale the application components properly.
:numref:`scalability-fig`
shows the relationship between the Kubernetes workload management
and the functional components it serves.
In most cases, Nubus uses either a *Deployment* or a *StatefulSet*
for workload management in the Kubernetes pod of the application component.

The later sections take a deeper look into the functional components
and which application components benefit
from the Kubernetes workload management for their scalability.

.. _scalability-fig:

.. figure:: /images/Scalability_overview.*
   :alt: Overview of the scalability architecture in Nubus for Kubernetes
   :target: ../_images/Scalability_overview.svg

   Overview of the scalability architecture in Nubus for Kubernetes

.. seealso::

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability` configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`.

   `Workload Management | Kubernetes <https://kubernetes.io/docs/concepts/workloads/controllers/>`_
      in :cite:t:`kubernetes-docs`
      for information about workload management in Kubernetes.

.. _scalability-identity-provider:

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

:numref:`scalability-identity-provider-fig`
shows that the following application components in the *Identity Provider*
benefit from the workload management:

*Keycloak*
   Scale *Keycloak* scales the *Keycloak* Kubernetes pods
   for a better handling of simultaneous sign-in requests.
   This scaling uses the integrated *Infinispan* feature of Keycloak
   for synchronizing the user sessions between *Keycloak* pods.

   However, *Keycloak* needs a :program:`PostgreSQL` database
   that also needs to sustain the load.
   The scalability of the PostgreSQL database is beyond the scope of this document.

*Keycloak Proxy* in the *Keycloak Extensions*
   If the Nubus for Kubernetes deployment has the *Keycloak Extensions* enabled,
   operators can scale up the *Keycloak Proxy*.

.. _scalability-identity-provider-fig:

.. figure:: /images/Scalability_Identity_Provider.*
   :target: ../_images/Scalability_Identity_Provider.svg
   :alt: Scalability for the Identity Provider
   :width: 650px

   Scalability for the *Identity Provider*

.. seealso::

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

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability-identity-provider` scalability configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`.

   `Infinispan - in-memory distributed database <https://infinispan.org/>`_
      for information about *Infinispan*.

.. _scalability-directory-service:

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

:numref:`scalability-directory-service-fig`
shows that the following application components in the *Identity Store and Directory Service*
benefit from the workload management:

*LDAP Primary*
   Scaling the *LDAP Primary* would accomplish high availability with automatic failover.

*LDAP Secondary*
   Scaling the *LDAP Secondary* allows to deal with many read requests to the *Directory Service*.

*LDAP Proxy*
   Because the *LDAP Proxy* distributes requests between the *LDAP Primary* and the *LDAP Secondary*,
   it suffers from the same kind of load.

.. _scalability-directory-service-fig:

.. figure:: /images/Scalability_Directory_Service.*
   :target: ../_images/Scalability_Directory_Service.svg
   :alt: Scalability for the Identity Store and Directory Service
   :width: 650px

   Scalability for the *Identity Store and Directory Service*

.. seealso::

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

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability-directory-service` scalability configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`.

.. _scalability-directory-manager:

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

:numref:`scalability-directory-manager-fig`
shows that the *UDM HTTP REST API* in the *Directory Manager* benefits from the workload management.

The *UDM HTTP REST API* provides a business layer on top of the *Directory Service*.
In environments with frequent concurrent requests to the *UDM HTTP REST API*,
operators can scale up their Kubernetes pods to parallelize request processing
and evaluation of the business layer.
However, depending on the circumstances,
the increased performance may also require scaling up the number of *LDAP Secondary* pods.
See :ref:`scalability-directory-service`.

Recommendation:
   Operators monitor the load on both the *Directory Manager* pods
   and the *Identity Store and Directory Service* pods
   to determine which of the functional components actually needs up-scaling.

   The answer depends, for example, on the specific *UDM Modules* in use
   and may vary from deployment to deployment.

.. _scalability-directory-manager-fig:

.. figure:: /images/Scalability_Directory_Manager.*
   :target: ../_images/Scalability_Directory_Manager.svg
   :alt: Scalability for the Directory Manager
   :width: 650px

   Scalability for the *Directory Manager*

.. seealso::

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

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability-directory-manager` scalability configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`
      for the scalability configuration.

.. _scalability-management-ui:

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

:numref:`scalability-management-ui-fig`
shows that the following application components in the *Management UI*
benefit from the workload management:

*UMC Server*
   It actively handles requests from the *Management UI*
   and the *End User Self Service*
   and manages the sessions of all active users.

   The *UMC Server* Kubernetes pod is especially in need of system memory to cache the user's
   sessions.
   Scaling up the *UMC Server* can prevent it from running out-of-memory
   when dealing with many simultaneous logins.

*UMC Gateway*
   It only serves the *Management UI* to the users' browsers.

In a high-traffic environment,
it's more important to scale up the *UMC Server* than the *UMC Gateway*.

.. _scalability-management-ui-fig:

.. figure:: /images/Scalability_Management_UI.*
   :target: ../_images/Scalability_Management_UI.svg
   :alt: Scalability for the Management UI
   :width: 650px

   Scalability for the *Management UI*

.. seealso::

   :ref:`component-management-ui` in components section
      for information about internal components and behavior.

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability-management-ui` scalability configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`
      for the scalability configuration.

.. _scalability-portal-service:

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

:numref:`scalability-portal-service-fig`
shows that the following application components in the *Portal Service*
benefit from the workload management:

*Portal Frontend*
   It only serves the Portal in the users' browser.

*Portal Server*
   It actively handles requests from the *Portal Frontend*
   and determines the portal content for each user.

In a high-traffic environment,
it's more significant to scale up the *Portal Server* Kubernetes pod
than the *Portal Frontend* pod.

.. _scalability-portal-service-fig:

.. figure:: /images/Scalability_Portal_Service.*
   :target: ../_images/Scalability_Portal_Service.svg
   :alt: Scalability for the Portal Service
   :width: 650px

   Scalability for the *Portal Service*

.. seealso::

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

   :external+uv-nubus-kubernetes-operation:ref:`conf-scalability-portal-service` scalability configuration in Nubus for Kubernetes
      in :cite:t:`uv-nubus-kubernetes-operation`.