⚠️ This document is for the Alpha version of Nubus for Kubernetes. Feedback is welcome. ⚠️

Nubus for Kubernetes - Operation Manual 0.5.1 (Alpha)

Installation

3. Installation#

This section describes the installation and deployment of Univention Nubus on a Kubernetes cluster.

Before you begin, make sure you meet the requirements outlined in Requirements. Choose one of the following scenarios:

Depending on the planned scenario, you need information from the cluster operator, such as endpoints to services and the corresponding authentication credentials. Finally, the section Deploying Nubus describes the deployment step by step with the appropriate commands.

3.1. Deploy requirements based on examples included in Nubus#

In this setup, you deploy the requirements for Nubus based on included examples. This setup is good for getting started with Nubus and for demonstration. Nevertheless, you need to ensure that the Certificate manager is in place.

Important

For production use, you need to consider your own concepts for redundancy, failover, and security.

For a production deployment and more information, see Use requirements provided by Kubernetes cluster.

By default, Nubus bundles the following services unless configured otherwise:

  1. S3-compatible object storage with MinIO

  2. Relational database with PostgreSQL for the Notifications API in the Univention Portal, UMC Server, Guardian and Keycloak

  3. Key-value store with Memcached for the UMC Server

Nubus provides a set of default configuration values in the Helm Chart. Copy the example.yaml file from the Helm Chart as shown in Listing 3.5. Customize the following values to your needs:

After you have configured all dependencies, proceed with the steps described in Deploying Nubus.

Note

Nubus comes bundled with a PostgreSQL database management system. The components Notifications API, UMC Server, Guardian, and Keycloak share it. by Keycloak, Guardian, Notifications API, UMC Server and Provisioning. You can configure the services to use an external PostgreSQL database.

Recommendation for a production environment: use a database management system for all services with concepts for redundancy, failover, and more, depending on your needs.

For more information about this use case, see Use requirements provided by Kubernetes cluster.

See also

Nubus for Kubernetes - Architecture Manual

for more information about functional components such as Notifications API, UMC Server, and Keycloak, see Univention Nubus for Kubernetes - Architecture Manual [2].

3.2. Use requirements provided by Kubernetes cluster#

The deployment of the default configuration assumes that your cluster provides the components Nubus depends on as described in Kubernetes cluster.

You may base your configuration on the example.yaml file provided in the Helm Chart. Create the file custom_values.yaml and adjust the values to your needs, as shown in Listing 3.5.

To make Nubus use the existing deployed services from the Kubernetes cluster, adjust your global values in the custom_values.yaml file to use these services. Listing 3.1 shows example values. Ask your cluster operator to provide the required configuration values for these services.

Listing 3.1 Example values for Nubus to use requirements provided by Kubernetes cluster#
global:
  postgresql:
    connection:
      host: ""
      port: ""
  minio:
    connection:
      host: ""
      port: ""
  memcached:
    connection:
      host: ""
    auth:
      username: ""

Nubus comes with provisioning jobs to create the users, databases, and buckets for the services. Nubus has the jobs enabled by default and derives secrets from global.nubusMasterPassword. You can deactivate the provisioning jobs by setting the values from Listing 3.2 in your custom_values.yaml.

Listing 3.2 Deactivate MinIO and PostgreSQL provisioning jobs#
postgresql:
  provisioning:
    enabled: false
minio:
  provisioning:
    enabled: false

If you deactivate the provisioning jobs, you must provide secret names and keys for each service that uses the provided external dependencies. These external dependencies are the following:

S3-compatible object storage

For the S3-compatible object storage, you need endpoint, bucket, access key ID, and secret for the access key ID. Provide this configuration information to the following services:

  • Portal Listener

  • Portal Server

  • Stack Gateway configuration for serving public object storage icons.

Relational database management system

For the relational database management system, you need the connection details, and databases, one for each of the following services:

  • Keycloak

  • Notifications API

  • UMC Server

  • Guardian Management REST API in the Authorization Service

  • Keycloak Extensions for Keycloak in the Identity Provider

For the configuration with PostgreSQL, see Use external PostgreSQL database.

Now you have configured all dependencies, proceed with the steps described in Deploying Nubus.

3.3. Use external PostgreSQL database#

This section describes, how you can use an external PostgreSQL database management system for all services. Use this configuration, if you have a PostgreSQL database cluster already in place, with redundancy and failover mechanisms.

To configure an external PostgreSQL database, you need to provide the connection details in the Helm Chart configuration in your custom_values.yaml file as outlined in Listing 3.3. Replace the following placeholders with your configuration values:

custom-host

The hostname to the external PostgreSQL database management system.

custom-secret

The secret with the passwords for the PostgreSQL service, containing the keys for the passwords.

custom-username

The username for authentication to the PostgreSQL database for the respective service.

custom-administrator-password-key

The password for the administrator to authenticate for the PostgreSQL database.

custom-user-password-key

The password for the user to authenticate for the PostgreSQL database.

custom-replication-password-key

The password for the PostgreSQL replication.

Important

Use a dedicated database per service in the external PostgreSQL database management system. Don’t use the same value for custom-database in the different services, as Listing 3.3 may convey.

Listing 3.3 Content for custom_values.yaml file to configure external PostgreSQL database#
global:
  postgresql:
    connection:
      host: "custom-host"
      port: 5432
postgresql:
  auth:
    existingSecret: "custom-secret"
    username: "custom-username"
    secretKeys:
      adminPasswordKey: "custom-administrator-password-key"
      userPasswordKey: "custom-user-password-key"
      replicationPasswordKey: "custom-replication-password-key"

3.4. 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 custom_values.yaml file as outlined in Listing 3.4. Replace the following placeholders with your configuration values:

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 ldap-server.replicaCountPrimary, ldap-server.replicaCountSecondary, and ldap-server.replicaCountProxy.

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 ldap-server.highAvailabilityMode is set to true.

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 ldap-server.highAvailabilityMode is set to true.

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 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. Listing 3.4 shows an example.

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.

ldap-server.resourcesPrimary#

The resources for the primary instances OpenLDAP service.

ldap-server.resourcesSecondary#

The resources for the secondary instances OpenLDAP service.

ldap-server.resourcesProxy#

The resources for the proxy instances of the OpenLDAP service.

Listing 3.4 Example for custom_values.yaml file to configure the OpenLDAP service#
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

3.5. Deploying Nubus#

This section describes the steps to deploy Nubus on a Kubernetes cluster. Before you can install Nubus, you need to select one of the scenarios mentioned earlier, gather the necessary configuration data, and write your custom_values.yaml file.

Important

Before you begin with the deployment, make sure you have all requirements in place as described in the section Requirements.

  1. Nubus provides a set of default configuration values in the Helm Chart. Fetch the example values file from the following repository with curl:

    Listing 3.5 Download example configuration values for deployment#
    $ export VERSION="0.18.3"
$ curl \
   --output custom_values.yaml \
   https://raw.githubusercontent.com/univention/nubus-stack/v"$VERSION"/helm/nubus/example.yaml

  2. Adjust the configuration values in the custom_values.yaml file depending on your previously chosen scenario.

  3. Install Univention Nubus with Helm:

    Listing 3.6 Install Univention Nubus on a Kubernetes cluster#
    $ export YOUR_NAMESPACE="Set to your Kubernetes namespace"
$ helm upgrade \
   --install nubus \
   --namespace="$YOUR_NAMESPACE" \
   oci://artifacts.software-univention.de/nubus/charts/nubus \
   --values custom_values.yaml \
   --timeout 10m \
   --version "$VERSION"

    Tip

    The installation may take some time depending on your cluster resources, internet connection and other factors. You can verify the status of the deployment with the following command:

    $ kubectl get pods -n <your-namespace>

    The deployment is complete when all pods are in the state Running.

On this page