Autoscaler

Scale your woodpecker agents automatically to the moon and back based on the current load.

Usage

If you are using docker-compose you can add the following to your docker-compose.yml file:

# docker-compose.yml
version: '3'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:next
    [...]

  woodpecker-autoscaler:
    image: woodpeckerci/autoscaler:next
    restart: always
    depends_on:
      - woodpecker-server
    environment:
      - WOODPECKER_SERVER=https://your-woodpecker-server.tld # the url of your woodpecker server / could also be a public url
      - WOODPECKER_TOKEN=${WOODPECKER_TOKEN} # the api token you can get from the UI https://your-woodpecker-server.tld/user
      - WOODPECKER_MIN_AGENTS=0
      - WOODPECKER_MAX_AGENTS=3
      - WOODPECKER_WORKFLOWS_PER_AGENT=2 # the number of workflows each agent can run at the same time
      - WOODPECKER_GRPC_ADDR=https://grpc.your-woodpecker-server.tld # the grpc address of your woodpecker server, publicly accessible from the agents
      - WOODPECKER_GRPC_SECURE=true
      - WOODPECKER_AGENT_ENV= # optional environment variables to pass to the agents
      - WOODPECKER_PROVIDER=hetznercloud # set the provider, you can find all the available ones down below
      - WOODPECKER_HETZNERCLOUD_API_TOKEN=${WOODPECKER_HETZNERCLOUD_API_TOKEN} # your api token for the Hetzner cloud

The agents will use WOODPECKER_GRPC_ADDR and a token automatically generated by the autoscaler to connect to the server.Therefore the WOODPECKER_GRPC_ADDR has to be publicly accessible from the newly created agents. Check for example how you could use caddy to expose the grpc connection.

Equinix Metal

Set WOODPECKER_PROVIDER=equinixmetal and configure at least:

• WOODPECKER_EQUINIXMETAL_API_TOKEN
• WOODPECKER_EQUINIXMETAL_PROJECT_ID
• WOODPECKER_EQUINIXMETAL_PLAN
• exactly one of WOODPECKER_EQUINIXMETAL_METRO or WOODPECKER_EQUINIXMETAL_FACILITY

Equinix Metal support is currently experimental: it has not been tested by the project maintainers, as none of them have real provider access.

Useful optional settings:

• WOODPECKER_EQUINIXMETAL_OPERATING_SYSTEM (default: ubuntu_24_04)
• WOODPECKER_EQUINIXMETAL_BILLING_CYCLE (default: hourly)
• WOODPECKER_EQUINIXMETAL_TAGS
• WOODPECKER_EQUINIXMETAL_PROJECT_SSH_KEYS
• WOODPECKER_EQUINIXMETAL_SPOT_INSTANCE
• WOODPECKER_EQUINIXMETAL_SPOT_PRICE_MAX

Teardown policy

How idle agents are torn down depends on how the selected provider bills:

• Per-second billing (e.g. AWS, Scaleway): an idle agent is drained and removed once it has been idle for WOODPECKER_AGENT_IDLE_TIMEOUT. Holding an idle agent open buys nothing.

• Hourly-rounded-up billing (e.g. Linode, Hetzner Cloud, Vultr): a partial hour costs the same as a full one, so an idle agent is kept schedulable for the rest of the hour that has already been paid for and is only torn down just before its next hour boundary (anchored at its creation time). A busy agent simply rolls into the next paid hour; you never pay for an idle hour.

  The teardown window is WOODPECKER_AGENT_BILLING_TEARDOWN_MARGIN (default 2m) plus WOODPECKER_RECONCILIATION_INTERVAL, so a reconciliation can never tick straight past the boundary. With the defaults (2m margin, 1m interval) an idle agent becomes eligible for teardown in the last 3 minutes of each paid hour.

The billing model is selected automatically by the provider, so no extra configuration is required to benefit from this.

Roadmap

• Add support for multiple providers
  • Hetzner Cloud
  • Amazon AWS
  • Google Cloud
  • Azure
  • Digital Ocean
  • Linode
  • Oracle Cloud
  • Equinix Metal [experimental] (untested by the maintainers against real provider access, see above)
  • Vultr
  • Scaleway
• Cleanup agents
  • Remove agents which exist on the provider but are not in the server list (they wont be able to connect to the server anyway as their is no agent token for them)
  • Remove agents from server list which do not exist on the provider
  • Remove agents which have not connected for a long time
• Release as container image
• Add docs
• Support agent deployment with specific attributes (e.g. platforms, architectures, etc.)