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

.. _nubus-ldap-scalability:

Directory service high availability and scalability
===================================================

This section describes, how you can configure the amount of replicas for a highly available and scalable directory service in Nubus.

A highly available, scalable directory service with OpenLDAP consists of the following components:

Providers
   Primary instances of the OpenLDAP service.

Replicas
   Secondary instances of the OpenLDAP service.

Proxies
   Proxy instances of the OpenLDAP service.

The primary instances of the OpenLDAP service are the providers of the service.
They replicate each other.
Anyone of the primary instances handles directory data updates.
One at a time.

The secondary instances of the OpenLDAP service are the replicas of the service.
They replicate the primary instances.
The data of the secondary instances is read-only.
Secondary instances respond to write operations with a referral to a primary instance.

The proxy instances of the OpenLDAP service are the proxies of the service.
They distribute the read operations to the primary and secondary instances.
They also distribute the write operations to a primary instance.

**Recommendation**: all third party services connect to the OpenLDAP service through the proxy instances.

To configure high availability and scalability for the OpenLDAP service,
you need to provide the replica counts in the Helm Chart configuration in your :file:`custom_values.yaml` file
as outlined in :numref:`nubus-ldap-scalability-yaml`.
Replace the following placeholders with your configuration values:

.. envvar:: ldap-server.highAvailabilityMode

   Configures the OpenLDAP service for high availability and scalability.
   Set the value to ``true`` to enable the configuration.
   The value ``true`` is a shortcut for setting the recommended values for
   :envvar:`ldap-server.replicaCountPrimary`, :envvar:`ldap-server.replicaCountSecondary`, and :envvar:`ldap-server.replicaCountProxy`.

.. envvar:: ldap-server.replicaCountPrimary

   Configures the amount of replicas for the primary instances OpenLDAP service.
   The recommended value is ``2``.

   Uses the the recommended value as default value, if :envvar:`ldap-server.highAvailabilityMode` is set to ``true``.

.. envvar:: ldap-server.replicaCountSecondary

   Configures the amount of replicas for the secondary instances OpenLDAP service.
   The recommended values is ``3``.

   Uses the the recommended value as default value, if :envvar:`ldap-server.highAvailabilityMode` is set to ``true``.

.. envvar:: ldap-server.replicaCountProxy

   Configures the amount of replicas for the proxy instances of the OpenLDAP service.
   The recommended value is ``3``.

   Uses the the recommended value as default value, if :envvar:`ldap-server.highAvailabilityMode` is set to ``true``.

To configure the resources for the OpenLDAP service,
you can provide them in the Helm Chart configuration by specifying the following values.
:numref:`nubus-ldap-scalability-yaml` shows an example.

.. envvar:: ldap-server.resources

   The resources for all instances of the OpenLDAP service.
   Use this to set the resources for all instances of the OpenLDAP service to the same values.

.. envvar:: ldap-server.resourcesPrimary

   The resources for the primary instances OpenLDAP service.

.. envvar:: ldap-server.resourcesSecondary

   The resources for the secondary instances OpenLDAP service.

.. envvar:: ldap-server.resourcesProxy

   The resources for the proxy instances of the OpenLDAP service.

.. code-block:: yaml
   :caption: Example for :file:`custom_values.yaml` file to configure the OpenLDAP service
   :name: nubus-ldap-scalability-yaml

   ldap-server:
     highAvailabilityMode: true
     resourcesPrimary:
       limits:
         cpu: 4
         memory: 2048Mi
       requests:
         cpu: 100m
         memory: 512Mi
     resourcesSecondary:
       limits:
         cpu: 4
         memory: 1024Mi
       requests:
         cpu: 100m
         memory: 256Mi
     resourcesProxy:
       limits:
         cpu: 2
         memory: 1024Mi
       requests:
         cpu: 100m
         memory: 256Mi