Example Kubernetes Project

The example DirX Directory Kubernetes project is tested and supported only with the minikube Kubernetes distributions using the Docker Container runtime. Therefore, documentation is only provided for this scenario.

The example DirX Directory Kubernetes project is tested and supported only as is. Any Kubernetes configuration changes other than the procedures described in this document are outside the scope of DirX Directory support.

The host machine requires at least 8 GB RAM and 40 GB free disk space to deploy the DirX Directory Kubernetes example project.

To run the example DirX Directory Kubernetes project, the Docker Container runtime must be installed and running on the host machine. Before any of the scenarios described below are executed, the following command must be able to run without errors on the host system:

docker container run --rm hello-world

Installation can be performed based on the distribution’s official documentation or the Docker Engine documentation. See https://docs.docker.com for details.

To run the example DirX Directory Kubernetes project, the host system must have a configured minikube environment as described in the minikube installation instructions (see https://minikube.sigs.k8s.io/docs) and the minikube instance must be running. Use the following command to check it:

minikube status

The default-storageclass and storage-provisioner addons must be enabled. The status of the addons can be verified by executing the following command:

minikube addons list

As in Kubernetes, the example DirX Directory Kubernetes project has a resource called an init container. The database initialization is implemented using this resource instead of the entrypoint-init.d scripts. The init_scripts_config_map.yaml configuration file contains the initialization scripts to be executed before the DirX Directory container starts up. It handles initializing a database file and loading the o=My-Company example database. You can customize the initialize_db.sh script to set the DBAM profile to your requirements.

This configuration file contains the definition of the main stateful set resource. It defines the init container, the container, the container ports used and the mounted volumes. As the stateful set contains the definition of the container in use, the DirX Directory container image version to be used can be specified here. For this, the image property can be set in both the container and the init container definition.

The service.yaml configuration files define the service resources that are used to expose ports. There are multiple service.yaml files, one for each DirX Directory server. You can modify the exposed port numbers in these files.

These configuration files define the persistent volume claims that are used to persist the files used by the DirX Directory service. These files include the database files, log files, audit files, etc. You can adjust the size of the persistent volume claims by setting the storage parameter.

Config maps are used to store the configuration files used by the DirX Directory service. There are several files with this naming structure, containing all configuration files used in a normal DirX Directory installation. You can modify these configuration files according to your requirements.

Kubernetes secrets are used to store sensitive or binary data. In the example DirX Directory Kubernetes project, they are used to store, for example, client certificates, user certificates, the license files, etc. These secrets can be updated according to your requirements.

The .pwd files must be handled specially in secret.yaml configuration files. The DirX Directory services encrypt the .pwd files automatically. However, in Kubernetes, secrets are read-only resources and should not be modified once they are attached to a container. As a result, if the password file is set in the secret.yaml file without encryption, password file encryption will fail and the server will not be able to start. To solve this issue, the example DirX Directory Kubernetes project delivers an executable called dirxencryptpwd that can be used to encrypt the password. All .pwd files must contain the encrypted password.

The first step of executing a containerized application is to get and load the container image. Download the DirX Directory container image from the DirX support portal and then load it to the local registry using the command:

This command adds the dxd:9.7.138 container image to the local registry inside the minikube environment. DirX Directory delivers the container image with only a single label containing the full version.

However, as the DirX Directory container image and the DirX Directory Kubernetes example project configuration files are delivered separately, the example project cannot refer to a specific DirX Directory version. So, in both the container and the init container, the image "dxd" is referred to with the default "latest" tag.

To use a specific image version, you can specify the tag in the image property of the containers and initContainers section of the stateful set.yaml configuration file. Alternatively, you can tag the image with the specific version tag to the default tag, as shown in the following command:

The provided Kubernetes configuration files and the container image make it easy to run the DirX Directory service in the Kubernetes environment with the default My-Company configuration. To start the project:

Here is an example startup command sequence for a DirX Directory service dxd-standalone:

Please note that starting up a pod takes time, so the last command may be repeated several times until the pod comes up, showing a Running status.

The example Kubernetes project uses LoadBalancer Kubernetes resources to expose its ports. By default, these ports are only available inside the minikube environment. To expose these ports to a specified bind address, use the command:

minikube tunnel --bind-address=target_IP

where target_IP is the IP address of the network interface to which the exposed ports should be bound. For example, to make the LDAP ports available outside minikube on the host’s loopback interface, use the command:

You can customize the example Kubernetes project by adjusting the delivered yaml configuration files and then applying the changes with the “apply” command described in the "Starting the Example Project" section.

Please note that the Kubernetes example project is tested and supported only as is. Kubernetes configuration changes other than the changes and procedures described in this document are outside the scope of DirX Directory support.

The DirX Directory container image contains a full Linux installation. All tools and clients are included. You can use these tools by using kubectl’s exec functionality. For example, you can open an interactive shell into the DirX Directory pod with the command:

minikube kubectl — exec -it -n namespace dxd-0 — bash

In the interactive shell, you can manage the DirX Directory service as a normal Linux installation.

DirX Directory instances, if running in a separate namespace, can be deleted with the command:

minikube kubectl — delete ns namespace

Please note that this command will not clean up the persistent volumes. You should remove them manually.

This section describes how to implement a simple supplier-consumer scenario using the example Kubernetes project.

By default, the DirX Directory watchdog (dirxdsas) handles all server crashes. However, the minikube environment does not allow ptrace calls by default, so the watchdog procedure is not allowed to generate core dumps.

To activate automatic core dump collection, install the systemd-coredump package and then disable the watchdog’s core dump handling by setting DIRX_WDOG_CRASH_HANDLER=0 in dirxenv.ini. These settings enable systemd to collect the core dumps.