# lerentis/woodpecker-autoscaler architecture

> Architecture diagram of the GitHub repository lerentis/woodpecker-autoscaler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lerentis/woodpecker-autoscaler
- Repository: https://github.com/lerentis/woodpecker-autoscaler

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        WoodpeckerCI["Woodpecker CI API"]:::external
        HetznerCloud["Hetzner Cloud API"]:::external
        KubernetesAPI["Kubernetes API Server (optional)"]:::external
    end

    %% Autoscaler Service
    subgraph "Autoscaler Service"
        direction TB
        CLI["CLI Entry Point"]:::internal
        Config["Config Loader"]:::internal
        Health["HealthCheck Endpoint"]:::internal
        Collector["Metrics Collector"]:::internal
        Logic["Scaling Logic"]:::internal
        WoodpClient["WoodpeckerClient"]:::internal
        HetznerClient["HetznerClient"]:::internal
        Logger["Logging Setup"]:::internal
        Models["Shared Data Models"]:::internal
        Utils["Utility Functions"]:::internal
        DockerfileNode["Dockerfile"]:::infra
        HelmChart["Helm Chart"]:::infra
        CICDPipelines["CI/CD Pipelines"]:::infra
        Systemd["Systemd Service (Standalone)"]:::infra
    end

    %% Provisioned Agents
    subgraph "Provisioned Build Agents"
        direction TB
        VM["New Build Agent VM"]:::infra
    end

    %% Connections
    CLI -->|loads| Config
    CLI -->|runs loop| Logic
    Config -->|validates env| Models
    Config -->|uses utils| Utils
    Config -->|reads Secret| KubernetesAPI
    Systemd -->|reads env file| Config

    Logic -->|calls| WoodpClient
    Logic -->|calls| HetznerClient
    Logic -->|logs to| Logger
    Logic -->|uses models| Models

    WoodpClient -->|GET /queue,/agents| WoodpeckerCI
    HetznerClient -->|POST/DELETE servers| HetznerCloud

    VM -->|registers as agent| WoodpeckerCI

    DockerfileNode -->|builds image| CLI
    HelmChart -->|deploys Pod| KubernetesAPI
    CICDPipelines -->|CI run| DockerfileNode

    %% Click Events
    click CLI "https://github.com/lerentis/woodpecker-autoscaler/blob/main/cmd/woodpecker-autoscaler.go"
    click Config "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/config/config.go"
    click Health "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/health/healthcheck.go"
    click Collector "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/woodpecker/metrics.go"
    click WoodpClient "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/woodpecker/agent.go"
    click Logic "https://github.com/lerentis/woodpecker-autoscaler/blob/main/cmd/woodpecker-autoscaler.go"
    click HetznerClient "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/hetzner/hetzneragent.go"
    click Logger "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/logging/logging.go"
    click Models "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/models/structs.go"
    click Utils "https://github.com/lerentis/woodpecker-autoscaler/blob/main/internal/utils/utils.go"
    click DockerfileNode "https://github.com/lerentis/woodpecker-autoscaler/tree/main/Dockerfile"
    click HelmChart "https://github.com/lerentis/woodpecker-autoscaler/tree/main/chart/woodpecker-autoscaler"
    click CICDPipelines "https://github.com/lerentis/woodpecker-autoscaler/tree/main/.woodpecker/"
    
    %% Styles
    classDef external fill:#a2d5c6,stroke:#333,stroke-width:1px
    classDef internal fill:#9ec1cf,stroke:#333,stroke-width:1px
    classDef infra fill:#f4a261,stroke:#333,stroke-width:1px
```
