3.2.3. UDM data loader#

As a developer or DevOps engineer, you need directory objects in the directory service for your packaged integration. If this scenario describes your customization case, then the UDM data loader is for you.

During its initial deployment, Nubus for Kubernetes creates a bunch of directory objects in the directory service. Data in the YAML format describes the wanted state of directory objects. The UDM data loader creates or modifies UDM objects accordingly, which applies business logic in UDM, creates and saves the directory objects.

You can use the same mechanism to add directory objects for your packaged integration. This section describes how you define the data, bundle, and apply it.

Example

For the UDM data loader, see the following implementation example:

UDM data loader in OX Connector

3.2.3.1. Provide data to the loader#

To provide data for the UDM data loader plugin to Nubus for Kubernetes, use the following steps:

Create the YAML files. See Data loader format and its following sections.
Save the YAML files in the directory udm-data-loader in your packaged integration project.
Follow the instructions for building the Docker image in Bundle packaged integrations.
Copy the plugin file to your packaged integration project. For the UDM data loader, the plugin-type is udm-data-loader. See Add plugins.
```
$ export PLUGIN_TYPE="udm-data-loader"
```

3.2.3.2. Data loader format#

The UDM data loader reads the wanted state of directory objects from YAML files and prepares that state by creating or modifying UDM objects. Your packaged integration can contain several YAML files. The data loader reads them in lexical order. For example, you can define groups in one YAML file and then define users in subsequent files to add them to the already defined groups. Listing 3.1 shows an example for the order.

Listing 3.1 Example for YAML files in data loader#

.
├── 01-user-groups.yaml
└── 05-users-to-groups.yaml

Each YAML file consists of several YAML directives separated by ---. Listing 3.2 shows an example of a YAML directive for the UDM data loader. It creates a mail domain object at a defined position using the ldapBaseDn in the directory service with the name of the configured externalMailDomain.

Listing 3.2 Example of a YAML directive for the UDM data loader#

---
action: "create"
module: "mail/domain"
position: "cn=domain,cn=mail,{{ ldapBaseDn }}"
properties:
  name: "{{ externalMailDomain }}"
---

ldapBaseDn and externalMailDomain in the example in Listing 3.2 are template variables, that are placeholders which Helm substitutes with the actual values provided by the operator at deployment time. For information about how to define and use template variables, see Template variables in the data loader.

Each YAML directive contains the following mapping:

action: Type: string. See Actions in the data loader.
module: Type: string. See UDM modules in the data loader.
position: Type: string. Defines the position in the directory service tree. For the LDAP base DN you can use the template variable ldapBaseDn.
properties: Type: mapping of strings.

The properties mapping defines the properties of the UDM object and depends on the UDM module used.

3.2.3.3. Actions in the data loader#

The data loader supports the following actions in the YAML directives:

create

The action creates the UDM object with the properties provided.

For an example, see Listing 3.2.

ensure_list_contains

The action ensures that a list in the given UDM object contains the given list entry.

For an example, see Listing 3.3.

Listing 3.3 Example for ensure_list_contains action#

---
action: ensure_list_contains
module: groups/group
position: cn=Domain Admins,cn=groups,{{ ldapBaseDn }}
policies:
  policies/umc:
    - "cn=default-umc-all,cn=UMC,cn=policies,{{ ldapBaseDn }}"
---

modify

The action modifies the given properties of the particular UDM object.

For an example, see Listing 3.4.

Listing 3.4 Example for modify action#

---
action: "modify"
module: "portals/entry"
position: "cn=login-saml,cn=entry,cn=portals,cn=univention,{{ ldapBaseDn }}"
properties:
  activated: true
---

create_or_modify

The action creates the object, if it doesn’t exist. In case it exists, UDM modifies the object accordingly.

delete_if_exists

The action deletes the object if it exists, otherwise it does nothing.

3.2.3.4. Template variables in the data loader#

Template variables provide the capability to adjust the data for loading into Nubus for Kubernetes depending on their installation environment.

The example in Listing 3.2 uses the template variables ldapBaseDn and externalMailDomain. You can define template variables in your YAML directives in the position and properties mappings using the double curly braces notation {{ variable }}. It’s the Jinja2 notation. You can also use other syntax from Jinja2, for example loops.

Variable declaration

To declare template variables, you as a software developer who creates the packaged integration, pick unique variable names and add it to your YAML directives. For example in Listing 3.2.

Recommendation:: Use a prefix as a namespace to distinguish your variables from template variables in other packaged integrations.

Variable value assignment

To assign values to the variables, you as an operator who updates the Nubus deployment with the packaged integration, assign values to the template variables in your deployment values file, such as custom_values.yaml. Listing 3.5 shows an example for assigning values to template variables.

Listing 3.5 Assign values to template variables in deployment values file#

nubusStackDataUms:
  templateContext:
    externalMailDomain: "<value-for-externalMailDomain>"
    variable2: "<value-for-variable-2"

When an operator activates a packaged integration that uses the UDM data loader, Helm provides a so-called template context to the data loader binary. The template context replaces the variable names with the variable values that the operator assigns in their custom_values.yaml deployment values file.

Tip

Nubus for Kubernetes provides the template variable ldapBaseDn in the template context by default. You don’t have to tell the operator to assign a value to it. The Helm Chart takes care of that template context.

Important

You as a software developer must document the template variables that you define, and communicate them to the operator. The operator can then assign values to the template variables in their custom_values.yaml deployment values file.

3.2.3.5. UDM modules in the data loader#

The data loader supports the following UDM modules in the module mapping of the YAML directive:

container/cn
groups/group
mail/domain
policies/umc
portals/category
portals/entry
portals/portal
settings/extended_attribute
settings/umc_operationset
settings/usertemplate
users/ldap
users/user

Nubus for Kubernetes - Customization and Modification Manual 1.x

UDM data loader

Contents

3.2.3. UDM data loader#

3.2.3.1. Provide data to the loader#

3.2.3.2. Data loader format#

3.2.3.3. Actions in the data loader#

3.2.3.4. Template variables in the data loader#

3.2.3.5. UDM modules in the data loader#