Skip to content

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
  • kubectl configured 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

  • adminPassword must be at least 12 characters and must not be equal to adminUser
  • adminApiKey and adminMcpApiKey are 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:

kubectl get pods -n kuvasz-uptime

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:

kubectl port-forward -n kuvasz-uptime svc/kuvasz-uptime 8080:8080

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:

postgresql:
  enabled: true
  persistence:
    enabled: true
    storageClass: "your-storage-class"
    size: 10Gi

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:

resources:
  limits:
    cpu: 1000m
    memory: 768Mi
  requests:
    cpu: 100m
    memory: 768Mi

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 the my-status slug. 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 with 404, 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. fullnameOverride keeps this name stable (kuvasz in the example), and the port has to be the same as service.port (8080 by default). If you change service.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.

values.yaml (defaults)
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):

values.yaml
podSecurityContext:
  fsGroup: 1000
  sysctls:
    - name: net.ipv4.ping_group_range
      value: "0 2147483647"

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:

kubectl create configmap kuvasz-custom-config -n kuvasz-uptime --from-file kuvasz.yml

Then add the following to your values file:

values.yaml
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"
  1. Must not be /config/kuvasz.yml, see the warning below
  2. 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 uninstall doesn'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:

helm uninstall kuvasz-uptime --namespace kuvasz-uptime

Data Persistence

This will not delete the PersistentVolumeClaims by default. To also delete the stored data, run:

kubectl delete pvc -n kuvasz-uptime --all

Configuration reference

For a complete list of all available configuration options, you can inspect the chart's values:

helm show values oci://ghcr.io/kuvasz-uptime/kuvasz-uptime --version <VERSION>

Troubleshooting

Checking logs

kubectl logs -n kuvasz-uptime deployment/kuvasz-uptime -f

Database connection issues

If your Kuvasz instance can't connect to the database, verify:

  1. PostgreSQL pod is running: kubectl get pods -n kuvasz-uptime
  2. Database credentials are correct in your values file
  3. 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

Additional resources