Uptime Kuma Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Deploy Uptime Kuma for external service monitoring with Authentik SSO protection.

Architecture: Single-replica Deployment with SQLite on Longhorn PVC, exposed via Traefik IngressRoute with ForwardAuth middleware for Authentik SSO.

Tech Stack: Kubernetes Deployment, Longhorn PVC, Traefik IngressRoute, cert-manager Certificate, Authentik ForwardAuth

---

Task 1: Create Namespace and Kustomization

Files:

• Create: argocd/app-configs/uptime-kuma/namespace.yaml
• Create: argocd/app-configs/uptime-kuma/kustomization.yaml

Step 1: Create directory

mkdir -p argocd/app-configs/uptime-kuma

Step 2: Create namespace.yaml

---
apiVersion: v1
kind: Namespace
metadata:
  name: uptime-kuma
  labels:
    app.kubernetes.io/name: uptime-kuma

Step 3: Create kustomization.yaml

---
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: uptime-kuma

resources:
  - namespace.yaml
  - pvc.yaml
  - deployment.yaml
  - service.yaml
  - certificate.yaml
  - ingress.yaml

Step 4: Validate kustomization structure

kubectl kustomize argocd/app-configs/uptime-kuma --enable-helm 2>&1 | head -5

Expected: Error about missing files (pvc.yaml, etc.) - confirms kustomization is valid

Step 5: Commit

git add argocd/app-configs/uptime-kuma/
git commit -m "feat(uptime-kuma): add namespace and kustomization"

---

Task 2: Create PVC for SQLite Storage

Files:

• Create: argocd/app-configs/uptime-kuma/pvc.yaml

Step 1: Create pvc.yaml

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: uptime-kuma-data
  namespace: uptime-kuma
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn
  resources:
    requests:
      storage: 1Gi

Step 2: Validate YAML syntax

kubectl apply --dry-run=client -f argocd/app-configs/uptime-kuma/pvc.yaml

Expected: persistentvolumeclaim/uptime-kuma-data created (dry run)

Step 3: Commit

git add argocd/app-configs/uptime-kuma/pvc.yaml
git commit -m "feat(uptime-kuma): add persistent volume claim"

---

Task 3: Create Deployment

Files:

• Create: argocd/app-configs/uptime-kuma/deployment.yaml

Step 1: Create deployment.yaml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: uptime-kuma
  namespace: uptime-kuma
  labels:
    app.kubernetes.io/name: uptime-kuma
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: uptime-kuma
  template:
    metadata:
      labels:
        app.kubernetes.io/name: uptime-kuma
    spec:
      containers:
        - name: uptime-kuma
          image: louislam/uptime-kuma:1
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 3001
              name: http
              protocol: TCP
          env:
            - name: UPTIME_KUMA_PORT
              value: "3001"
          volumeMounts:
            - name: data
              mountPath: /app/data
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /
              port: http
            initialDelaySeconds: 10
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: uptime-kuma-data
      restartPolicy: Always

Step 2: Validate YAML syntax

kubectl apply --dry-run=client -f argocd/app-configs/uptime-kuma/deployment.yaml

Expected: deployment.apps/uptime-kuma created (dry run)

Step 3: Commit

git add argocd/app-configs/uptime-kuma/deployment.yaml
git commit -m "feat(uptime-kuma): add deployment"

---

Task 4: Create Service

Files:

• Create: argocd/app-configs/uptime-kuma/service.yaml

Step 1: Create service.yaml

---
apiVersion: v1
kind: Service
metadata:
  name: uptime-kuma
  namespace: uptime-kuma
  labels:
    app.kubernetes.io/name: uptime-kuma
spec:
  type: ClusterIP
  ports:
    - port: 3001
      targetPort: http
      protocol: TCP
      name: http
  selector:
    app.kubernetes.io/name: uptime-kuma

Step 2: Validate YAML syntax

kubectl apply --dry-run=client -f argocd/app-configs/uptime-kuma/service.yaml

Expected: service/uptime-kuma created (dry run)

Step 3: Commit

git add argocd/app-configs/uptime-kuma/service.yaml
git commit -m "feat(uptime-kuma): add service"

---

Task 5: Create TLS Certificate

Files:

• Create: argocd/app-configs/uptime-kuma/certificate.yaml

Step 1: Create certificate.yaml

---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: uptime-kuma-tls
  namespace: uptime-kuma
spec:
  secretName: uptime-kuma-tls
  issuerRef:
    name: vault-issuer
    kind: ClusterIssuer
  dnsNames:
    - status.fzymgc.house
  usages:
    - server auth

Step 2: Validate YAML syntax

kubectl apply --dry-run=client -f argocd/app-configs/uptime-kuma/certificate.yaml

Expected: certificate.cert-manager.io/uptime-kuma-tls created (dry run)

Step 3: Commit

git add argocd/app-configs/uptime-kuma/certificate.yaml
git commit -m "feat(uptime-kuma): add TLS certificate"

---

Task 6: Create IngressRoute with ForwardAuth

Files:

• Create: argocd/app-configs/uptime-kuma/ingress.yaml

Step 1: Create ingress.yaml

Note: References the existing modern-auth middleware from the authentik namespace (cross-namespace reference). Do NOT duplicate the middleware.

---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: uptime-kuma
  namespace: uptime-kuma
  annotations:
    router-hosts.fzymgc.house/enabled: "true"
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`status.fzymgc.house`)
      kind: Rule
      middlewares:
        - name: modern-auth
          namespace: authentik
      services:
        - name: uptime-kuma
          port: 3001
  tls:
    secretName: uptime-kuma-tls

Step 2: Validate YAML syntax

kubectl apply --dry-run=client -f argocd/app-configs/uptime-kuma/ingress.yaml

Expected: ingressroute.traefik.io/uptime-kuma created (dry run)

Step 3: Commit

git add argocd/app-configs/uptime-kuma/ingress.yaml
git commit -m "feat(uptime-kuma): add ingress with ForwardAuth"

---

Task 7: Create ArgoCD Application

Files:

• Create: argocd/cluster-app/templates/uptime-kuma.yaml

Step 1: Create uptime-kuma.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: uptime-kuma
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "1"
spec:
  project: core-services
  sources:
    - repoURL: https://github.com/fzymgc-house/selfhosted-cluster
      targetRevision: HEAD
      path: argocd/app-configs/uptime-kuma
  destination:
    server: https://kubernetes.default.svc
    namespace: uptime-kuma
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - ServerSideApply=true
      - CreateNamespace=true

Step 2: Validate Helm template

helm template argocd/cluster-app/ | grep -A 20 "name: uptime-kuma"

Expected: Shows the Application manifest

Step 3: Commit

git add argocd/cluster-app/templates/uptime-kuma.yaml
git commit -m "feat(uptime-kuma): add ArgoCD application"

---

Task 8: Final Validation and Kustomize Build

Step 1: Validate full kustomize build

kubectl kustomize argocd/app-configs/uptime-kuma

Expected: Complete YAML output with all 6 resources

Step 2: Dry-run apply

kubectl apply --dry-run=server -k argocd/app-configs/uptime-kuma

Expected: All resources created (dry run)

Step 3: Final commit with design doc

git add docs/plans/
git commit -m "docs: add uptime-kuma design and implementation plan"

---

Task 9: Push and Create PR

Step 1: Push branch

git push -u origin feat/uptime-kuma

Step 2: Create PR

gh pr create --title "feat: deploy Uptime Kuma monitoring" --body "## Summary
- Deploy Uptime Kuma for external service monitoring
- Authentik SSO via ForwardAuth middleware
- Longhorn PVC for SQLite persistence
- Available at https://status.fzymgc.house

## Test Plan
- [ ] ArgoCD syncs successfully
- [ ] Pod starts and becomes healthy
- [ ] TLS certificate issues correctly
- [ ] ForwardAuth redirects to Authentik
- [ ] Can create admin account after SSO login
- [ ] Can add HTTP monitors for services

Closes #492

🤖 Generated with [Claude Code](https://claude.ai/code)"

---

Post-Deployment Steps (Manual)

After PR merges and ArgoCD syncs:

1. Navigate to https://status.fzymgc.house
2. Authenticate via Authentik SSO
3. Complete Uptime Kuma setup wizard (create local admin account)
4. Add initial monitors:
   • https://auth.fzymgc.house - Authentik
   • https://vault.fzymgc.house - Vault UI
   • https://grafana.fzymgc.house - Grafana