How lerentis/woodpecker-autoscaler works
Project type and purpose
• This is a Go-based autoscaler microservice whose job is to dynamically spawn and destroy Woodpecker CI build agents on Hetzner Cloud.
• It is packaged for deployment both as a standalone binary (with systemd) and as a Kubernetes workload via a Helm chart under chart/woodpecker-autoscaler.
File structure
• Top-level:
• cmd/woodpecker-autoscaler.go – entry point for the CLI/application.
• internal/ – core packages:
– config – loads and validates environment variables.
– health – exposes health-check endpoints.
– hetzner – encapsulates Hetzner Cloud API logic (create/delete servers).
– woodpecker – interfaces with the Woodpecker CI API (fetch queue size, agent metrics).
– models – shared data structures.
– logging – centralized logger setup.
– utils – helper functions.
• Deployment:
• Dockerfile – container image build.
• chart/woodpecker-autoscaler/ – Helm resources: Deployment, ServiceAccount, values.yaml, etc.
• CI/CD:
• .woodpecker/*.yml – Woodpecker pipeline definitions.
Extract architecture insights from the README
• The service polls the Woodpecker server at a configurable interval, calculates desired agent count, and uses the Hetzner API token to manage cloud servers.
• Deployment modes:
• Kubernetes (via Helm) – runs as a pod in namespace woodpecker-autoscaler.
• Standalone (systemd) – runs on any Linux host.
• Environment variables drive all configuration (tokens, thresholds, labels, instance types, etc.).
Main components and interactions
a. External systems (outside your cluster/host)
• Woodpecker CI Server & API
• Hetzner Cloud API
• (Optional) Kubernetes API server (if deployed on K8s)
b. Core autoscaler service (Pod or binary)
1. Config Loader
2. HealthCheck HTTP endpoint
3. Metrics Collector (Woodpecker API client)
4. Scaling Logic (calculates desired number of agents)
5. Hetzner Agent (Hetzner API client creates/deletes VMs)
6. Logging & Metrics exporter (stdout or Prometheus)
c. Build agents (new VMs)
• User-provided cloud-init script or image that registers itself as a Woodpecker agent with the Woodpecker server using the shared secret.
Architectural patterns and design principles
• Single responsibility: each internal package handles one domain (config, API clients, health, etc.).
• Poll-and-act loop: check interval → fetch metrics → scale actions.
• Externalized configuration: all secrets and parameters come from environment variables or Kubernetes secrets.
• Container-first deployment with Helm, but also supports classic systemd service.