Install on Nubus for Kubernetes

3.2. Install on Nubus for Kubernetes#

Provisioning sends selected directory objects from the Directory Service in Nubus to a remote OX App Suite installation. These objects include user accounts, user groups, and resources.

The OX Consumer sends this data through the OX SOAP API. For example, users created in Nubus appear in the OX App Suite address book. Users can also book synchronized resources, such as meeting rooms, in OX App Suite.

For Nubus for Kubernetes, the OX Consumer provides the same functionality for OX App Suite as the OX Connector app provides for the Nubus for UCS appliance. Both use the same business logic.

Before you start, make sure that your environment meets the Kubernetes prerequisites. For details, see Nubus for Kubernetes.

This page covers the following tasks:

  1. Prepare OX App Suite

  2. Install the packaged integration

  3. Create a Provisioning API subscription

  4. Prepare the OX Consumer configuration

  5. Install the OX Consumer

3.2.1. Prepare OX App Suite#

If you don’t have an OX App Suite installation, install it before you continue. Installing OX App Suite is beyond the scope of this manual. For installation resources, see the following links:

OX App Suite 8 Operations Guide

for information about the deployment of OX App Suite 8.

OX App Suite 7

for information about the installation of OX App Suite 7.

Important

Univention doesn’t provide support for the installation of OX App Suite.

3.2.2. Install the packaged integration#

This section shows how to install the packaged integration for OX App Suite in Nubus for Kubernetes. It adds these customizations to Nubus:

  • A Nubus Portal tile for the OX App Suite instance.

  • Management capabilities in the Management UI for the following OX App Suite objects:

    • Access profiles

    • Functional accounts

    • OX contexts

    • OX resources

    • User access to OX App Suite

    • User groups

For details, see Load packaged integrations in Univention Nubus - Customization and Modification Manual [5].

Before you continue, make sure that you know the container image registry and repository name for the packaged integration. For details, see Nubus for Kubernetes.

To install the packaged integration, follow these steps:

  1. Copy the content from nubus-values.yaml to the custom_values.yaml file for your Nubus for Kubernetes installation. Listing 3.3 shows the Helm Chart values to add.

    oxDefaultContext

    Define the number of the first and default context in OX App Suite. You can define the value as an integer, for example 10, or as a string, for example "10".

    oxSystemUserPassword

    Choose a secure password. Use the same password later when you set up LDAP in Open-Xchange.

    portalOxLinkBase

    Define the base URL of your OX App Suite instance. You get this URL after you install OX App Suite. See Prepare OX App Suite.

    To choose an appropriate version number for the packaged integration in the tag attribute, see the tags in the repository.

    Listing 3.3 Helm Chart values for adding the Open-Xchange packaged integration#
    # SPDX-License-Identifier: AGPL-3.0-only
# SPDX-FileCopyrightText: 2025-2026 Univention GmbH

global:
  extensions:
    - name: "ox"
      image:
        registry: "artifacts.software-univention.de"
        repository: "nubus/images/ox-extension"
        tag: "0.41.0"
        imagePullPolicy: "IfNotPresent"

nubusStackDataUms:
  templateContext:
    oxDefaultContext: "<The number of the first and default context in OX App Suite>"
    oxSystemUserPassword: "<Password for the LDAP search user>"
    portalOxLinkBase: "<Base URL to your OX App Suite instance>"

  2. Apply the changes with Helm. Use the command in Listing 3.4.

    Before you run it, replace these placeholders:

    • <NAMESPACE>: Kubernetes namespace of your Nubus installation.

    • <NUBUS_RELEASE_NAME>: Helm Chart release name of your Nubus installation.

    • <NUBUS_VERSION>: Nubus Helm Chart version to install.

    Listing 3.4 Install the Open-Xchange packaged integration#
    $ export NAMESPACE_FOR_NUBUS="<NAMESPACE>"
$ export RELEASE_NAME="<NUBUS_RELEASE_NAME>"
$ export VERSION="<NUBUS_VERSION>"

$ helm upgrade \
   "$RELEASE_NAME" \
   --namespace="$NAMESPACE_FOR_NUBUS" \
   oci://artifacts.software-univention.de/nubus/charts/nubus \
   --values custom_values.yaml \
   --version "$VERSION"

  3. Verify that the Helm upgrade completes successfully and that the packaged integration is available in Nubus for Kubernetes.

3.2.3. Create a Provisioning API subscription#

Create the subscription before the OX Consumer connects to the Provisioning Service.

The subscription gives the OX Consumer access to the Provisioning API. The Provisioning Service sends directory object updates. It also provides the data that you want to provision.

For OX App Suite, the relevant directory objects are user accounts, user groups, and Open-Xchange resources. Examples include meeting rooms and functional mailboxes.

To create the OX Consumer subscription, follow these steps:

  1. Make sure that your local client can reach the Provisioning API.

    If you run the commands outside the cluster, create temporary port forwarding. Use the command in Listing 3.5. Keep it running while you create the subscription.

    Listing 3.5 Forward the Provisioning API to your local client#
    $ export LOCAL_PORT=7777
$ kubectl \
   --namespace "$NAMESPACE_FOR_NUBUS" \
   port-forward \
   services/"$RELEASE_NAME"-provisioning-api \
   "$LOCAL_PORT":80

  2. Get the password for the Provisioning API administrator with the command in Listing 3.6.

    Caution

    Environment variables can expose passwords in shell history, debug output, or process environments. Use this method only on a trusted system.

    Listing 3.6 Retrieve the administrative password for the Provisioning API#
    $ export BASE_URL="http://localhost:7777"
$ export USERNAME="admin"
$ export PASSWORD="$(kubectl \
   --namespace "$NAMESPACE_FOR_NUBUS" \
   get secret \
   nubus-provisioning-api-admin \
   -o json \
   | jq -r ".data.password" \
   | base64 -d)"

  3. Create the provisioning-api.json configuration file for the OX Consumer. Use the content in Listing 3.7.

    Set password to any value. Use the name and password values later for the OX Consumer configuration.

    Listing 3.7 Subscription configuration for the OX Consumer#
    {
  "name": "ox-consumer",
  "realms_topics": [
    {
      "realm": "udm",
      "topic": "groups/group"
    },
    {
      "realm": "udm",
      "topic": "oxmail/accessprofile"
    },
    {
      "realm": "udm",
      "topic": "oxmail/functional_account"
    },
    {
      "realm": "udm",
      "topic": "oxmail/oxcontext"
    },
    {
      "realm": "udm",
      "topic": "oxresources/oxresources"
    },
    {
      "realm": "udm",
      "topic": "users/user"
    }
  ],
  "request_prefill": true,
  "password": "<your desired password>"
}

  4. Send the subscription file to the Provisioning API with the command in Listing 3.8.

    Listing 3.8 Create the subscription for the OX Consumer#
    $ curl \
   --user "$USERNAME":"$PASSWORD" \
   --request POST \
   "$BASE_URL"/v1/subscriptions \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --data @provisioning-api.json

  5. Verify that the subscription exists with the command in Listing 3.9.

    Listing 3.9 Retrieve the list of subscriptions#
    $ curl \
   --user "$USERNAME":"$PASSWORD" \
   --request GET \
   "$BASE_URL"/v1/subscriptions \
   --header "Accept: application/json"

  6. If you created a temporary port forward, stop the kubectl port-forward command in Listing 3.5 after you verify that the subscription exists.

See also

Create subscription

in Univention Nubus - Customization and Modification Manual [5] for information about how to create a subscription in the Provisioning Service using the Provisioning API.

3.2.4. Prepare the OX Consumer configuration#

Prepare the configuration before you install the OX Consumer in a Kubernetes cluster. For the installation step, see Install the OX Consumer. The configuration defines the data source, the Provisioning API, and the data target, your OX App Suite instance.

To prepare the OX Consumer configuration, follow these steps:

  1. Create the ox-consumer-values.yaml values file with the structure in Listing 3.10.

    Listing 3.10 Configuration for the OX Consumer in the values file#
    # SPDX-License-Identifier: AGPL-3.0-only
# SPDX-FileCopyrightText: 2025 Univention GmbH

---
# Configuration for OX CONNECTOR
openXchange:
  # -- OX-Mail-Domain to generate OX-email-addresses
  domainName: null
  auth:
    # -- OX Admin username (the OX Admin can create, modify, delete contexts; has to exist)
    username: "oxadminmaster"
    # -- OX Admin password
    password: null
    existingSecret:
      # -- The name of an existing Secret to use for retrieving the password
      # for the ox admin password.
      #
      # "oxConnector.auth.password" will be ignored if this value is set.
      name: null
      keyMapping:
        # -- The key to retrieve the password from. Setting this value allows to use
        # a key with a different name.
        password: null
  # -- Default timezone for new users
  oxLocalTimezone: "Europe/Berlin"
  # -- Default language for new users
  oxLanguage: "de_DE"
  # -- Default context for users (has to exist)
  oxDefaultContext: "10"
  # -- Default SMTP server for new users (if not set explicitely there)
  oxSmtpServer: null
  # -- Default IMAP server for new users (if not set explicitely there)
  oxImapServer: null
  # -- The server where Open-Xchange is installed
  oxSoapServer: null
  # -- OX Connector log level
  # Chose from "DEBUG", "INFO", "WARNING" and "ERROR".
  logLevel: "INFO"
  # -- SQLAlchemy DB connection URL for the OX connector.
  oxDbConnectionString: null

# Configuration for the communication with the provisioning API.
provisioningApi:
  # -- Connection parameters
  connection:
    # -- The base URL the provisioning API is reachable at. (e.g. "https://provisioning-api")
    baseUrl: ""
  # -- Authentication parameters
  auth:
    # -- The username to authenticate with.
    username: null
    # -- The password to authenticate with.
    password: null
    existingSecret:
      # -- The name of an existing Secret to use for retrieving the password
      # to authenticate with the Provisioning API.
      #
      # "provisioningApi.auth.password" will be ignored if this value is set.
      name: null
      keyMapping:
        # -- The key to retrieve the password from. Setting this value allows to use
        # a key with a different name.
        password: null
  # -- Database resync on first startup only if database is empty.
  resync:
    # -- Enable the database resync on first startup only if database is empty.
    enabled: true
    auth:
      # -- The admin username to authenticate with the Provisioning API
      # for re-creating the ox-connector subscriber.
      username: "admin"
      # -- The admin password to authenticate with the Provisioning API.
      password: null
      existingSecret:
        # -- The name of an existing Secret to use for retrieving the password
        # to authenticate with the Provisioning API.
        #
        # "provisioningApi.resync.auth.password" will be ignored if this value is set.
        name: null
        keyMapping:
          # -- The key to retrieve the password from. Setting this value allows to use
          # a key with a different name.
          password: null
...

  2. Set the required values for the following settings.

    For optional settings and their default values, see Configuration for Nubus for Kubernetes.

    Section openXchange

    openXchange.domainName: The OX mail domain that the connector uses to generate email addresses.

    openXchange.auth.password: OX_MASTER_PASSWORD

    openXchange.oxSmtpServer: OX_SMTP_SERVER

    openXchange.oxImapServer: OX_IMAP_SERVER

    openXchange.oxSoapServer: OX_SOAP_SERVER

    openXchange.oxDbConnectionString: The SQLAlchemy connection string for the database.

    The connection string uses the following pattern:

    postgresql+psycopg2://<DATABASE_USERNAME>:<PASSWORD>@<HOSTNAME>/<DATABASE_NAME>

    Replace <DATABASE_USERNAME>, <PASSWORD>, <HOSTNAME>, and <DATABASE_NAME> with the values for your database connection.

    Section provisioningApi

    provisioningApi.auth.username: The value of the name attribute in Listing 3.7.

    provisioningApi.auth.password: The value of the password attribute in Listing 3.7.

    provisioningApi.connection.baseUrl: The base URL for the Provisioning API in the Provisioning Service.

    The URL points to the Kubernetes service for the Provisioning API.

    Use the following URL format:

    http://release-name-provisioning-api

    Replace release-name with the Helm Chart release name of your Nubus for Kubernetes installation.

    provisioningApi.resync.auth.password: The password for the administrative user of the Provisioning API. Use this setting if you leave provisioningApi.resync.enabled set to true.

    Important

    Nubus for Kubernetes doesn’t expose the Provisioning API outside the cluster for security reasons.

    Tip

    Using existing Kubernetes secrets

    Instead of specifying passwords directly in the values file, you can use existing Kubernetes secrets. Set openXchange.auth.existingSecret.*, provisioningApi.auth.existingSecret.*, and provisioningApi.resync.auth.existingSecret.* to the names of the secrets that contain the credentials.

    When you use existing secrets, the OX Consumer ignores the inline password values.

See also

README file for the OX Consumer

for information about the available Helm Chart values and their default settings.

Access to Provisioning API endpoint

in Univention Nubus - Customization and Modification Manual [5] for information about how to access the Provisioning API inside the Kubernetes cluster.

Engine Configuration - SQLAlchemy 2.0 Documentation

for information about the configuration of database connections.

3.2.5. Install the OX Consumer#

To install the OX Consumer with the configuration in Prepare the OX Consumer configuration, follow these steps:

  1. Select an OX Consumer version from the OX Connector repository tags.

  2. Replace the following placeholders in Listing 3.11:

    • <NAMESPACE>: Kubernetes namespace for the OX Consumer. You may choose the same namespace as your Nubus for Kubernetes deployment.

    • <OX_CONSUMER_RELEASE_NAME>: Helm Chart release name for the OX Consumer.

      Caution

      The release name for the OX Consumer must be different from your Nubus for Kubernetes release name. You risk deleting your Nubus for Kubernetes installation, if you select the same release name.

    • <OX_CONSUMER_VERSION>: OX Consumer Helm Chart version to install.

    Danger

    Use a different Helm release name for the OX Consumer. Don’t reuse the Nubus release name. If both releases use the same name in the same namespace, Helm can delete the existing Nubus for Kubernetes installation.

  3. Install the OX Consumer with the command in Listing 3.11.

    Listing 3.11 Install the OX Consumer with Helm#
    $ export NAMESPACE_FOR_CONSUMER="<NAMESPACE>"
$ export RELEASE_NAME="<OX_CONSUMER_RELEASE_NAME>"
$ export VERSION="<OX_CONSUMER_VERSION>"

$ helm upgrade \
   "$RELEASE_NAME" \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   --install \
   oci://artifacts.software-univention.de/nubus/charts/ox-connector \
   --values ox-consumer-values.yaml \
   --version "$VERSION"

  4. Verify that the Helm release installs successfully and that the OX Consumer workloads are ready.

On this page