Deploy Kuvasz via Helm Chart
Kuvasz provides an official Helm chart for deploying to Kubernetes clusters. This guide will walk you through the deployment process.
Prerequisites
- A running Kubernetes cluster
- Helm 3.8.0 or newer (Helm 4.x works too) installed. The chart is published to an OCI registry, and older Helm versions can't install charts from there
kubectlconfigured to access your cluster
Quick start
1. Add the official Helm repository
The official Helm chart is published to GitHub's OCI registry. To install it, you can pull it directly:
# Install with default values
helm install my-kuvasz oci://ghcr.io/kuvasz-uptime/kuvasz-uptime --version <VERSION>
# Or install with custom values
helm install my-kuvasz oci://ghcr.io/kuvasz-uptime/kuvasz-uptime --version <VERSION> -f my-values.yaml
Replace <VERSION> with the desired version (e.g., 3.3.0). You can find the available versions on the GitHub releases page.
2. Create a values File
Create a file called values.yaml to customize your deployment. Here's a minimal example:
# Database configuration
postgresql:
enabled: true
auth:
username: kuvasz-uptime
password: "YourSuperSecretDbPassword" # Change this!
database: kuvasz-uptime
# Authentication configuration
auth:
adminUser: "YourSuperSecretUsername" # Change this!
adminPassword: "YourSuperSecretPassword" # Change this!
# Optional API keys. Leave empty to disable API-key access.
adminApiKey: ""
adminMcpApiKey: ""
# Ingress configuration (optional)
ingress:
enabled: false
# Uncomment and configure if you want to expose Kuvasz externally
# className: "nginx"
# hosts:
# - host: kuvasz-uptime.example.com
# paths:
# - path: /
# pathType: Prefix
Credential Requirements
adminPasswordmust be at least 12 characters and must not be equal toadminUseradminApiKeyandadminMcpApiKeyare optional; when set, they must be at least 16 characters
3. Install the Chart
Install Kuvasz using your custom values:
helm install kuvasz-uptime oci://ghcr.io/kuvasz-uptime/kuvasz-uptime \
--version <VERSION> \
--values values.yaml \
--namespace kuvasz-uptime \
--create-namespace
4. Verify the installation
Check that all pods are running:
You should see the Kuvasz application pod and PostgreSQL pod (if enabled) in a Running state.
5. Access Kuvasz
By default, Kuvasz is exposed via a ClusterIP service. To access it locally, you can use port-forwarding:
Then open your browser to http://localhost:8080.
Configuration options
Using an external PostgreSQL database
If you already have a PostgreSQL database, you can disable the bundled PostgreSQL and configure an external connection:
postgresql:
enabled: false
externalDatabase:
host: "your-postgres-host"
port: 5432
database: "kuvasz-uptime"
user: "kuvasz-uptime"
password: "your-password"
# Or reference existing secret:
# existingSecret: "my-secret"
# existingSecretPasswordKey: "password"
Persistent storage
By default, the chart creates PersistentVolumeClaims for the PostgreSQL database. You can customize the storage:
Resource limits
Configure resource requests and limits for Kuvasz. The values below are enough for up to 1,000 monitors. If you have more, give Kuvasz more memory, and make its heap bigger with the JAVA_TOOL_OPTIONS environment variable (through extraEnv), as described in the hardware requirements:
The memory request is the same as the limit on purpose: this way Kubernetes starts Kuvasz only on a node that has enough free memory for it. The default values of the chart request less (256Mi), so set it yourself.
Ingress configuration
To expose Kuvasz externally with an Ingress controller:
ingress:
enabled: true
className: "nginx"
annotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
hosts:
- host: kuvasz-uptime.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: kuvasz-uptime-tls
hosts:
- kuvasz-uptime.example.com
Gateway API HTTPRoute
You can expose Kuvasz with a Gateway API HTTPRoute instead of, or alongside, an Ingress. The chart creates the HTTPRoute; the target Gateway must already exist in the cluster:
httpRoute:
enabled: true
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: gateway
namespace: gateway-system
sectionName: https
hostnames:
- kuvasz-uptime.example.com
matches:
- path:
type: PathPrefix
value: /
If httpRoute.parentRefs is empty, the route attaches to a Gateway named gateway in the release namespace. httpRoute.filters, httpRoute.timeouts, and httpRoute.extraRules are rendered directly into the HTTPRoute spec for advanced Gateway API use cases.
Kubernetes fills in some fields of the HTTPRoute if they are not set. For example, it adds group and kind to every Gateway in parentRefs and to every backend in backendRefs, weight to every backend, type to every path and header match, and statusCode to every redirect. The chart sets these fields for the default Gateway and for the backend it creates, but it uses your own httpRoute.parentRefs, httpRoute.matches, httpRoute.filters and httpRoute.extraRules as they are. If you use a tool that compares the chart with what is running in the cluster (like Argo CD), set these fields in your own values too, as in the example above. Otherwise, the tool keeps reporting the route as out of sync. For the same reason, don't leave httpRoute.matches empty: Kubernetes adds a match for every path (/) in that case.
Additional HTTPRoutes
Sometimes one route is not enough. For example, you may want to expose Kuvasz on two Gateways: an internal one that serves everything, and a public one that serves only a status page. The Gateways and the hostnames are set for the whole route, so every rule of a route works on every Gateway it is attached to. That's why the chart can create more routes with extraHttpRoutes.
Each item of extraHttpRoutes takes the same keys as httpRoute (except enabled), and gets its own default rule that sends the requests to the Service of the chart. The route is named <fullname>-<name>, so the names have to be unique. The items don't inherit anything from httpRoute, and the chart creates them even if httpRoute.enabled is false. To turn off a route, remove its item: the chart stops with an error if an item has an enabled key, so a route you wanted to turn off is never created by mistake.
Always set matches
The items don't inherit the default matches of httpRoute either. If an item has no matches, its default rule matches every path, so the whole app (the dashboard, the API and /mcp too) is reachable through that route.
The example below serves a public status page at the root of status.example.com, and nothing else:
fullnameOverride: kuvasz
extraHttpRoutes:
- name: public
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: external
namespace: gateway
hostnames:
- status.example.com
matches:
- path:
type: PathPrefix
value: /public
extraRules:
- matches:
- path:
type: Exact
value: /
filters:
- type: URLRewrite
urlRewrite:
path:
type: ReplaceFullPath
replaceFullPath: /status/my-status
backendRefs:
- group: ""
kind: Service
name: kuvasz
port: 8080
weight: 1
- The default rule serves the stylesheets, scripts and icons of the page under
/public. - The extra rule sends
/to the status page with themy-statusslug. The address bar still shows/, and the page refreshes itself through this address too. - Every other path (the dashboard, the API,
/mcp, etc.) matches no rule, so the Gateway answers with404, and the request never reaches Kuvasz. - Only the default rule sends the requests to the Service of the chart automatically, so the extra rule has to name the Service and its port itself.
fullnameOverridekeeps this name stable (kuvaszin the example), and the port has to be the same asservice.port(8080by default). If you changeservice.port, change the port in the extra rule too, otherwise only the assets of the page keep working.
If you want to serve status pages on more hostnames, create one route for each of them, because each hostname has to send / to a different page.
List the paths you want to expose
Don't try to hide some paths (for example /mcp) with a rule that redirects or blocks them, and let everything else through. Some Gateways pass on paths like //mcp or /mcp%2F as they are, so these skip your rule, but Kuvasz still treats them as /mcp. A list of the allowed paths, like in the example above, is much safer: a path that is not on the list doesn't reach Kuvasz at all.
The note above about the fields that Kubernetes fills in is true for these routes too.
Security context
The chart runs Kuvasz as a non-root user and group (1000:1000), without any capabilities, and with a read-only root filesystem by default. The only place Kuvasz writes to is /tmp (the temporary files of the YAML exports), which the chart always mounts as an emptyDir volume, so you don't need to add one yourself.
podSecurityContext:
fsGroup: 1000
securityContext:
runAsNonRoot: true
runAsUser: 1000
runAsGroup: 1000
capabilities:
drop:
- ALL
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
ICMP monitors on older container runtimes
ICMP monitors rely on unprivileged ICMP sockets, which are only allowed for the groups covered by the net.ipv4.ping_group_range kernel parameter. containerd 2.x allows them for every group by default, but older runtimes (e.g. containerd 1.x) might not, and your ICMP monitors will be DOWN with a ping: permission denied (are you root?) error. In that case, set the parameter for the pod (it's a safe sysctl, so it's allowed by default):
If you'd like to monitor the containers of your nodes through their Docker socket, the group owning the socket has to be added to the pod as well, see the related recipe.
Configuring Kuvasz
You can provide a custom YAML configuration by including it in your values file:
config:
raw: |
integrations:
slack:
- name: team-notifications
webhook-url: 'https://hooks.slack.com/services/XXX/YYY/ZZZ'
global: true
http-monitors:
- name: example-monitor
url: https://example.com
uptime-check-interval: 60
Using your own ConfigMap
If you'd rather keep your configuration separate from your values file, you can manage it in your own ConfigMap, mount it into the container with extraVolumes and extraVolumeMounts, and point Kuvasz to it with the MICRONAUT_CONFIG_FILES environment variable.
First, create the ConfigMap from your local kuvasz.yml:
Then add the following to your values file:
extraVolumes:
- name: custom-config
configMap:
name: kuvasz-custom-config
extraVolumeMounts:
- name: custom-config
mountPath: /config/kuvasz-custom.yml # (1)!
subPath: kuvasz.yml # (2)!
readOnly: true
extraEnv:
- name: MICRONAUT_CONFIG_FILES
value: "/config/kuvasz-custom.yml"
- Must not be
/config/kuvasz.yml, see the warning below - The key of the file in your ConfigMap (with
--from-file, it's the name of the file you created it from)
Use a different file name than kuvasz.yml
The chart always mounts its own configuration (the one built from config.raw) to /config/kuvasz.yml, so your file has to be mounted to a different path (e.g. /config/kuvasz-custom.yml). Kubernetes doesn't allow two volume mounts with the same path, so the pod won't be created if you mount your ConfigMap to /config/kuvasz.yml.
Setting MICRONAUT_CONFIG_FILES replaces the default config file location of the image, so the chart's own /config/kuvasz.yml (and therefore config.raw) won't be loaded anymore. Keep your whole configuration in your own ConfigMap.
Since Kuvasz reads its configuration on startup only, you need to restart the deployment after changing your ConfigMap (the chart can only detect the changes of config.raw automatically):
kubectl create configmap kuvasz-custom-config -n kuvasz-uptime --from-file kuvasz.yml \
--dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment -n kuvasz-uptime kuvasz-uptime
Admin credentials
The chart stores the admin username and password in a Secret, named <release-name>-kuvasz-uptime-admin by default. The name is different if the release name already contains kuvasz-uptime (then it's <release-name>-admin), or if you set nameOverride or fullnameOverride. helm status <release-name> prints the commands to read the credentials with the exact name of your Secret. With the default name, you can read the values with:
kubectl get secret -n <namespace> <release-name>-kuvasz-uptime-admin -o jsonpath='{.data.admin-user}' | base64 -d
kubectl get secret -n <namespace> <release-name>-kuvasz-uptime-admin -o jsonpath='{.data.admin-password}' | base64 -d
If you leave auth.adminUser or auth.adminPassword empty, the chart creates a random value for it, but only if the Secret doesn't have one yet. When you upgrade, the chart reads the Secret from the cluster and keeps these values. So they don't change, and the pod doesn't restart because of them (except once, on the first upgrade after a fresh install). This also means that:
- if you remove a value that you set before (e.g.
auth.adminPassword), the chart keeps the old value, and doesn't create a random one, helm uninstalldoesn't delete the Secret, so if you install the chart again with the same release name, it uses the old values.
If you want new random values, delete the Secret (kubectl delete secret -n <namespace> <release-name>-kuvasz-uptime-admin), then run helm upgrade (or helm install) again.
Tools that create the manifests with helm template (like Argo CD) can't read the Secret from the cluster, so they create new random values every time. If you use such a tool, set auth.adminUser and auth.adminPassword yourself, or create the Secret yourself and set externalAdminSecret: true.
OIDC authentication
You can configure OpenID Connect instead of the built-in username/password login form:
auth:
enabled: true
oidc:
enabled: true
issuer: "https://keycloak.example.com/realms/kuvasz"
clientId: "kuvasz"
clientSecret: "your-client-secret"
authorizationServer: "KEYCLOAK"
allowedEmails:
- admin@example.com
requireVerifiedEmail: true
When OIDC is enabled, auth.adminUser and auth.adminPassword are ignored. auth.adminApiKey remains independent and can still be used for REST API access.
Supported auth.oidc.authorizationServer values are AUTH0, COGNITO, KEYCLOAK, MICROSOFT, OKTA, and ORACLE_CLOUD.
For production, prefer using an existing Kubernetes Secret for the OIDC client secret:
auth:
oidc:
enabled: true
issuer: "https://keycloak.example.com/realms/kuvasz"
clientId: "kuvasz"
existingSecret: "kuvasz-oidc"
existingSecretClientSecretKey: "client-secret"
When externalAdminSecret=true, auth.oidc.clientSecret cannot be used because the chart does not create or update the admin Secret. In that mode, either put an oidc-client-secret key in the external admin Secret or use auth.oidc.existingSecret.
Upgrading
To upgrade to a new version of Kuvasz:
helm upgrade kuvasz-uptime oci://ghcr.io/kuvasz-uptime/kuvasz-uptime \
--version <NEW_VERSION> \
--values values.yaml \
--namespace kuvasz-uptime
Uninstalling
To remove Kuvasz from your cluster:
Data Persistence
This will not delete the PersistentVolumeClaims by default. To also delete the stored data, run:
Configuration reference
For a complete list of all available configuration options, you can inspect the chart's values:
Troubleshooting
Checking logs
Database connection issues
If your Kuvasz instance can't connect to the database, verify:
- PostgreSQL pod is running:
kubectl get pods -n kuvasz-uptime - Database credentials are correct in your values file
- Network policies allow communication between pods
Health check
Check if Kuvasz is healthy using the health endpoint:
kubectl exec -n kuvasz-uptime deployment/kuvasz-uptime -- wget -q -O- http://localhost:8080/api/v2/health