helm

Kubernetes Deployment Guide

In advanced setups, deploying applications in container orchestrators like Kubernetes is common, even in homelabs to enhance reliability. This guide will walk you through deploying the Omada Controller and MongoDB to Kubernetes using Helm. It will implement the external MongoDB deployment pattern for the Omada Controller.

Below, we’ll use Helm to deploy both MongoDB and Omada Controller. It is assumed that you have a working knowledge of Kubernetes and Helm in order to customize the deployment to your needs.

Prerequisites

• A Kubernetes cluster v1.23+ with a storage class configured
• A working LoadBalancer Service or Ingress Controller configuration for exposing the Omada Controller
• Default Kubernetes config pointing to your cluster
• Helm v3.8.0+ (installed and in PATH)
• Kubectl (installed and in PATH)
• Linux or MacOS as runtime environment (Windows will work but is not tested or documented)
• Cloned this repository to your local machine

Optional

• External Secrets Operator (if you want to fetch secrets from external vault or secrets manager)
• cert-manager (if you want to generate TLS certificates)
• External DNS (if you want to manage DNS records automatically)
• Ingress Controller (if you want to expose Omada via Ingress)
• Reloader Operator (if you want to automatically reload Omada Controller when TLS certificates change)

Note

If you prefer to generate and store the required credentials in a vault, use External Secrets to fetch credentials and generate Kubernetes secret automatically. To do this ensure you have the operator installed and configured. Then deploy the ExternalSecret manifest before proceeding (this would replace the secret creation steps below).

Deploy MongoDB

We use the Bitnami's MongoDB chart. Specific values are required in order for Omada to be able to use the database. This includes specific values for the auth and initdbScripts sections. Other recommended updates include explicitly setting persistence and resource limits configurations.

Currently the Omada Controller supports MongoDB versions 3.0 through 8.0. It is recommended to use the latest MongoDB version supported by Omada or at least a version that is still maintained by MongoDB. The latest version of MongoDB is 8.0 and is supported till October 31, 2029. This chart defaults to the latest version of MongoDB. In the future if a newer MongoDB version is released that is not supported by Omada you maybe required to update the image tag for the MongoDB chart in order to use a version that is supported.

Important

Before proceeding customize the values file with the parameters to meet your needs. No deployment will be exactly the same. Review the official chart documentation for all possible values and configurations you may require.

Let's deploy the chart:

1. Create namespace for MongoDB and Omada Controller

   NAMESPACE="omada"
   
   kubectl create ns $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

2. Create secret for MongoDB

   ROOT_PASS=$(openssl rand -base64 32 | tr -dc 'A-Za-z0-9' | head -c32)
   OMADA_DB_PASS=$(openssl rand -base64 32 | tr -dc 'A-Za-z0-9' | head -c32)
   RS_KEY=$(openssl rand -base64 32 | tr -dc 'A-Za-z0-9' | head -c32)
   
   kubectl create secret generic omada-db-secret \
     --from-literal=mongodb-root-password=$ROOT_PASS \
     --from-literal=mongodb-passwords=$OMADA_DB_PASS \
     --from-literal=mongodb-replica-set-key=$RS_KEY \
     -n $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

3. Deploy MongoDB Helm chart

   helm install omada-db oci://registry-1.docker.io/bitnamicharts/mongodb \
     --namespace $NAMESPACE --wait --timeout 10m \
     -f ./k8s/helm/mongodb/values.yaml

Deploy Omada Controller

This repository now contains a Helm chart for Omada Controller. It will be used to complete the Omada Controller deployment using Helm instead of custom crafted manifests.

Prior to deploying the Omada Controller a decision is required on how to expose it external to Kubernetes. This can be done Kubernetes Ingress or LoadBalancer service. If you choose to use Ingress, you will need to have an Ingress Controller installed and configured. If you choose to use a LoadBalancer service, you will need to have a LoadBalancer Controller installed and configured. If you're in an on-premises or homelab environment, you might need tools like MetalLB or Kube-VIP to route traffic and provide IP addresses for LoadBalancer services.

Further enhancements to accessing the Omada Controller can be made by using cert-manager to create a SSL certificate and ExternalDNS to create an A record for the Omada Controller URL. These are optional and not required for the Omada Controller to function.

In this example we will use a LoadBalancer service type with no extra configurations.

Important

Before proceeding customize the values file with the parameters to meet your needs. Additional values files have been provided to demonstrate using the Ingress and LoadBalancer with ExternalDNS and cert-manager configured. No deployment will be exactly the same.

Let's deploy the chart:

1. Create secret for MongoDB Connection String

   kubectl create secret generic omada-db-uri-secret \
     --from-literal=mongodb-uri="mongodb://omada:${OMADA_DB_PASS}@omada-db-mongodb.${NAMESPACE}.svc.cluster.local:27017/omada?authSource=omada" \
     -n $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

2. Deploy Omada Controller Helm chart

   helm install omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm \
     --namespace $NAMESPACE --wait --timeout 10m \
     -f ./k8s/helm/omada-controller/values.yaml

3. Verify the deployment and all pods are running

   kubectl get pods -n $NAMESPACE

4. Get the LoadBalancer IP address

   kubectl get svc omada-controller -n $NAMESPACE -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

5. Access the Omada Controller web interface

   https://<LoadBalancer IP>:8043

Note

The first time you access the Omada Controller web interface, you will need to accept the self-signed certificate.