Nubus for Kubernetes - Operation Manual 1.0.1

Deployment

3. Deployment#

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 dependencies based on examples included in Nubus#

In this setup, you can let the Nubus Helm Chart deploy the dependencies for you based on included examples. It’s good for getting started with Nubus and for demonstration. Nevertheless, you need to validate if you want to use a Certificate manager or provide your own certificates.

Important

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

For a production deployment and more information, see Use dependencies provided in Kubernetes cluster.

By default, Nubus bundles the following services unless configured otherwise. The Helm Chart and Kubernetes handle 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 deployment file from the Helm Chart as shown in Listing 3.6. 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 dependencies provided in 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 dependencies provided in Kubernetes cluster#

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

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

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

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 deployment file.

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

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 deployment file as outlined in Listing 3.3. Use the following configuration values:

global.postgresql.connection.host

The hostname to the external PostgreSQL database management system.

postgresql.enabled

Defines whether Helm deploys the bundled PostgreSQL database, the value true, or use a PostgreSQL database that’s external to Nubus, the value false.

postgresql.auth.existingSecret

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

postgresql.auth.username

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

postgresql.auth.secretKeys.adminPasswordKey

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

postgresql.auth.secretKeys.userPasswordKey

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

postgresql.auth.secretKeys.replicationPasswordKey

The password for the PostgreSQL replication.

Listing 3.3 Example for custom_values.yaml deployment file to configure external PostgreSQL database#
global:
  postgresql:
    connection:
      host: "postgres.db.example.com"
      port: 5432
postgresql:
  enabled: false
  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

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.

Important

You need to follow the lexical structure for identifiers and keywords for PostgreSQL database names. Otherwise, the database setup fails, which has subsequent consequences to the Nubus deployment. Database names are identifiers. See Identifiers and Key Words in PostgreSQL 15.8 Documentation [3].

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"

Tip

To lookup the database names in your cluster:

  1. Render the Helm Chart template as described in Render Helm Chart 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.

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 deployment file.

Important

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

  1. Set environment variables for deployment:

    Listing 3.5 Set environment variables for Univention Nubus deployment#
    $ export NAMESPACE_FOR_NUBUS="Set to your Kubernetes namespace"
$ export RELEASE_NAME="The Helm Chart release name"
$ export VERSION="1.0.0"

  2. 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.6 Download example configuration values for deployment#
    $ curl \
   --output custom_values_examples.yaml \
   https://raw.githubusercontent.com/univention/nubus-stack/v"$VERSION"/helm/nubus/example.yaml

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

  4. 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.7 Install Univention Nubus on a Kubernetes cluster#
    $ helm upgrade \
   --install \
   --namespace="$NAMESPACE_FOR_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 "$NAMESPACE_FOR_NUBUS"

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

On this page