provisioning-catalog/providers/hetzner

Hetzner Cloud Provider

A comprehensive provider implementation for Hetzner Cloud infrastructure automation, enabling seamless integration with the provisioning platform.

Overview

The Hetzner Cloud provider enables management of:

• Server Infrastructure: Create, delete, resize, and manage cloud servers
• Private Networking: Configure private networks and VPCs
• Block Storage: Attach and manage persistent volumes
• Firewalls: Define and manage firewall rules
• Load Balancing: Configure load balancers
• Floating IPs: Manage floating IP addresses
• Placement Groups: Organize servers with placement policies

Features

Core Capabilities

• ✅ Server lifecycle management (create, delete, start, stop, restart)
• ✅ Dual interface support (HTTP API + hcloud CLI)
• ✅ Private network configuration
• ✅ Block storage volume management
• ✅ Pricing calculations (hourly/monthly)
• ✅ Intelligent caching for performance
• ✅ Type-safe Nickel schemas
• ✅ Interactive code generation

Supported Locations

Code	Name	Country
fsn1	Falkenstein	Germany
nbg1	Nuremberg	Germany
hel1	Helsinki	Finland
ash	Ashburn	USA
hil	Hillsboro	USA

Server Types

Shared vCPU (CX Series)

• cx11: 1 vCPU, 2GB RAM, 20GB SSD
• cx21: 2 vCPU, 4GB RAM, 40GB SSD
• cx31: 2 vCPU, 8GB RAM, 80GB SSD
• cx41: 4 vCPU, 16GB RAM, 160GB SSD
• cx51: 8 vCPU, 32GB RAM, 240GB SSD

Dedicated vCPU (CPX Series)

• cpx11: 2 vCPU, 2GB RAM, 40GB SSD
• cpx21: 3 vCPU, 4GB RAM, 80GB SSD
• cpx31: 4 vCPU, 8GB RAM, 160GB SSD
• cpx41: 8 vCPU, 16GB RAM, 240GB SSD
• cpx51: 16 vCPU, 32GB RAM, 360GB SSD

Dedicated CPU (CCX Series)

• ccx13: 2 cores, 8GB RAM, 80GB SSD
• ccx23: 4 cores, 16GB RAM, 160GB SSD
• ccx33: 8 cores, 32GB RAM, 240GB SSD
• ccx43: 16 cores, 64GB RAM, 360GB SSD
• ccx53: 32 cores, 128GB RAM, 960GB SSD

Prerequisites

Required

• Hetzner Cloud Account: Create at https://console.hetzner.cloud
• API Token: Generate in Cloud Console → API Tokens
• Nushell: 0.109.0 or higher

Optional

• hcloud CLI: For CLI-based operations (install from https://github.com/hetznercloud/cli)
• SSH Keys: Pre-configured in Hetzner Cloud Console for authentication

Installation

1. Set Up API Token

# Store API token securely using SOPS
sops -e ~/.config/provisioning/hetzner-secrets.yaml

# Add to secrets file:
# hetzner:
#   api_token: "your_token_here"

# Or set environment variable:
export HCLOUD_TOKEN="your_token_here"

2. Install hcloud CLI (Optional)

# Using the provided installation script
cd provisioning/extensions/providers/hetzner/bin
./install.sh

# Or install manually
# macOS
brew install hcloud

# Ubuntu/Debian
apt-get install hcloud

# From source
https://github.com/hetznercloud/cli/releases

3. Configure Provider

Create or update workspace/config/providers/hetzner.toml:

[provider]
name = "hetzner"
enabled = true
workspace = "production"

[provider.auth]
interface = "API"  # API or CLI
# Token from environment: HCLOUD_TOKEN
# or secrets: sops://hetzner/api_token

[provider.defaults]
location = "nbg1"
server_type = "cx11"
image = "ubuntu-22.04"

[provider.api]
url = "https://api.hetzner.cloud/v1"
timeout = 30
retry_attempts = 3

[provider.features]
enable_private_network = true
enable_volumes = true
enable_firewall = true
enable_load_balancer = true

Usage Examples

List Available Resources

# List all Hetzner servers
provisioning server list --provider hetzner

# List locations
provisioning providers info hetzner --detail locations

# List server types
provisioning providers info hetzner --detail server_types

Create Server

# Interactive generation
provisioning generate server hetzner

# Create server with defaults
provisioning server create web-01 
  --provider hetzner 
  --location nbg1 
  --server-type cx11

# Create with options
provisioning server create web-01 
  --provider hetzner 
  --location nbg1 
  --server-type cx21 
  --image ubuntu-22.04 
  --ssh-key my-key

# Dry-run (check mode)
provisioning server create web-01 
  --provider hetzner 
  --check

Server Management

# Get server details
provisioning server info web-01 --provider hetzner

# Start server
provisioning server start web-01 --provider hetzner

# Stop server
provisioning server stop web-01 --provider hetzner

# Reboot server
provisioning server reboot web-01 --provider hetzner

# Delete server
provisioning server delete web-01 --provider hetzner

# Delete with volumes
provisioning server delete web-01 
  --provider hetzner 
  --delete-storage

SSH Connections

# SSH into server (automatic IP detection)
provisioning server ssh web-01 --provider hetzner

# SSH with custom user
provisioning server ssh web-01 
  --provider hetzner 
  --user root

# SSH with specific port
provisioning server ssh web-01 
  --provider hetzner 
  --port 2222

Nickel Configuration

Define servers in Nickel with full type safety:

let hetzner = import "hetzner/server_hetzner.ncl" in

let servers = [
  {
    hostname = "web-01",
    server_type = "cx21",
    location = "nbg1",
    image = "ubuntu-22.04",

    volumes = [
      {
        name = "data-01",
        size = 100,
        format = "ext4",
        automount = true
      }
    ],

    networks = [
      {
        name = "private-01",
        ip = "10.0.0.10"
      }
    ],

    labels = {
      env = "production",
      app = "web"
    },

    backups = true
  }
] in servers

Configuration Reference

Environment Variables

# API Authentication
export HCLOUD_TOKEN="token_here"

# Interface selection
export HCLOUD_INTERFACE="API"  # API or CLI

# API URL (usually not needed)
export HCLOUD_API_URL="https://api.hetzner.cloud/v1"

# Timeout settings
export PROVISIONING_PROVIDER_HETZNER_TIMEOUT=30
export PROVISIONING_PROVIDER_HETZNER_RETRY_ATTEMPTS=3

Configuration Hierarchy

Settings are loaded in priority order (highest wins):

1. Runtime Arguments: CLI flags (--location nbg1)
2. Environment Variables: PROVISIONING_PROVIDER_HETZNER_*
3. User Config: workspace/config/providers/hetzner.toml
4. System Defaults: provisioning/extensions/providers/hetzner/config.defaults.toml

Config File Structure

workspace/config/providers/hetzner.toml:

[provider]
name = "hetzner"
enabled = true

[provider.auth]
interface = "API"

[provider.defaults]
location = "nbg1"
server_type = "cx11"
image = "ubuntu-22.04"

[provider.api]
url = "https://api.hetzner.cloud/v1"
timeout = 30
retry_attempts = 3
rate_limit = 10

[provider.features]
enable_private_network = true
enable_volumes = true
enable_firewall = true
enable_load_balancer = true

API Reference

Server Operations

List Servers

curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/servers

Get Server Details

curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/servers/{id}

Create Server

curl -X POST 
  -H "Authorization: Bearer $HCLOUD_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "web-01",
    "server_type": "cx11",
    "image": "ubuntu-22.04",
    "location": "nbg1",
    "start_after_create": true
  }' 
  https://api.hetzner.cloud/v1/servers

Delete Server

curl -X DELETE 
  -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/servers/{id}

Pricing API

Get Pricing Information

curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/pricing

Locations API

List All Locations

curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/locations

Server Types API

List All Server Types

curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/server_types

Troubleshooting

Authentication Issues

Problem: "HCLOUD_TOKEN not set" or "Unauthorized"

Solution:

# Check token is set
echo $HCLOUD_TOKEN

# Test token validity
curl -H "Authorization: Bearer $HCLOUD_TOKEN" 
  https://api.hetzner.cloud/v1/locations | head -20

# Generate new token in Cloud Console
# Settings → API Tokens → Generate Token

Server Creation Fails

Problem: "Server type not available in location"

Solution: Not all server types are available in all locations. Check availability:

provisioning providers info hetzner --detail locations

Problem: "SSH key not found"

Solution: Pre-upload SSH keys in Hetzner Cloud Console:

# List available SSH keys
hcloud ssh-key list

# Add new SSH key
hcloud ssh-key create --name my-key --public-key-from-file ~/.ssh/id_rsa.pub

Performance Issues

Problem: Slow operations

Solution: Enable caching:

[provider.caching]
enabled = true
ttl_seconds = 3600  # Cache for 1 hour

CLI vs API Issues

Problem: Commands work with API but fail with CLI

Solution: Check hcloud CLI version:

hcloud version

# Update hcloud CLI
brew upgrade hcloud  # macOS
apt-get upgrade hcloud  # Ubuntu

Problem: "hcloud: command not found"

Solution: Install hcloud CLI:

provisioning/extensions/providers/hetzner/bin/install.sh

Advanced Usage

Private Networks

let networks = [
  {
    name = "backend-01",
    ip = "10.0.0.10",
    alias_ips = ["10.0.0.11", "10.0.0.12"]
  }
] in networks

Block Storage Volumes

let volumes = [
  {
    name = "data-01",
    size = 100,   # GB
    location = "nbg1",
    format = "ext4",
    automount = true,
    delete_on_termination = false
  }
] in volumes

Firewalls

let firewalls = [
  {
    name = "web-firewall",
    apply_to = ["app=web"]
  }
] in firewalls

Labels and Metadata

labels = {
    env = "production"
    app = "web"
    team = "platform"
    managed_by = "provisioning"
}

Pricing

Hetzner Cloud pricing (EUR):

Server Type	Hourly	Monthly
cx11	€0.0070	€3.29
cx21	€0.0140	€6.58
cx31	€0.0280	€13.16
cpx11	€0.0140	€6.58
cpx21	€0.0300	€14.07
ccx13	€0.0410	€19.29
ccx23	€0.0820	€38.59

Storage Pricing:

• Volumes: €0.0850/GB/month
• Backup: Free (1 automatic backup per server)
• Snapshots: €0.0850/GB/month

See https://www.hetzner.com/cloud/pricing for current pricing.

Development

Testing Provider

# Test provider discovery
provisioning providers discover
provisioning providers list | grep hetzner

# Test provider info
provisioning providers info hetzner

# Test server operations (dry-run)
provisioning server list --provider hetzner --check
provisioning server create test-01 --provider hetzner --check

# Test with real infrastructure
export HCLOUD_TOKEN="your_token"
provisioning server create test-01 --provider hetzner --server-type cx11 --location nbg1
provisioning server list --provider hetzner
provisioning server delete test-01 --provider hetzner

Adding New Features

1. Extend Nickel schemas in schemas/defaults_hetzner.ncl
2. Implement support functions in nulib/hetzner/
3. Add interface functions to provider.nu
4. Add tests in tests/
5. Update documentation

API Documentation

Official Documentation: https://docs.hetzner.cloud/ CLI Documentation: https://github.com/hetznercloud/cli Pricing: https://www.hetzner.com/cloud/pricing Status: https://status.hetzner.cloud/

Support

For issues and questions:

1. Check this README
2. Review troubleshooting section
3. Check provider logs: tail -f workspace/.providers/hetzner/logs/operations.log
4. Enable debug mode: PROVISIONING_DEBUG=true

Version History

v1.0.0 (2025)

• Initial release
• Server management (create, delete, list, info)
• Private networking support
• Block storage (volumes)
• Pricing calculations
• Caching system
• Nickel schema definitions
• Code generation templates
• Interactive configuration
• Dual API/CLI interface

License

MIT - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Follow Nushell style guide
2. Add tests for new features
3. Update documentation
4. Submit PR with detailed description