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
ipFamilyPolicyandipFamilies - 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
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.
|-----|---------|-------------|
| 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/datais 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 thewait-for-dbinit 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 SyncedVerified 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]
Uptime Kuma Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/louislam/uptime-kuma | Uptime Kuma container image |
| image.tag | string | 2.5.6 | Image tag |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Uptime Kuma(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| uptimeKuma.port | integer | 3001 | Application port |
| uptimeKuma.disableFrameSameOrigin | boolean | false | Allow iframe embedding from different origins |
| uptimeKuma.extraEnv | array | - | Extra environment variables for the container |
Database(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.type | string | sqlite | Database type Allowed: sqlitemariadb |
| database.external.host | string | "" | Database host |
| database.external.port | stringinteger | 3306 | Database port |
| database.external.name | string | uptime_kuma | Database name |
| database.external.username | string | uptime_kuma | Database username |
| database.external.password | string | "" | Database password |
| database.external.existingSecret | string | "" | Existing secret containing the database password |
| database.external.existingSecretPasswordKey | string | password | Key in the existing secret containing the password |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Enable persistence for /app/data |
| persistence.size | string | 2Gi | Storage size |
| persistence.storageClass | string | "" | Storage class (leave empty for cluster default) |
| persistence.accessModes | array | ["ReadWriteOnce"] | Access modes for the PVC |
| persistence.existingClaim | string | "" | Use an existing PVC instead of creating one |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount |
| serviceAccount.name | string | "" | ServiceAccount name |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
| serviceAccount.automountServiceAccountToken | boolean | false | Mount the Kubernetes API token into application and backup pods |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | HTTP service port |
| service.annotations | object | - | Annotations for the Service |
| service.ipFamilyPolicy | string | - | Service IP family policy for dual-stack clusters Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Service IP families for dual-stack clusters |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for Uptime Kuma |
| ingress.ingressClassName | string | traefik | Ingress class name (for example: traefik, nginx) |
| ingress.annotations | object | - | Annotations for the ingress |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | true | Chart configuration parameter |
| probes.startup.path | string | / | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | true | Chart configuration parameter |
| probes.liveness.path | string | / | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | true | Chart configuration parameter |
| probes.readiness.path | string | / | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | CPU and memory requests/limits for the main container |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
Runtime Storage(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| runtimeStorage.tmpSizeLimit | string | 256Mi | Maximum writable temporary storage for Uptime Kuma |
Lifecycle(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| lifecycle.preStop.exec.command | array | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for shutdown (seconds) |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod |
Backup(29)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable built-in backup CronJob |
| backup.schedule | string | 0 2 * * * | Backup schedule in Cron format |
| backup.suspend | boolean | false | Suspend backup execution |
| backup.concurrencyPolicy | string | Forbid | CronJob concurrency policy Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | 3 | Successful job history retained |
| backup.failedJobsHistoryLimit | integer | 3 | Failed job history retained |
| backup.backoffLimit | integer | 1 | Job backoff limit |
| backup.archivePrefix | string | uptime-kuma | Prefix for backup archive names |
| backup.resources | object | - | Resources for backup containers |
| backup.podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
| backup.securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| backup.securityContext.capabilities.drop | array | - | Chart configuration parameter |
| backup.securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| backup.tmpSizeLimit | string | 64Mi | Maximum writable temporary storage shared by backup containers |
| backup.images.uploader.repository | string | minio/mc | Chart configuration parameter |
| backup.images.uploader.tag | string | - | Chart configuration parameter |
| backup.images.uploader.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.images.mysql.repository | string | mysql | Chart configuration parameter |
| backup.images.mysql.tag | string | 8.4 | Chart configuration parameter |
| backup.images.mysql.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.s3.endpoint | string | "" | S3-compatible endpoint URL |
| backup.s3.bucket | string | "" | Target bucket name |
| backup.s3.prefix | string | uptime-kuma | Optional prefix inside the bucket |
| backup.s3.createBucketIfNotExists | boolean | true | Create bucket if not exists |
| backup.s3.existingSecret | string | "" | Existing secret containing access-key and secret-key |
| backup.s3.existingSecretAccessKeyKey | string | access-key | Key in existing secret for access key |
| backup.s3.existingSecretSecretKeyKey | string | secret-key | Key in existing secret for secret key |
| backup.s3.accessKey | string | "" | Inline access key |
| backup.s3.secretKey | string | "" | Inline secret key |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests to deploy alongside the chart |
Pod Disruption Budget(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podDisruptionBudget.enabled | boolean | false | Render a PodDisruptionBudget |
| podDisruptionBudget.minAvailable | integerstringnull | 1 | Minimum available pods during voluntary disruptions |
| podDisruptionBudget.maxUnavailable | integerstringnull | - | Maximum unavailable pods during voluntary disruptions |
Network Policy(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | false | Render a NetworkPolicy |
| networkPolicy.ingress | array | - | Ingress rules; an empty array denies all ingress |
| networkPolicy.egress | array | - | Egress rules; an empty array denies all egress |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | false | Render Gateway API HTTPRoute resources |
| gatewayAPI.httpRoutes | array | - | HTTPRoute definitions |
External Secrets(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Render ExternalSecret resources |
| externalSecrets.apiVersion | string | external-secrets.io/v1 | ExternalSecret API version Allowed: external-secrets.io/v1external-secrets.io/v1beta1 |
| externalSecrets.refreshInterval | string | 1h | Default provider sync interval for ExternalSecret items that do not set spec.refreshInterval |
| externalSecrets.items | array | - | ExternalSecret definitions with full spec blocks |
Mysql(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mysql.enabled | boolean | false | Enable the local MySQL chart |
| mysql.architecture | string | standalone | MySQL architecture |
| mysql.auth.database | string | uptime_kuma | Chart configuration parameter |
| mysql.auth.username | string | uptime_kuma | Chart configuration parameter |
| mysql.auth.password | string | "" | Required when using the MySQL subchart |
No schema parameters match your search
Try searching for a different keyword or reset the filter.