Hetzner Cloud

Hetzner Cloud Integration

csp-benchmarks supports running benchmarks on dedicated Hetzner Cloud servers for consistent, reproducible results.

Why Hetzner Cloud?

• Consistent environment: Dedicated VMs provide stable performance
• Cost-effective: Pay only for benchmark time
• Automated: Full automation via CLI and GitHub Actions
• Reproducible: Same hardware configuration each run

Setup

1. Create Hetzner Cloud Account

1. Go to Hetzner Cloud Console
2. Create a new project
3. Generate an API token with read/write permissions

2. Configure Authentication

Set the HCLOUD_TOKEN environment variable:

export HCLOUD_TOKEN="your-api-token-here"

For GitHub Actions, add it as a repository secret.

3. SSH Key Setup (Required)

SSH keys must be pre-registered in Hetzner Cloud:

1. Generate an SSH key pair:

   ssh-keygen -t ed25519 -f ~/.ssh/hetzner_key -N ""

2. Add the public key to Hetzner Cloud Console with name benchmarks
3. Use the CLI with both paths:

   --ssh-key ~/.ssh/hetzner_key --ssh-key-name benchmarks

For GitHub Actions, add the private key content as secret HETZNER_SSH_PRIVATE_KEY.

CLI Usage

Run Benchmarks

# Basic run (requires SSH key already in Hetzner)
python -m csp_benchmarks.hetzner.cli run --ssh-key-name benchmarks

# With options
python -m csp_benchmarks.hetzner.cli run \
    --server-type cx43 \
    --commits "HEAD~5..HEAD" \
    --push

Options

Option	Description	Default
--token	Hetzner API token	$HCLOUD_TOKEN
--server-name	Server name	csp-benchmark-runner
--server-type	Server size	cx23
--ssh-key	Path to SSH private key	None
--ssh-key-name	Hetzner SSH key name	None
--branches	Branches to benchmark	main
--commits	Commit range	None
--reuse	Reuse existing server	False
--keep-server	Keep server after run	False
--push	Push results to repo	False

Cleanup

Remove leftover servers:

python -m csp_benchmarks.hetzner.cli cleanup

Server Types

Type	vCPU	RAM	Use Case
cx23	2	4GB	Quick tests (default)
cx43	8	16GB	Standard benchmarks

GitHub Actions

The benchmarks workflow automatically uses Hetzner Cloud:

# .github/workflows/benchmarks.yaml
- name: Run benchmarks on Hetzner
  env:
    HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
  run: |
    python -m csp_benchmarks.hetzner.cli run --push

Required Secrets

Secret	Description
HCLOUD_TOKEN	Hetzner Cloud API token
HETZNER_SSH_PRIVATE_KEY	SSH private key (optional)

Architecture

┌─────────────────┐
│  GitHub Action  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  CLI Runner     │────▶│  Hetzner Cloud  │
└─────────────────┘     └────────┬────────┘
                                 │
         ┌───────────────────────┘
         ▼
┌─────────────────┐
│  Ubuntu Server  │
│  - Clone repo   │
│  - Run ASV      │
│  - Push results │
└─────────────────┘

Troubleshooting

Server Creation Fails

• Check API token permissions
• Verify server type is available in the selected location
• Check Hetzner Cloud quotas

SSH Connection Fails

• Ensure the server has finished provisioning (cloud-init)
• Verify SSH key is correctly configured
• Check firewall rules in Hetzner Cloud

Benchmarks Fail

• Check CSP build dependencies are installed
• Verify Python version compatibility
• Review cloud-init logs: ssh root@<ip> cat /var/log/cloud-init-output.log

Cost Estimation

Approximate costs (as of 2026):

Server	Hourly	Monthly
cx23	€0.006	€3.49
cx43	€0.015	€9.49

Servers are automatically deleted after benchmarks complete.