provisioning-catalog/providers/hetzner/README.md

# 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

```bash
# 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)

```bash
# 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`:

```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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```javascript
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

```bash
# 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**:

```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**

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

**Get Server Details**

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

**Create Server**

```bash
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**

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

### Pricing API

**Get Pricing Information**

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

### Locations API

**List All Locations**

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

### Server Types API

**List All Server Types**

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

## Troubleshooting

### Authentication Issues

**Problem**: "HCLOUD_TOKEN not set" or "Unauthorized"

**Solution**:

```bash
# 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:

```bash
provisioning providers info hetzner --detail locations
```

**Problem**: "SSH key not found"

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

```bash
# 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:

```toml
[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:

```bash
hcloud version

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

**Problem**: "hcloud: command not found"

**Solution**: Install hcloud CLI:

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

## Advanced Usage

### Private Networks

```javascript
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

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

### Firewalls

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

### Labels and Metadata

```bash
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

```bash
# 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