Full Steam Ahead: How to Install Nubus in Your Local Kubernetes Cluster

Time to set sail: We’re spinning up a local Kubernetes cluster and hoisting the Nubus flag—your very own test environment for centralized Identity & Access Management. Missed part one? That’s where we explained how Kubernetes works and who’s really at the helm inside the cluster.

In the first part of this series, we broke down how Kubernetes works, what it’s responsible for, and who holds the wheel in a modern container fleet. Now it’s time to get hands-on. In this article, we’ll show you how to launch your very own local Kubernetes cluster—no cloud provider, no server rack required.

Together, we’ll set up a test cluster using kind, install an Ingress controller, and finally launch Nubus for Kubernetes—our powerful Open Source solution for managing identities, permissions, and access across your applications.

Before we set sail, let’s make sure your system is ready to go. All you need is a Linux machine with a 64-bit Intel, AMD, or ARM processor. Nothing fancy—any major Linux distribution released in the last five years will do. For this guide, we used Ubuntu 24.04 on an Intel/AMD system, but the setup also works on UCS 5 or inside a virtual machine running on Windows or macOS.

Your system should have at least 6 GB of free RAM and 12 GB of available disk space to keep your local Kubernetes cluster running smoothly.

Note: This setup is for testing purposes only! You’ll be launching a single-node Kubernetes “cluster” on your local machine. Perfect for exploring, but of course not comparable to a high-availability production environment.

Before you take Kubernetes into full production, it’s worth getting your hands dirty first. What’s it like to work with a cluster? How do you deploy, configure, scale, and monitor applications? The good news: you don’t need a data center to find out—a regular notebook is more than enough.

With kind (short for “Kubernetes in Docker”), you can spin up a full Kubernetes cluster right on your local machine. It’s lightweight, fast, and perfect for testing. kind uses Docker containers to simulate one or more Kubernetes nodes, so you can experiment without setting up a cloud or virtual infrastructure.

To get started, you’ll need a few tools installed on your system:

• Docker: the runtime that powers kind‘s containers
• kubectl: the command-line tool for talking to your cluster
• Helm: the package manager for Kubernetes applications
• kind: the tool that creates your local cluster
• jq: a handy CLI tool for working with JSON data

Note: Want to see how to install these tools on Ubuntu or UCS? Check out our step-by-step guide: Install Nubus for Kubernetes on your notebook in 20 minutes.

Source: Univention Help Forum

At first glance, it might seem complex—but the whole setup is actually neatly layered, like a Russian Matryoshka doll. On the outside, you’ve got your physical machine or a virtual one. On top of that runs a Linux operating system. Inside that, Docker spins up a container. And inside that container, kind launches your local Kubernetes cluster. From there, it’s smooth sailing: within the cluster, you can run your own applications—like Nubus, which consists of roughly 25 separate pods (or containers), all working together.

Now that all your tools are in place, it’s time to launch the cluster itself. We’ll use kind to spin up Kubernetes right from the command line—quick and easy. To make sure your applications will be accessible later via your browser, we’ll define port mappings for HTTP and HTTPS up front. Save the following configuration to a file named kind-cluster-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP

This configuration uses the default ports 80 (HTTP) and 443 (HTTPS) on your system. If those ports are already in use—say, by another web server—you’ll run into conflicts. In that case, you can switch to ports like 8000 and 8443, but you’ll also need to set up a reverse proxy like Apache or Nginx to forward requests. That’s also necessary if you want to run multiple Nubus instances in parallel.

For a quick trial run, the default setup will do just fine—just make sure the ports are free. In this guide, we’ll name our cluster nubus, since that’s the application we’re about to deploy. But feel free to pick any name you like.

To launch your cluster, run the following command:

kind create cluster --name nubus --config=kind-cluster-config.yaml

A few moments later, your cluster should be up and running—with access to the usual web ports. You can check its status with:

kubectl cluster-info --context kind-nubus

If everything went smoothly, you’ll see URLs for accessing the Kubernetes API. Congratulations—you now have a fully functional Kubernetes lab right on your laptop. Perfect for experimenting, running your first deployments, and taking Nubus for a test sail.

By default, a Kubernetes cluster runs in isolation—like a ship with no harbor. Nothing is accessible from the outside world. To open applications like Nubus in your browser later on, you’ll need an Ingress controller. It acts as a gatekeeper, making sure incoming traffic (like HTTP or HTTPS requests) gets routed to the right containers inside your cluster.

In our setup, we‘re using the tried-and-tested Nginx Ingress Controller—a reference implementation from the Kubernetes community and fully supported by Nubus. (Important: it’s called ingress-nginx, not nginx-ingress. The similar names can be confusing!) You can install the controller using Helm:

helm upgrade --install ingress-nginx ingress-nginx \
     --repo https://kubernetes.github.io/ingress-nginx \
     --namespace ingress-nginx \
     --create-namespace \
     --version "4.8.0" \
     --set controller.allowSnippetAnnotations=true \
     --set controller.config.hsts=false \
     --set controller.service.enableHttps=false \
     --set controller.hostPort.enabled=true \
     --set controller.service.ports.http=80

After a short moment, a new pod will pop up in your cluster, standing by to handle incoming requests:

kubectl get pods -A

In the output, you’ll see something like this:

NAMESPACE         NAME                       READY STATUS   RESTARTS   AGE
ingress-nginx   ingress-nginx-controller[…]  1/1   Running  0          3m19s
kube-system     coredns-668d6bf9bc-6hwlb     1/1   Running  0          3m41s
# ...

That‘s it—your cluster is now open to the outside world and ready for its first real application: Nubus for Kubernetes.

Now that your local Kubernetes cluster is up and running and reachable from the outside it’s time for the real action: installing Nubus for Kubernetes. First, download the configuration file for Nubus:

export VERSION="1.8.0"
curl --output custom_values.yaml "https://raw.githubusercontent.com/univention/nubus-stack/v${VERSION}/helm/nubus/example.yaml"

You can use the file custom_values.yaml as it is or adjust it to match your environment, such as setting your own baseDn, domainName, and domain. For a first test run, sticking with the default example.com domain is perfectly fine.

Next up, we’ll install Nubus using the so-called umbrella Helm chart. Think of a Helm chart as a blueprint for Kubernetes applications—it describes which services, configurations, and dependencies need to be deployed and how they fit together. The umbrella chart for Nubus bundles all the components—from Keycloak and LDAP to the portal and various APIs—and ensures everything is consistently configured and launched in the correct order.

export VERSION="1.8.0"
export NAMESPACE_FOR_NUBUS=default
export RELEASE_NAME=nubus

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

Depending on your internet connection and disk speed, the installation can take up to ten minutes. Once it’s done, you should see an output like this:

[…]
NAME: nubus
LAST DEPLOYED: Tue Mar 17 17:09:00 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
Thank you for installing nubus.

Once the installation kicks off, Kubernetes gets busy behind the scenes—spinning up a whole crew of services, each running as its own pod inside the cluster. These pods are the operational heart of your Nubus system: Keycloak handles authentication, LDAP manages identities, and various APIs take care of provisioning, self-service, and much more.

You can check the current status of all pods with a quick command:

kubectl get pods
NAME                             READY   STATUS           RESTARTS        AGE
nubus-keycloak-0                 1/1     Running          5 (3m19s ago)   6m55s
nubus-keycloak-bootstrap-[…]     0/1     Completed        0               6m54s
nubus-ldap-notifier-0            0/1     CrashLoopBackOff 3 (31s ago)     6m55s
nubus-ldap-server-primary-0      0/1     Running          0               6m54s
nubus-ldap-server-proxy-[…]      0/1     Init:3/5         0               6m54s
nubus-ldap-server-secondary-0    0/1     Init:4/5         0               6m55s
[…]

Don’t worry if everything doesn’t look shipshape right away: Some services need extra time to initialize or are waiting on other components to come online. It’s perfectly normal for some pods to show Init or even CrashLoopBackOff statuses early on. Kubernetes will keep trying to restart and stabilize them automatically—give it a few minutes, and the system will usually sort itself out.

While your cluster’s crew is still getting fully organized, you can already prepare for your first login. Right after installation, Nubus automatically creates a user called Administrator—fully equipped with all the rights you’ll need to manage the system.

To retrieve the password for this user, run the following command in your terminal:

kubectl -n default get secret nubus-nubus-credentials -o json | jq -r '.data.administrator_password' | base64 -d; echo
b30665941288528735bf8aa04655188c1328509b

If you didn’t customize the nubusMasterPassword value in your custom_values.yaml file, this will be the auto-generated default password. You’ll need it in just a moment when you log into the Nubus dashboard through your browser.

To access Nubus comfortably through your browser, your system needs to know where to find addresses like id.example.com. In a production environment, this would normally be handled by a DNS server. But for our local test setup, there’s a simple shortcut: We’ll just add the necessary names to the /etc/hosts file. Open the file in a text editor and add this line at the end:

127.0.0.1 id.example.com portal.example.com

If you customized the domain names in your custom_values.yaml file, be sure to adjust them here as well.

Now you can open the portals in your browser:

• https://id.example.com – for self-service and authentication
• https://portal.example.com – for accessing the Nubus management dashboard

Since the SSL certificate is self-signed, your browser will warn you about it. No worries, it’s safe to accept the warning and proceed. When prompted to log in, use the Administrator account and the password you retrieved earlier with kubectl.

Even in a well-prepared test environment, things might not always go according to plan—for example, a service might fail to start or get stuck in a CrashLoopBackOff state. Luckily, Kubernetes gives you the tools you need to find out what’s going on under the hood.

To check the logs of a deployment or pod, use this command:

kubectl logs [-f] <object>

The -f flag stands for “follow”, meaning you’ll see new log entries in real time, similar to tail -f. Just replace <object> with the name of the deployment or StatefulSet you want to inspect, for example:

• UDM REST API:
  kubectl logs -f deployments/nubus-udm-rest-api
• Portal Frontend:
  kubectl logs -f deployments/nubus-portal-frontend
• LDAP Server (StatefulSet):
  kubectl logs -f statefulsets/nubus-ldap-server-primary

Tip: Type kubectl logs, then hit the Tab key twice—Kubernetes will auto-suggest available resources you can choose from.

Your test run went smoothly? Great! You can now continue experimenting with Nubus — or clear the decks for a fresh start. If you just want to uninstall Nubus while keeping your Kubernetes cluster intact, simply run helm uninstall nubus. This will remove Nubus, but your cluster will remain up and running, ready for further testing.

If you want to wipe the slate completely clean, you can delete the entire cluster with kind delete clusters nubus. This stops the underlying Docker container and removes all associated volumes, freeing up RAM and disk space.

The Docker image used for the cluster remains on your system—which speeds things up if you want to deploy again later. If you also want to remove the image, list all images with docker images and delete the one for your cluster with docker rmi <IMAGE-ID>.

With this article, you’ve laid the groundwork: your Kubernetes cluster is up and running locally, it’s accessible, and it’s hosting Nubus—a full-fledged IAM solution for containerized environments. But your journey through the world of Kubernetes has only just begun. Now you can take your time to explore Nubus: create users, manage groups, and get comfortable with the admin interface.

Whether you’re planning to use Nubus in a school environment, a government organization, or a data center—your local test cluster is the perfect playground to get started. When you’re ready to set sail for production, be sure to check out the official Nubus for Kubernetes – Operation Manual for everything you need to navigate real-world deployments.