Prometheus Hetzner Storage Box Exporter

Modern Prometheus exporter for Hetzner Storage Box with comprehensive metrics

Quick Start • Metrics • Installation • Grafana Dashboard • Configuration

📋 Overview

A Prometheus exporter for Hetzner Storage Box using the modern Hetzner Cloud API.

• ✅ 15+ comprehensive metrics - Storage usage, access settings, snapshots, and protection status
• 🐳 Multi-architecture Docker - Images for amd64 and arm64
• ☸️ Kubernetes ready - Pre-built manifests included
• 🎯 Lightweight - Under 50MB memory usage
• 📈 Grafana dashboard - 21-panel dashboard ready to import (download)
• 🔒 Bearer token auth - Secure API authentication

Key Features

• All-in-one solution - Includes Docker images, K8s manifests, and Grafana dashboard
• Additional metrics - Access settings (SSH, Samba, WebDAV, ZFS), snapshot plans, and delete protection
• Production ready - Health checks, structured logging, and comprehensive error handling

📊 Dashboard Preview

Click on dashboard image to download the JSON file for import

🚀 Quick Start

Prerequisites

You need a Hetzner API token with read permissions:

1. Log in to Hetzner Cloud Console
2. Navigate to Security → API Tokens
3. Create a new token with Read permissions
4. Copy the token for configuration

Docker Compose (Recommended)

docker-compose up -d

Docker

docker run -d \
  --name storagebox-exporter \
  -p 9509:9509 \
  -e HETZNER_TOKEN="your-api-token" \
  ghcr.io/crstian19/prometheus-storagebox-exporter:latest

# With token file (recommended for NixOS)
echo "your-api-token" > /run/secrets/hetzner-token
docker run -d \
  --name storagebox-exporter \
  -p 9509:9509 \
  -v /run/secrets/hetzner-token:/run/secrets/hetzner-token:ro \
  -e HETZNER_TOKEN_FILE="/run/secrets/hetzner-token" \
  ghcr.io/crstian19/prometheus-storagebox-exporter:latest

🐳 Multi-Architecture Docker Images

Our Docker images are built for multiple architectures with automatic platform detection:

# Automatically pulls the right image for your platform:
docker pull ghcr.io/crstian19/prometheus-storagebox-exporter:latest

# Available architectures:
# - Linux amd64 (Intel/AMD)
# - Linux arm64 (ARM 64-bit)
# - macOS amd64 (Intel Mac)
# - macOS arm64 (Apple Silicon)

🏷️ Available Tags:

• latest - Latest release (multi-arch)
• v0.x.x - Specific version (multi-arch)
• latest-amd64 - Intel/AMD specific
• latest-arm64 - ARM specific

Binary

# Linux amd64
wget https://github.com/crstian19/prometheus-storagebox-exporter/releases/latest/download/prometheus-storagebox-exporter_linux_x86_64.tar.gz
tar xzf prometheus-storagebox-exporter_linux_x86_64.tar.gz

# Run with environment variable
export HETZNER_TOKEN="your-api-token"
./prometheus-storagebox-exporter

# Or with token file (recommended for NixOS)
echo "your-api-token" > /run/secrets/hetzner-token
export HETZNER_TOKEN_FILE="/run/secrets/hetzner-token"
./prometheus-storagebox-exporter

Access Metrics

Open http://localhost:9509/metrics to view the exported metrics.

⚙️ Configuration

Environment Variables

Command-line Flags

./prometheus-storagebox-exporter --help

Flags:
  --hetzner-token string           Hetzner API token (can also be set via HETZNER_TOKEN env var)
  --hetzner-token-file string      Path to file containing Hetzner API token (can also be set via HETZNER_TOKEN_FILE env var)
  --listen-address string          Address to listen on for HTTP requests (default ":9509")
  --metrics-path string            Path under which to expose metrics (default "/metrics")
  --log-level string               Log level (debug, info, warn, error) (default "info")
  --cache-ttl int                  Cache TTL in seconds, 0 to disable (can also be set via CACHE_TTL env var, default: 0 - disabled)
  --cache-max-size int64           Cache maximum size in bytes, 0 for unlimited (can also be set via CACHE_MAX_SIZE env var, default: 0 - unlimited)
  --cache-cleanup-interval int     Cache cleanup interval in seconds, 0 for default (can also be set via CACHE_CLEANUP_INTERVAL env var, default: 0 - 10s)
  --cache-storage-type string      Cache storage type (memory, redis) (can also be set via CACHE_STORAGE_TYPE env var, default: memory)
  --version                        Show version information and exit

Cache Configuration (Optional)

⚠️ Cache is disabled by default following Prometheus best practices. Use scrape_interval in Prometheus instead of caching for most use cases.

When to Enable Cache

• Multiple Prometheus instances: Prevent duplicate API calls
• Rate limiting concerns: Reduce API request frequency
• Development/Testing: Minimize API calls during testing

Cache Configuration Examples

# Enable cache with 60s TTL, 1MB size limit
export CACHE_TTL=60
export CACHE_MAX_SIZE=1048576
export CACHE_CLEANUP_INTERVAL=30

# Enable with memory limit only (10s cleanup interval)
export CACHE_TTL=120
export CACHE_MAX_SIZE=5242880

# Enable with custom cleanup interval
export CACHE_TTL=300
export CACHE_CLEANUP_INTERVAL=60

Prometheus Configuration (Recommended Alternative)

# prometheus.yml
scrape_configs:
  - job_name: 'storagebox-exporter'
    scrape_interval: 5m    # Control scraping frequency
    scrape_timeout: 30s
    static_configs:
      - targets: ['localhost:9509']

📊 Metrics

The exporter exposes 15+ metrics organized in 4 categories:

Core Storage Metrics

Information & Status Metrics

Access Settings Metrics

Protection & Snapshot Metrics

Exporter Metrics

Dashboard Features

• 📊 Overview Section: Gauges for disk usage percentage and disk space distribution
• 📈 Time Series Graphs:
  • Disk usage over time with quota visualization
  • Usage breakdown (Data vs Snapshots) with dual Y-axes
  • Disk usage percentage trends
  • Storage growth rate analysis (1h intervals)
• 📋 Detailed Table: Complete storage box details with all metrics
• 🔧 Access Status: Visual indicators for SSH, Samba, WebDAV, and ZFS access
• 🛡️ Configuration Info: Snapshot plan and delete protection status
• 📊 Multi-box Support: Variable to filter by specific storage box or view all

Quick test with Docker Compose

The repository includes a complete Docker Compose test with pre-configured dashboard:

# Start all services (Exporter + Prometheus + Grafana)
./test-env.sh

# Or manually:
docker-compose -f docker-compose.dev.yml up -d

Access points:

• 🎯 Grafana Dashboard: http://localhost:3000 (admin/admin) - Dashboard is pre-imported
• 📈 Prometheus: http://localhost:9090
• 🔧 Exporter: http://localhost:9509/metrics

💡 For production: Import the dashboard manually using grafana-dashboard.json

Dashboard Panels

The dashboard includes:

Access Settings Panels:

• SSH Access Status
• Samba Access Status
• WebDAV Access Status
• ZFS Access Status
• External Reachability Status

Configuration Panels:

• Storage Box Status
• Snapshot Plan Status
• Delete Protection Status

Details Table:

• Storage Box Details (comprehensive table)

🐳 Docker Deployment

Docker Compose

Complete docker-compose.yml example with Prometheus and Grafana:

version: '3.8'

services:
  # Storage Box Exporter
  storagebox-exporter:
    image: ghcr.io/crstian19/prometheus-storagebox-exporter:latest
    container_name: storagebox-exporter
    restart: unless-stopped
    ports:
      - "9509:9509"
    environment:
      - HETZNER_TOKEN=${HETZNER_TOKEN}
      # Optional cache configuration (uncomment to enable)
      # - CACHE_TTL=60
      # - CACHE_MAX_SIZE=1048576
      # - CACHE_CLEANUP_INTERVAL=30
    networks:
      - monitoring

  # Prometheus
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
      - '--web.console.templates=/usr/share/prometheus/consoles'
      - '--web.enable-lifecycle'
    networks:
      - monitoring
    depends_on:
      - storagebox-exporter

  # Grafana
  grafana:
    image: grafana/grafana:10.2.0
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana-provisioning:/etc/grafana/provisioning:ro
    networks:
      - monitoring
    depends_on:
      - prometheus

networks:
  monitoring:
    driver: bridge

volumes:
  prometheus-data:
  grafana-data:

Prometheus Configuration

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'hetzner-storagebox'
    static_configs:
      - targets: ['storagebox-exporter:9509']
    scrape_interval: 60s
    scrape_timeout: 30s

☸️ Kubernetes Deployment

Quick Deploy

# Apply all manifests
kubectl apply -f k8s/

# Check status
kubectl get pods -n monitoring

Manifests

apiVersion: v1
kind: Secret
metadata:
  name: storagebox-exporter-secret
  namespace: monitoring
type: Opaque
stringData:
  hetzner-token: "your-api-token-here"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: storagebox-exporter
  namespace: monitoring
  labels:
    app: storagebox-exporter
spec:
  replicas: 1
  selector:
    matchLabels:
      app: storagebox-exporter
  template:
    metadata:
      labels:
        app: storagebox-exporter
    spec:
      containers:
      - name: storagebox-exporter
        image: ghcr.io/crstian19/prometheus-storagebox-exporter:latest
        ports:
        - containerPort: 9509
          name: metrics
        env:
        - name: HETZNER_TOKEN
          valueFrom:
            secretKeyRef:
              name: storagebox-exporter-secret
              key: hetzner-token
        livenessProbe:
          httpGet:
            path: /health
            port: metrics
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: metrics
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            memory: "32Mi"
            cpu: "50m"
          limits:
            memory: "64Mi"
            cpu: "100m"
---
apiVersion: v1
kind: Service
metadata:
  name: storagebox-exporter
  namespace: monitoring
  labels:
    app: storagebox-exporter
spec:
  type: ClusterIP
  ports:
  - port: 9509
    targetPort: metrics
    name: metrics
  selector:
    app: storagebox-exporter
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: storagebox-exporter
  namespace: monitoring
  labels:
    app: storagebox-exporter
spec:
  selector:
    matchLabels:
      app: storagebox-exporter
  endpoints:
  - port: metrics
    interval: 60s
    scrapeTimeout: 30s

🏗️ Development

Setup

The toolchain is pinned with mise (mise.toml) and git hooks are managed with lefthook. One-time setup per clone:

mise install     # installs Go + golangci-lint + goreleaser + ko + lefthook + gitleaks
make setup       # installs the git hooks (lefthook install) and downloads deps

Hooks: pre-commit runs gitleaks + gofmt + incremental lint; pre-push runs the full make test and make lint — the same checks as CI, so failures surface locally first.

Building

# Build binary
make build            # or: go build -o prometheus-storagebox-exporter .

# Run tests / linter (same as CI)
make test
make lint

# Container image (no Dockerfile): built with ko via goreleaser on release.
# The Dockerfile is kept only for local `docker build` / docker-compose.
KO_DOCKER_REPO=ko.local ko build . --bare --platform=linux/amd64,linux/arm64

Project Structure

.
├── main.go                 # Application entry point
├── internal/
│   ├── collector/          # Prometheus collector implementation
│   ├── hetzner/           # Hetzner API client
│   └── config/            # Configuration handling
├── grafana-provisioning/  # Grafana dashboard provisioning
├── k8s/                   # Kubernetes manifests
├── .github/workflows/     # CI/CD pipelines
├── Dockerfile             # Multi-stage Docker build
├── docker-compose.yml     # Docker Compose configuration
├── docker-compose.dev.yml # Development environment
└── DESIGN.md             # Architecture documentation

🐛 Troubleshooting

Common Issues

# Option 1: Direct token
export HETZNER_TOKEN="your-token-here"
./prometheus-storagebox-exporter

# Option 2: Token from file (recommended for NixOS)
echo "your-token-here" > /run/secrets/hetzner-token
export HETZNER_TOKEN_FILE="/run/secrets/hetzner-token"
./prometheus-storagebox-exporter

# Correct: Use only one method
export HETZNER_TOKEN="your-token-here"
# or
export HETZNER_TOKEN_FILE="/path/to/token/file"

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Adding New Metrics

1. Update the collector in internal/collector/storagebox.go
2. Add metric definitions
3. Update the Grafana dashboard (grafana-dashboard.json) if needed
4. Update this README

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Technologies

• Hetzner Storage Box - Backup storage solution
• Hetzner Cloud API - Modern API infrastructure
• Prometheus - Monitoring toolkit and time series database
• Grafana - Analytics and monitoring platform
• Go - Programming language

Inspiration

• fleaz/prometheus-storagebox-exporter - Original implementation
• Prometheus exporter best practices

📞 Support

• Issues: Report a bug
• Features: Request a feature
• Security: Report a vulnerability
• Documentation: DESIGN.md for architecture details

💝 Donate

If you find this project useful and want to support its development, you can donate via PayPal:

Your support helps keep this project maintained and improved! 🙏