Skip to content
fzymgc-house Cluster Docs

Uptime Kuma Deployment Design

Date: 2026-01-24 Issue: selfhosted-cluster-zpx Status: Approved

Overview

Section titled “Overview”

Deploy Uptime Kuma for external service monitoring and uptime tracking with minimal initial scope.

Architecture

Section titled “Architecture”

Uptime Kuma runs as a single-replica Deployment in a dedicated uptime-kuma namespace. It uses an embedded SQLite database stored on a Longhorn PVC for persistence.

Components

Section titled “Components”
Component Description
Deployment Single pod running louislam/uptime-kuma:1
Service ClusterIP exposing port 3001
PVC 1Gi Longhorn volume at /app/data
IngressRoute status.fzymgc.house with Authentik ForwardAuth
Certificate TLS via cert-manager (Let’s Encrypt)

Design Decisions

Section titled “Design Decisions”
Decision Choice Rationale
Monitoring scope Minimal (3 services) Validate deployment before expanding
Storage Longhorn PVC Standard pattern, Velero backup included
Authentication ForwardAuth only Simpler than OIDC, established pattern
Notifications None initially Keep first deployment simple

File Structure

Section titled “File Structure”
argocd/app-configs/uptime-kuma/
├── kustomization.yaml     # Kustomize entry point
├── namespace.yaml         # uptime-kuma namespace
├── deployment.yaml        # Pod spec with SQLite volume
├── service.yaml           # ClusterIP on 3001
├── pvc.yaml              # 1Gi Longhorn storage
├── certificate.yaml       # TLS for status.fzymgc.house
└── ingress.yaml          # IngressRoute with ForwardAuth

Initial Monitors

Section titled “Initial Monitors”

Configured manually post-deployment:

  1. https://auth.fzymgc.house - Authentik
  2. https://vault.fzymgc.house - Vault UI
  3. https://grafana.fzymgc.house - Grafana

Deployment Flow

Section titled “Deployment Flow”
  1. ArgoCD Application added to argocd/cluster-app/
  2. ArgoCD syncs namespace, PVC, deployment, ingress
  3. First access at https://status.fzymgc.house:
    • Authentik ForwardAuth prompts for SSO login
    • Uptime Kuma setup wizard creates local admin account
  4. Configure the 3 initial HTTP monitors manually

Security

Section titled “Security”
  • ForwardAuth via authentik@kubernetescrd middleware
  • No ExternalSecrets needed (admin created via UI)
  • Namespace automatically included in Velero backups

Future Enhancements

Section titled “Future Enhancements”
  • Add more service monitors
  • Configure notification channels (Slack, email)
  • Public status page feature