Skip to content
Uptime Kuma icon
v1.6.2App: v2.5.6Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Uptime Kuma Helm Chart

Deploy Uptime Kuma on Kubernetes using the official louislam/uptime-kuma Docker image. Self-hosted monitoring with HTTP/TCP/DNS/Ping checks, 90+ notification services, and customizable status pages.

Features

  • 20+ monitor types — HTTP(s), TCP, Ping, DNS, Docker, WebSocket, and more
  • 90+ notification services — Telegram, Discord, Slack, Email, Pushover, and more
  • Status pages — public status pages with custom domains
  • SQLite or MariaDB — embedded SQLite (default) or MySQL subchart
  • External database — connect to existing MariaDB instances
  • Scheduled backups — SQLite tar or mysqldump with S3 upload
  • Ingress support — TLS with cert-manager
  • Gateway API support — optional HTTPRoute rendering for dashboard and status pages
  • External Secrets support — optional ExternalSecret resources for database, backup, or integration credentials
  • Dual-stack Service support — optional ipFamilyPolicy and ipFamilies
  • Secure runtime defaults — seccomp, dropped capabilities, read-only root filesystem, and no API token mount
  • Availability controls — optional PodDisruptionBudget and NetworkPolicy
  • 2FA — built-in two-factor authentication

Architecture

The chart runs one Uptime Kuma application pod behind a ClusterIP Service. The application stores state either on the /app/data PVC (SQLite) or in a bundled or external MariaDB-compatible database. Optional Ingress and HTTPRoute resources expose the Service. A separate CronJob can archive SQLite data or run mysqldump, then upload the result to S3-compatible storage.

Uptime Kuma is intentionally single-replica: horizontal scaling duplicates monitor execution and WebSocket state. The optional PodDisruptionBudget protects that pod from voluntary disruption but does not make the application highly available.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install uptime-kuma helmforge/uptime-kuma -f values.yaml

OCI registry:

helm install uptime-kuma oci://ghcr.io/helmforgedev/helm/uptime-kuma -f values.yaml

Basic Example (SQLite)

# values.yaml — default values are sufficient
# SQLite is used by default, no database configuration needed

After deploying, access the setup wizard:

kubectl port-forward svc/<release>-uptime-kuma 3001:80
# Open http://localhost:3001

MariaDB Mode

The optional local database path uses the HelmForge MySQL subchart 2.1.1 as a MariaDB-compatible backend.

database:
  type: mariadb

mysql:
  enabled: true
  auth:
    password: "change-me"

External Database

database:
  type: mariadb
  external:
    host: mariadb.example.com
    name: uptime_kuma
    username: uptime_kuma
    existingSecret: uptime-kuma-db-credentials

mysql:
  enabled: false

Gateway API

gatewayAPI:
  enabled: true
  httpRoutes:
    - name: web
      parentRefs:
        - name: public
          namespace: gateway-system
      hostnames:
        - status.example.com

External Secrets

Use External Secrets Operator to materialize Secrets, then point chart values at those target Secrets.

database:
  type: mariadb
  external:
    host: mariadb.example.com
    existingSecret: uptime-kuma-db

externalSecrets:
  enabled: true
  items:
    - name: database
      spec:
        secretStoreRef:
          name: platform-secrets
          kind: ClusterSecretStore
        target:
          name: uptime-kuma-db
          creationPolicy: Owner
        data:
          - secretKey: password
            remoteRef:
              key: uptime-kuma/database
              property: password
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | image.repository | docker.io/louislam/uptime-kuma | Uptime Kuma container image | | image.tag | 2.5.6 | Uptime Kuma image tag | | uptimeKuma.port | 3001 | Application port | | database.type | sqlite | Database type (sqlite, mariadb) | | mysql.enabled | false | Deploy MySQL subchart (helmforge/mysql 2.1.1) | | persistence.enabled | true | Enable persistence for /app/data | | persistence.size | 2Gi | PVC size | | ingress.enabled | false | Enable ingress | | backup.enabled | false | Enable S3 backups | | service.port | 80 | Service port | | service.ipFamilyPolicy | omitted | Optional Service IP family policy for dual-stack clusters | | gatewayAPI.enabled | false | Enable Gateway API HTTPRoute rendering | | externalSecrets.enabled | false | Render ExternalSecret resources | | serviceAccount.automountServiceAccountToken | false | Mount the Kubernetes API token | | runtimeStorage.tmpSizeLimit | 256Mi | Writable /tmp emptyDir limit | | podDisruptionBudget.enabled | false | Render a PodDisruptionBudget | | networkPolicy.enabled | false | Render an explicit NetworkPolicy | | image.pullPolicy | IfNotPresent | Container image pull policy | | uptimeKuma.disableFrameSameOrigin | false | Allow cross-origin iframe embedding | | uptimeKuma.extraEnv | [] | Additional application environment variables | | database.external.host | "" | External MariaDB-compatible hostname | | database.external.port | "3306" | External database port | | database.external.name | uptime_kuma | External database name | | database.external.username | uptime_kuma | External database user | | database.external.existingSecret | "" | Secret containing the external database password | | persistence.storageClass | "" | PVC StorageClass; empty uses the cluster default | | persistence.accessModes | [ReadWriteOnce] | PVC access modes | | persistence.existingClaim | "" | Existing PVC used for /app/data | | serviceAccount.create | false | Create a dedicated ServiceAccount | | serviceAccount.name | "" | Existing or generated ServiceAccount name override | | ingress.ingressClassName | traefik | Ingress controller class | | ingress.hosts | [] | Ingress host and path rules | | ingress.tls | [] | Ingress TLS configuration | | probes.startup.enabled | true | Enable the startup probe | | probes.liveness.enabled | true | Enable the liveness probe | | probes.readiness.enabled | true | Enable the readiness probe | | resources | {} | Application CPU and memory requests/limits | | podSecurityContext | RuntimeDefault seccomp | Pod-level security context | | securityContext | Restricted defaults | Application container security context | | terminationGracePeriodSeconds | 30 | Graceful termination window | | nodeSelector | {} | Pod node selector | | tolerations | [] | Pod tolerations | | affinity | {} | Pod affinity and anti-affinity rules | | topologySpreadConstraints | [] | Pod topology spread constraints | | backup.schedule | 0 2 * * * | Backup CronJob schedule | | backup.concurrencyPolicy | Forbid | Concurrent backup execution policy | | backup.tmpSizeLimit | 64Mi | Backup temporary-storage limit | | backup.s3.endpoint | "" | Required S3-compatible endpoint when backup is enabled | | backup.s3.bucket | "" | Required backup bucket | | backup.s3.existingSecret | "" | Secret containing S3 credentials | | podDisruptionBudget.minAvailable | 1 | Minimum available pod during voluntary disruptions | | podDisruptionBudget.maxUnavailable | null | Alternative maximum unavailable value | | networkPolicy.ingress | [] | Complete ingress rules; empty denies ingress | | networkPolicy.egress | [] | Complete egress rules; empty denies egress | | gatewayAPI.httpRoutes | [] | HTTPRoute definitions | | externalSecrets.items | [] | ExternalSecret resources with complete specs | | extraVolumes | [] | Additional application volumes | | extraVolumeMounts | [] | Additional application volume mounts | | extraManifests | [] | Additional Kubernetes manifests |

Security and Operations

The application and backup containers deny privilege escalation, drop all Linux capabilities, use the runtime-default seccomp profile, and keep the image root filesystem read-only. Writable temporary files use bounded emptyDir volumes. Kubernetes API tokens are not mounted unless explicitly enabled. Database value changes update the pod checksum annotation so credential rotations trigger a rollout.

The upstream standard image still starts as UID 0, so the chart does not claim a non-root runtime. Use admission policy, network isolation, resource limits, and tested backups as complementary controls. When enabling networkPolicy, define the ingress and egress rules required for your ingress controller, DNS, monitor targets, notification endpoints, database, and S3 service.

Troubleshooting

  • Pod startup failures: inspect all container logs and verify /app/data is writable, the PVC is bound, and the selected database is reachable.
  • MariaDB failures: confirm database.type=mariadb, provide either the bundled MySQL password or an external database Secret, and check the wait-for-db init container.
  • Backup failures: inspect the backup Job, verify S3 endpoint/bucket credentials, and confirm persistence remains enabled for SQLite backups.
  • NetworkPolicy failures: start from the required DNS, database, S3, notification, monitor-target, and ingress-controller flows; empty rule lists deny that direction.
  • Upgrade failures: restore the last tested backup in a non-production namespace before retrying the upgrade.

Upgrade Notes

Uptime Kuma 2.5.6 fixes average-response badge calculations and updates security-sensitive dependencies. The default database.type=sqlite, port, and persistence paths are unchanged. See the upstream release notes. Keep persistence enabled and back up /app/data before upgrading live instances.

More Information

Security Scan: uptime-kuma

Framework Score
MITRE + NSA + SOC2 72.72727%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  client[Operator or status-page visitor] --> edge[Ingress or HTTPRoute]
  edge --> service[ClusterIP Service]
  service --> app[Uptime Kuma pod]
  app --> sqlite[(PVC /app/data)]
  app --> database[(Bundled or external database)]
  secret[Database Secret] --> app
  backup[Optional backup CronJob] --> sqlite
  backup --> database
  backup --> s3[S3-compatible storage]
Official Contractvalues.schema.json

Uptime Kuma Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

120 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/louislam/uptime-kumaUptime Kuma container image
image.tagstring2.5.6Image tag
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Uptime Kuma(3)

ParameterTypeDefaultDescription
uptimeKuma.portinteger3001Application port
uptimeKuma.disableFrameSameOriginbooleanfalseAllow iframe embedding from different origins
uptimeKuma.extraEnvarray-Extra environment variables for the container

Database(8)

ParameterTypeDefaultDescription
database.typestringsqliteDatabase type
Allowed:sqlitemariadb
database.external.hoststring""Database host
database.external.portstringinteger3306Database port
database.external.namestringuptime_kumaDatabase name
database.external.usernamestringuptime_kumaDatabase username
database.external.passwordstring""Database password
database.external.existingSecretstring""Existing secret containing the database password
database.external.existingSecretPasswordKeystringpasswordKey in the existing secret containing the password

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueEnable persistence for /app/data
persistence.sizestring2GiStorage size
persistence.storageClassstring""Storage class (leave empty for cluster default)
persistence.accessModesarray["ReadWriteOnce"]Access modes for the PVC
persistence.existingClaimstring""Use an existing PVC instead of creating one

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a ServiceAccount
serviceAccount.namestring""ServiceAccount name
serviceAccount.annotationsobject-Annotations for the ServiceAccount
serviceAccount.automountServiceAccountTokenbooleanfalseMount the Kubernetes API token into application and backup pods

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80HTTP service port
service.annotationsobject-Annotations for the Service
service.ipFamilyPolicystring-Service IP family policy for dual-stack clusters
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Service IP families for dual-stack clusters

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for Uptime Kuma
ingress.ingressClassNamestringtraefikIngress class name (for example: traefik, nginx)
ingress.annotationsobject-Annotations for the ingress
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledbooleantrueChart configuration parameter
probes.startup.pathstring/Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledbooleantrueChart configuration parameter
probes.liveness.pathstring/Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledbooleantrueChart configuration parameter
probes.readiness.pathstring/Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory requests/limits for the main container

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContext.seccompProfile.typestring-Chart configuration parameter

Container Security(3)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter

Runtime Storage(1)

ParameterTypeDefaultDescription
runtimeStorage.tmpSizeLimitstring256MiMaximum writable temporary storage for Uptime Kuma

Lifecycle(1)

ParameterTypeDefaultDescription
lifecycle.preStop.exec.commandarray-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for shutdown (seconds)

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Backup(29)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable built-in backup CronJob
backup.schedulestring0 2 * * *Backup schedule in Cron format
backup.suspendbooleanfalseSuspend backup execution
backup.concurrencyPolicystringForbidCronJob concurrency policy
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger3Successful job history retained
backup.failedJobsHistoryLimitinteger3Failed job history retained
backup.backoffLimitinteger1Job backoff limit
backup.archivePrefixstringuptime-kumaPrefix for backup archive names
backup.resourcesobject-Resources for backup containers
backup.podSecurityContext.seccompProfile.typestring-Chart configuration parameter
backup.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
backup.securityContext.capabilities.droparray-Chart configuration parameter
backup.securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
backup.tmpSizeLimitstring64MiMaximum writable temporary storage shared by backup containers
backup.images.uploader.repositorystringminio/mcChart configuration parameter
backup.images.uploader.tagstring-Chart configuration parameter
backup.images.uploader.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.images.mysql.repositorystringmysqlChart configuration parameter
backup.images.mysql.tagstring8.4Chart configuration parameter
backup.images.mysql.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.s3.endpointstring""S3-compatible endpoint URL
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringuptime-kumaOptional prefix inside the bucket
backup.s3.createBucketIfNotExistsbooleantrueCreate bucket if not exists
backup.s3.existingSecretstring""Existing secret containing access-key and secret-key
backup.s3.existingSecretAccessKeyKeystringaccess-keyKey in existing secret for access key
backup.s3.existingSecretSecretKeyKeystringsecret-keyKey in existing secret for secret key
backup.s3.accessKeystring""Inline access key
backup.s3.secretKeystring""Inline secret key

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart

Pod Disruption Budget(3)

ParameterTypeDefaultDescription
podDisruptionBudget.enabledbooleanfalseRender a PodDisruptionBudget
podDisruptionBudget.minAvailableintegerstringnull1Minimum available pods during voluntary disruptions
podDisruptionBudget.maxUnavailableintegerstringnull-Maximum unavailable pods during voluntary disruptions

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledbooleanfalseRender a NetworkPolicy
networkPolicy.ingressarray-Ingress rules; an empty array denies all ingress
networkPolicy.egressarray-Egress rules; an empty array denies all egress

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledbooleanfalseRender Gateway API HTTPRoute resources
gatewayAPI.httpRoutesarray-HTTPRoute definitions

External Secrets(4)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseRender ExternalSecret resources
externalSecrets.apiVersionstringexternal-secrets.io/v1ExternalSecret API version
Allowed:external-secrets.io/v1external-secrets.io/v1beta1
externalSecrets.refreshIntervalstring1hDefault provider sync interval for ExternalSecret items that do not set spec.refreshInterval
externalSecrets.itemsarray-ExternalSecret definitions with full spec blocks

Mysql(5)

ParameterTypeDefaultDescription
mysql.enabledbooleanfalseEnable the local MySQL chart
mysql.architecturestringstandaloneMySQL architecture
mysql.auth.databasestringuptime_kumaChart configuration parameter
mysql.auth.usernamestringuptime_kumaChart configuration parameter
mysql.auth.passwordstring""Required when using the MySQL subchart