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

Nubus for Kubernetes - Operation Manual 0.5.5 (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. It’s 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. You don’t have to take of them explicitly, because the Helm Chart and Kubernetes handles the proper setup.

  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.

  4. Message queue with NATS for the Provisioning Service.

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, Provisioning and Keycloak use it for their databases. 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.

3.3.1. Configure external PostgreSQL database#

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 Example for custom_values.yaml file to configure external PostgreSQL database#
global:
  postgresql:
    connection:
      host: "postgres.db.example.com"
      port: 5432
postgresql:
  auth:
    existingSecret: "Your secret"
    username: "Your username"
    secretKeys:
      adminPasswordKey: "Your secret key name for the administrator password."
      userPasswordKey: "Your secret key name for the user password."
      replicationPasswordKey: "Your secret key name for the replication password."

3.3.2. Define custom database names#

The default deployment of Nubus for Kubernetes creates databases with the following names:

  • guardian

  • keycloak

  • keycloak_extensions

  • notificationsapi

  • selfservice

Tip

To lookup the database names in your cluster:

  1. Render the Helm Chart template as described in Rendered template.

  2. Look for the ConfigMap with metadata.name: "release-name-postgresql-provisioning".

  3. You find the list of database names in the ConfigMap data.databases.list.

To define custom database names, add the content from Listing 3.4 to your custom_values.yaml. Replace custom_name_for_* with your respective values for the database name.

Listing 3.4 Define custom database names for PostgreSQL databases used by Nubus#
nubusGuardian:
  postgresql:
    auth:
      database: "custom_name_for_guardian"

keycloak:
  postgresql:
    auth:
      database: "custom_name_for_keycloak"

nubusKeycloakExtensions:
  postgresql:
    auth:
      database: "custom_name_for_keycloak_extensions"

nubusNotificationsApi:
  postgresql:
    auth:
      database: "custom_name_for_notifications_api"

nubusUmcServer:
  postgresql:
    auth:
      database: "custom_name_for_selfservice"

3.4. Configuration#

Besides the external PostgreSQL database, you can configure other aspects for Nubus. See the following list:

If you need any of them, configure them accordingly and come back to perform in deployment of Nubus as described in the next section.

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 and provide, provide the argument for the RELEASE_NAME, and the options for the namespace and the version:

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

    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