mbentley/omada-controller-helm

Omada Controller Helm Chart

Helm chart for deploying the TP-Link Omada SDN Controller on Kubernetes.

Prerequisites

• Kubernetes 1.19+
• Helm 3.0+
• PV provisioner support in the underlying infrastructure (for persistent storage)

Chart Versions

The Helm chart releases do not correspond to the controller version so below is a guide to help you find the appropriate Chart version for the version of the controller you wish to run:

Installation

Install the chart from OCI registry

bash
helm install omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm

Install with custom values

bash
helm install omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm -f custom-values.yaml

Install a specific version

bash
helm install omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm --version 1.0.0

Uninstallation

bash
helm uninstall omada-controller

Configuration

The following table lists the configurable parameters of the Omada Controller chart and their default values.

Image Configuration

Service Account

Omada Controller Configuration

Service Configuration

Ingress Configuration

Persistence Configuration

Resource Management

Health Checks

Additional Configuration

Example Configurations

Basic Installation with Load***

yaml
service:
  type: LoadBalancer
  annotations:
    metallb.io/loadBalancerIPs: 192.168.1.20

persistence:
  data:
    size: 5Gi
  logs:
    size: 2Gi

Installation with Ingress and TLS

yaml
service:
  type: ClusterIP

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  managementHosts:
    - host: omada.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: omada-tls-secret
      hosts:
        - omada.example.com

Installation with External MongoDB

yaml
config:
  externalMongoDBUrl: "mongodb://user:password@mongodb.example.com:27017/omada"

persistence:
  data:
    enabled: true # Data storage still required for backups and firmware with external MongoDB
    size: 2Gi
  logs:
    enabled: true
    size: 2Gi

Installation with External MongoDB Using Secret

For better security, store the MongoDB URI in a Kubernetes secret:

bash
# Create a secret with the MongoDB URI
kubectl create secret generic mongodb-uri \
  --from-literal=uri='mongodb://user:password@mongodb.example.com:27017/omada'

yaml
config:
  externalMongoDBUrlSecret:
    name: mongodb-uri
    key: uri

persistence:
  data:
    enabled: true # Data storage still required for backups and firmware with external MongoDB
    size: 2Gi
  logs:
    enabled: true
    size: 2Gi

[!IMPORTANT] externalMongoDBUrlSecret and externalMongoDBUrl are mutually exclusive. Setting both will result in a validation error during deployment.

Installation with Custom TLS Certificates

Using a Kubernetes TLS secret (e.g., from cert-manager):

yaml
config:
  tlsSecretName: omada-tls-secret

Or with custom certificate/key filenames:

yaml
config:
  tlsSecretName: omada-custom-tls
  sslCertName: custom.crt
  sslKeyName: custom.key

[!NOTE] The secret must be of type kubernetes.io/tls or contain keys matching sslCertName and sslKeyName.

Resource-Constrained Installation

yaml
config:
  # Reduce the JVM heap from the default 1024m to fit within the pod memory limit.
  # The replacement is visible in `ps` output alongside the Kubernetes resource limits.
  javaMaxHeapSize: "512m"
  javaMinHeapSize: "128m"

resources:
  limits:
    cpu: 2000m
    memory: 2Gi
  requests:
    cpu: 500m
    memory: 1Gi

persistence:
  data:
    size: 2Gi
  logs:
    size: 500Mi

[!NOTE] MONGOD_EXTRA_ARGS (for tuning the embedded MongoDB WiredTiger cache) is not applicable for the standard Helm chart deployment, which uses external MongoDB and runs in rootless mode. If you are running a non-rootless deployment with embedded MongoDB, you can pass it via extraEnvVars.

Port Requirements

The Omada Controller requires several ports to be accessible for proper operation:

• 8043/TCP - HTTPS management portal and Device Firmware Upgrades (primary interface)
• 8088/TCP - HTTP management portal
• 8843/TCP - HTTPS captive portal
• 27001/UDP - Omada app discovery
• 29810/UDP - Device discovery
• 29811-29817/TCP - Device management, adoption, and monitoring

When using a Load*** service, ensure your load *** supports both TCP and UDP protocols.

Upgrading

To a newer chart version

bash
helm upgrade omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm --version 1.2.0

Upgrading the Application Version

When upgrading to a new version of the Omada Controller application, update the image.tag value:

bash
helm upgrade omada-controller oci://registry-1.docker.io/mbentley/omada-controller-helm \
  --set image.tag=6.0.0.25 \
  --reuse-values

Troubleshooting

Controller Takes Long Time to Start

The Omada Controller can take several minutes to start, especially on first run. The startupProbe is configured with a 5-minute timeout (30 failures × 10 seconds) to accommodate this.

Device Discovery Not Working

Ensure UDP ports 27001, 29810, and *** are accessible from your network. If using a Load***, verify it supports UDP protocols.

TLS/Certificate Issues

If using an Ingress controller, ensure your Ingress controller is configured to communicate with the backend using HTTPS. Example for nginx-ingress:

yaml
ingress:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

MongoDB Connection Issues

Check the logs for MongoDB connection errors. If using external MongoDB, verify the connection URL and credentials.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

See the https://github.com/mbentley/docker-omada-controller?tab=readme-ov-file#getting-help--reporting-issues section of the main README for details on how to get support.