Omada Controller Helm Chart

September 9, 2026 · View on GitHub

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:

Controller VersionChart VersionChange Notes
6.3.0.441.5.3Fix Logs Persistent Volume Claim
6.3.0.441.5.2Update to version 6.3.0.45
6.3.0.441.5.1Fix port name upgrade-es-https exceeding Kubernetes' 15 character limit
6.3.0.441.5.0Update to version 6.3.0.44
6.2.14.111.4.2Added env var for UPGRADE_ES_HTTPS_PORT
6.2.14.111.4.1Update to version 6.2.14.11
6.2.10.171.4.0Update to version 6.2.10.17
6.2.0.171.3.0Add javaMaxHeapSize and javaMinHeapSize config options
6.2.0.171.2.0Update to version 6.2.0.17
6.1.0.191.1.6Add upgradeHttps port to service if it doesn't equal the manageHttps port
6.1.0.191.1.5Add webConfigOverride option to force re-read of port configuration
6.1.0.191.1.4Improve secret handling and external MongoDB support
6.1.0.191.1.3Adds the ability to configure an initcontainer
6.1.0.191.1.2Fix #721; duplicate port in values.yaml
6.1.0.191.1.1Auto set MONGO_EXTERNAL=true when MongoDBUrl is set
6.1.0.191.1.0Updated to version 6.1.0.19
6.0.0.251.0.2Added env var for UPGRADE_HTTPS_PORT
6.0.0.251.0.1Updated to version 6.0.0.25
6.0.0.241.0.0Initial version

Installation

Install the chart from OCI registry

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

Install with custom values

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

Install a specific version

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

Uninstallation

helm uninstall omada-controller

Configuration

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

Image Configuration

ParameterDescriptionDefault
image.repositoryOmada Controller image repositorymbentley/omada-controller
image.pullPolicyImage pull policyAlways
image.tagImage tag (defaults to chart appVersion if empty)""
imagePullSecretsImage pull secrets for private registries[]

Service Account

ParameterDescriptionDefault
serviceAccount.createCreate a service accounttrue
serviceAccount.automountAutomount service account tokentrue
serviceAccount.annotationsAnnotations for service account{}
serviceAccount.nameService account name (generated if empty)""

Omada Controller Configuration

ParameterDescriptionDefault
config.ports.manageHttpManagement portal HTTP port8088
config.ports.manageHttpsManagement portal HTTPS port8043
config.ports.portalHttpCaptive portal HTTP port8088
config.ports.portalHttpsCaptive portal HTTPS port8843
config.ports.upgradeHttpsDedicated HTTPS port for upgrades8043
config.ports.appDiscoveryUDP port for Omada App discovery27001
config.ports.adoptV1Device adoption port (v1)29812
config.ports.upgradeV1Device upgrade port (v1)29813
config.ports.managerV1Device management port (v1)29811
config.ports.managerV2Device management port (v2)29814
config.ports.discoveryUDP device discovery port29810
config.ports.udpManagementUDP device management port19810
config.ports.transferV2Device transfer port (v2)29815
config.ports.rttyRTTY connection port29816
config.ports.deviceMonitorDevice monitoring port (Omada 6+)29817
config.webConfigOverrideForce re-read of port configuration from properties on startupfalse
config.rootlessRun controller in rootless modetrue
config.showMongoDBLogsDisplay MongoDB logs (auto-disabled with external MongoDB)false
config.showServerLogsDisplay server logs in container outputtrue
config.sslCertNameSSL certificate filenametls.crt
config.sslKeyNameSSL key filenametls.key
config.tlsSecretNameKubernetes TLS secret name to auto-mount""
config.tls1EnabledRe-enable TLS 1.0 & 1.1false
config.timezoneController timezoneEtc/UTC
config.externalMongoDBUrlExternal MongoDB URL (mutually exclusive with secret)""
config.externalMongoDBUrlSecret.nameSecret name containing MongoDB URI (mutually exclusive with URL)""
config.externalMongoDBUrlSecret.keySecret key containing MongoDB URI""
config.javaMaxHeapSizeReplaces the hardcoded -Xmx in the default CMD (e.g. 512m, 1g); leave empty to use image default of 1024m""
config.javaMinHeapSizeReplaces the hardcoded -Xms in the default CMD (e.g. 64m, 128m); leave empty to use image default of 128m""

Service Configuration

ParameterDescriptionDefault
service.typeKubernetes service typeLoadBalancer
service.labelsAdditional service labels{}
service.annotationsAdditional service annotations{}

Ingress Configuration

ParameterDescriptionDefault
ingress.enabledEnable ingress controllerfalse
ingress.classNameIngress class name""
ingress.annotationsIngress annotations{}
ingress.managementHostsHosts for management portal[]
ingress.portalHostsHosts for captive portal[]
ingress.tlsTLS configuration[]

Persistence Configuration

ParameterDescriptionDefault
persistence.data.enabledEnable data persistencetrue
persistence.data.storageClassNameStorage class for data volume""
persistence.data.accessModesAccess modes for data volume[ReadWriteOnce]
persistence.data.sizeSize of data volume1Gi
persistence.logs.enabledEnable logs persistencetrue
persistence.logs.storageClassNameStorage class for logs volume""
persistence.logs.accessModesAccess modes for logs volume[ReadWriteOnce]
persistence.logs.sizeSize of logs volume1Gi
persistence.extraVolumesAdditional volumes to mount[]
persistence.extraVolumeMountsAdditional volume mounts[]

Resource Management

ParameterDescriptionDefault
resourcesCPU/Memory resource requests/limits{}
nodeSelectorNode selector for pod assignment{}
tolerationsTolerations for pod assignment[]
affinityAffinity rules for pod assignment{}

Health Checks

ParameterDescriptionDefault
livenessProbeLiveness probe configuration{}
readinessProbeReadiness probe configurationSee values.yaml
startupProbeStartup probe configurationSee values.yaml

Additional Configuration

ParameterDescriptionDefault
podAnnotationsPod annotations{}
podLabelsPod labels{}
initContainersInit containers to add to the pod[]
extraEnvVarsAdditional environment variables{}
extraManifestsAdditional Kubernetes manifests[]

Example Configurations

Basic Installation with LoadBalancer

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

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

Installation with Ingress and TLS

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

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:

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

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):

config:
  tlsSecretName: omada-tls-secret

Or with custom certificate/key filenames:

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

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 LoadBalancer service, ensure your load balancer supports both TCP and UDP protocols.

Upgrading

To a newer chart version

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:

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 19810 are accessible from your network. If using a LoadBalancer, 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:

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 Getting Help & Reporting Issues section of the main README for details on how to get support.