Yuptime

Kubernetes-native monitoring where all configuration is CRDs

Documentation • Quick Start • Monitor Types • Examples

---

Why Yuptime?

Yuptime is a monitoring solution designed for Kubernetes-first teams. Unlike traditional monitoring tools that require databases and complex setups, Yuptime stores everything in Kubernetes Custom Resource Definitions (CRDs).

• 🎯 GitOps-Native: All configuration lives in Git as YAML manifests
• 📦 Database-Free: No databases to manage — state lives in CRD status subresources
• ⚙️ Bounded Execution: Persistent workers run checks without per-check Kubernetes objects
• 📊 Prometheus Metrics: Native metrics export for Grafana dashboards
• 🔔 Alertmanager Integration: Direct webhook integration for alert routing
• ⏰ Smart Suppression: Maintenance windows with RRULE scheduling and ad-hoc silences

Architecture

Monitor CRDs -> Controller Check Engine -> Checker sidecar -> Targets
                       |
                       +-> Monitor status
                       +-> Prometheus
                       +-> Alertmanager

Key Design Principles:

• Controller only updates status subresources, never spec (source of truth stays in Git)
• Exact schedule slots do not drift with execution time, retries, or queue delay
• A fixed worker pool and bounded queue prevent API and process storms
• The controller is the sole ordered status writer; workers hold no database state

The Timoni/CUE module under timoni/yuptime/ is the authoritative packaging and CRD source for maintainers. The checked-in k8s/, helm/yuptime/, and manifests/ trees are generated mirrors with semantic parity checks.

Quick Start

Prerequisites

• Kubernetes cluster (1.26+)
• kubectl configured

Installation

Choose your preferred installation method:

⎈ Helm (Recommended)

Helm is the default installation route and has the broadest Kubernetes ecosystem support.

# Install from GHCR (public, no login required)
helm install yuptime oci://ghcr.io/briansunter/yuptime/charts/yuptime \
  --namespace yuptime \
  --create-namespace

# With custom values
helm install yuptime oci://ghcr.io/briansunter/yuptime/charts/yuptime \
  --namespace yuptime \
  --create-namespace \
  --set mode=production \
  --set logging.level=info

📦 Timoni (Type-safe/advanced)

Timoni provides CUE validation, rich customization, OCI distribution, and GitOps-oriented lifecycle management.

# Install Timoni
brew install stefanprodan/tap/timoni

# Apply the module
timoni apply yuptime oci://ghcr.io/briansunter/yuptime/timoni-module \
  --version latest \
  --namespace yuptime

📋 kubectl (Static Manifests)

Direct Kubernetes resource application — no tools required.

# Apply CRDs first
kubectl apply -f https://raw.githubusercontent.com/briansunter/yuptime/master/k8s/crds.yaml

# Create namespace and apply all resources
kubectl create namespace yuptime
kubectl apply -f https://raw.githubusercontent.com/briansunter/yuptime/master/manifests/all.yaml -n yuptime

Verify Installation

# Check pods are running
kubectl get pods -n yuptime

# Check CRDs are installed
kubectl get crds | grep yuptime

# Port forward to access metrics
kubectl port-forward -n yuptime svc/yuptime-api 3000:3000
curl http://localhost:3000/health

Your First Monitor

Create a simple HTTP monitor:

# my-monitor.yaml
apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: example-website
  namespace: yuptime
spec:
  type: http
  schedule:
    intervalSeconds: 60
    timeoutSeconds: 30
  target:
    http:
      url: "https://example.com"
      method: GET
  successCriteria:
    http:
      acceptedStatusCodes: [200, 201]

kubectl apply -f my-monitor.yaml

Check the monitor status:

kubectl get monitors -n yuptime
kubectl describe monitor example-website -n yuptime

Monitor Types

Yuptime currently exposes 17 monitor enum values. docker is reserved in the schema but not implemented yet; the others map to active checkers.

Type	Description	Use Case
http	HTTP/HTTPS endpoints	APIs, websites, webhooks
tcp	TCP port connectivity	Databases, services
dns	DNS record queries	DNS infrastructure
ping	ICMP ping checks	Network connectivity
websocket	WebSocket connections	Real-time services
grpc	gRPC health checks	Microservices
mysql	MySQL connectivity	Database health
postgresql	PostgreSQL connectivity	Database health
redis	Redis PING	Cache health
k8s	K8s resource health	Deployments, pods
push	Push-based monitoring	Custom apps
steam	Steam game servers	Gaming infrastructure
keyword	Content matching	Page content validation
jsonQuery	JSON response validation	API response checking
xmlQuery	XML/XPath validation	XML APIs, feeds
htmlQuery	HTML/CSS selector validation	Page structure checks
docker	Reserved placeholder	Not implemented

Examples

HTTP Monitor with Authentication

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: api-with-auth
  namespace: yuptime
spec:
  type: http
  schedule:
    intervalSeconds: 60
    timeoutSeconds: 30
  target:
    http:
      url: "https://api.example.com/health"
      method: GET
      auth:
        bearer:
          tokenSecretRef:
            name: api-credentials
            key: token
  successCriteria:
    http:
      acceptedStatusCodes: [200]

JSON Response Validation

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: api-json-check
  namespace: yuptime
spec:
  type: jsonQuery
  schedule:
    intervalSeconds: 120
    timeoutSeconds: 30
  target:
    http:
      url: "https://api.example.com/status"
      method: GET
  successCriteria:
    jsonQuery:
      mode: jsonpath-plus
      path: "$.status"
      equals: "healthy"

TCP Database Check

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: postgres-connectivity
  namespace: yuptime
spec:
  type: tcp
  schedule:
    intervalSeconds: 30
    timeoutSeconds: 10
  target:
    tcp:
      host: "postgres.database.svc.cluster.local"
      port: 5432

MySQL Health Check

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: mysql-health
  namespace: yuptime
spec:
  type: mysql
  schedule:
    intervalSeconds: 60
    timeoutSeconds: 10
  target:
    mysql:
      host: "mysql.database.svc.cluster.local"
      port: 3306
      database: "myapp"
      credentialsSecretRef:
        name: mysql-credentials
        usernameKey: username
        passwordKey: password
      healthQuery: "SELECT 1"

gRPC Health Check

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: grpc-service
  namespace: yuptime
spec:
  type: grpc
  schedule:
    intervalSeconds: 30
    timeoutSeconds: 10
  target:
    grpc:
      host: "my-service.default.svc.cluster.local"
      port: 50051
      service: "my.package.MyService"
      useTLS: false

Kubernetes Deployment Health

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: my-app-deployment
  namespace: yuptime
spec:
  type: k8s
  schedule:
    intervalSeconds: 60
    timeoutSeconds: 30
  target:
    k8s:
      resource:
        apiVersion: apps/v1
        kind: Deployment
        name: my-app
      check:
        type: AvailableReplicasAtLeast
        min: 3

Bulk Monitors with MonitorSet

apiVersion: monitoring.yuptime.io/v1
kind: MonitorSet
metadata:
  name: api-endpoints
  namespace: yuptime
spec:
  defaults:
    schedule:
      intervalSeconds: 60
      timeoutSeconds: 30
    successCriteria:
      http:
        acceptedStatusCodes: [200]
    alertmanagerUrl: "http://alertmanager.monitoring:9093/api/v2/alerts"
  items:
    - name: users-api
      spec:
        type: http
        target:
          http:
            url: "https://api.example.com/users"

    - name: orders-api
      spec:
        type: http
        target:
          http:
            url: "https://api.example.com/orders"

Maintenance Window (RRULE)

apiVersion: monitoring.yuptime.io/v1
kind: MaintenanceWindow
metadata:
  name: weekly-maintenance
  namespace: yuptime
spec:
  enabled: true
  schedule:
    start: "2026-03-15T02:00:00Z"
    end: "2026-03-15T04:00:00Z"
    recurrence:
      rrule: "FREQ=WEEKLY;BYDAY=SU"
  match:
    matchLabels:
      matchLabels:
        environment: production
  behavior:
    suppressNotifications: true

Ad-hoc Silence

apiVersion: monitoring.yuptime.io/v1
kind: Silence
metadata:
  name: emergency-silence
  namespace: yuptime
spec:
  expiresAt: "2026-03-16T12:00:00Z"
  match:
    names:
      - namespace: yuptime
        name: critical-api
    tags:
      - production
  reason: "Emergency maintenance window"

CRD Reference

Yuptime defines 5 Custom Resource Definitions:

CRD	Description	Scope
Monitor	Single health check definition	Namespaced
MonitorSet	Bulk monitor definitions	Namespaced
MaintenanceWindow	Scheduled suppression (RRULE)	Namespaced
Silence	Ad-hoc alert muting	Namespaced
YuptimeSettings	Global configuration	Cluster

For complete API reference, see the documentation.

Alerting

Yuptime integrates directly with Prometheus Alertmanager:

apiVersion: monitoring.yuptime.io/v1
kind: Monitor
metadata:
  name: critical-api
  namespace: yuptime
spec:
  type: http
  schedule:
    intervalSeconds: 30
    timeoutSeconds: 10
  target:
    http:
      url: "https://api.example.com/health"
  alertmanagerUrl: "http://alertmanager.monitoring:9093/api/v2/alerts"
  alerting:
    notifyOn:
      down: true
      up: false

Metrics

Yuptime exposes Prometheus metrics on port 3000:

# Port forward and scrape metrics
kubectl port-forward -n yuptime svc/yuptime-api 3000:3000
curl http://localhost:3000/metrics

Key metrics:

• yuptime_monitor_status - Current monitor status (1=up, 0=down)
• yuptime_monitor_latency_seconds - Check latency histogram
• yuptime_monitor_checks_total - Total checks performed
• yuptime_monitor_failures_total - Total check failures

Development

# Clone and install
git clone https://github.com/briansunter/yuptime.git
cd yuptime
bun install

# Run development server
bun run dev

# Run tests
bun run test

# Type checking and linting
bun run type-check
bun run lint

See the Development Guide for more details.

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a Pull Request.

License

Apache License 2.0

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions