Kubernetes
Overview
The openmediavault-k8s plugin adds a Kubernetes service to openmediavault, providing a user-friendly interface to deploy and manage containerized applications in a cluster environment. The lightweight K3s is used under the hood, allowing a Kubernetes environment to run on SBC systems as well.
After installation, the service is available in the navigation menu under Services | Kubernetes.
The installed applications can then be accessed via the URL:
https://<APPNAME>.<FQDN>:8443
Example:
https://whoami.mynas.internal:8443
Note
It is important that the local DNS server/router can resolve these hostnames.
Networking and DNS
By default, the Traefik reverse proxy in the openmediavault Kubernetes plugin uses
subdomain-based URLs in the form http://<APPNAME>.<FQDN>:8080 or
https://<APPNAME>.<FQDN>:8443.
If local DNS cannot resolve these names, an alternative is to use sslip.io, which is a public DNS service that maps hostnames containing an IP address directly to that IP. This is useful when your local DNS server does not provide records for app subdomains.
Pattern:
https://<APPNAME>.<IP>.sslip.io:8443
Example:
https://whoami.192.168.1.10.sslip.io:8443
Hint
Most recipes are already prepared for sslip.io usage. In many cases,
you only need to uncomment the corresponding line in the recipe
configuration section.
Using subdomains (e.g., whoami.mynas.internal) is preferred over path prefixes (e.g., mynas.internal/app) for accessing apps via the Traefik reverse proxy in the openmediavault Kubernetes plugin because:
Cleaner and simpler routing – Subdomains keep Ingress rules modular and avoid complex path rewrites.
Fewer compatibility issues – Many apps assume they run at / and break when served under a path prefix due to issues with relative URLs, static assets, or routing.
Avoids URL rewriting problems – With path prefixes, you often need to rewrite URLs or modify the app, which can cause subtle bugs or failures.
Better isolation and security – Subdomains help enforce security boundaries between apps.
Easier scaling and maintenance – Apps on subdomains are more portable, scalable, and microservice-friendly.
Recipes
The Kubernetes service offers several, so called, recipes to help you get started with installing popular applications.
The recipes are maintained in the openmediavault-k8s-recipes GitHub project and are offered by the plugin in a graphical overview for easy installation.
The recipes have an area at the top of the YAML code that must be filled in by the user. This configuration area contains information that is then used by the recipe to install the application on the given system.
Installed applications are not updated by openmediavault, this must be done by the user. In most cases, it is sufficient to first delete the image and then the pod of the application to be updated.
Administration
openmediavault offers a rudimentary UI for managing simple tasks in the cluster, but it makes sense to use external software that specializes in this area. Examples include Rancher UI (to be installed using a recipe) or k9s.
Customization
The Kubernetes service in openmediavault is can be customized via environment variables to adapt it to your personal needs.
Environment variable |
Example |
Description |
|---|---|---|
OMV_K8S_K3S_VERSION |
|
Specifies the K3s version to be used.
To force a reinstallation of K3s with the specified version, create the file |