hetzner-cloud-management

What this skill does

# Hetzner Cloud Management

Comprehensive management of Hetzner Cloud infrastructure using the official `hcloud` CLI. Covers servers, networks, firewalls, load balancers, volumes, floating IPs, and automation workflows.

## Quick Reference

| Task | Command | Notes |
|------|---------|-------|
| **Create Server** | `hcloud server create --name <name> --type <type> --image <image>` | Add `--ssh-key`, `--network`, `--firewall` for production |
| **List Servers** | `hcloud server list` | Use `--output json` for scripting |
| **Server Control** | `hcloud server [poweron\|shutdown\|reboot\|reset] <name>` | `reset` is hard reset |
| **SSH Access** | `hcloud server ssh <name>` | Direct SSH connection |
| **Create Snapshot** | `hcloud server create-image <name> --type snapshot` | For backups before changes |
| **Create Network** | `hcloud network create --name <name> --ip-range <cidr>` | Private networking |
| **Create Firewall** | `hcloud firewall create --name <name> --rules-file <file>` | JSON format for rules |
| **Create Load Balancer** | `hcloud load-balancer create --name <name> --type <type>` | Add services and targets after |
| **Context Switch** | `hcloud context use <context>` | Multi-project management |
| **JSON Output** | `hcloud <command> --output json` | Pipe to `jq` for parsing |

## Command Categories

The `hcloud` CLI is organized into these main resource types:

| Category | Purpose | Key Commands |
|----------|---------|--------------|
| **server** | Virtual machines | create, list, delete, poweron, shutdown, ssh, create-image |
| **network** | Private networks | create, add-subnet, add-route, expose-routes-to-vswitch |
| **firewall** | Security rules | create, add-rule, apply-to-resource, replace-rules |
| **load-balancer** | Traffic distribution | create, add-service, add-target, change-algorithm |
| **volume** | Block storage | create, attach, detach, resize |
| **floating-ip** | Static IPs | create, assign, unassign, set-rdns |
| **ssh-key** | SSH key management | create, list, delete |
| **placement-group** | Server distribution | create spread, create anti-affinity |
| **primary-ip** | IP management | create, assign, unassign |
| **certificate** | SSL/TLS certs | create, list, delete |
| **datacenter** | View datacenters | list, describe |
| **location** | View locations | list, describe |
| **server-type** | View server types | list, describe |
| **image** | OS images | list, describe, delete |
| **context** | Multi-project auth | create, list, use, active, delete |

## Installation

### Install hcloud CLI

```bash
# macOS (Homebrew)
brew install hcloud

# Linux (snap)
sudo snap install hcloud

# Or download binary from GitHub releases
# https://github.com/hetznercloud/cli/releases
```

### Verify Installation

```bash
hcloud version
# Expected: hcloud v1.60.0 or later
```

## Authentication

### Workflow 1: Initial Setup with API Token

```bash
# 1. Get API token from Hetzner Cloud Console
# https://console.hetzner.cloud → Project → Security → API Tokens
# Create Read & Write token (64 characters)

# 2. Create context (interactive)
hcloud context create my-project
# Paste token when prompted

# 3. Verify authentication
hcloud server list

# 4. Show active context
hcloud context active
```

### Workflow 2: Multiple Projects (Context Management)

```bash
# Create contexts for different projects
hcloud context create production
# Enter production token

hcloud context create staging
# Enter staging token

# List all contexts
hcloud context list

# Switch between contexts
hcloud context use production
hcloud server list  # Lists production servers

hcloud context use staging
hcloud server list  # Lists staging servers

# Show active context
hcloud context active
```

### Workflow 3: CI/CD Authentication (Environment Variable)

```bash
# Export token (no config file created)
export HCLOUD_TOKEN="your-64-character-api-token"

# Run commands
hcloud server list

# In CI/CD pipelines (GitHub Actions example)
- name: Deploy to Hetzner
  env:
    HCLOUD_TOKEN: ${{ secrets.HETZNER_TOKEN }}
  run: |
    hcloud server create --name ci-server --type cpx11 --image ubuntu-24.04
```

### Configuration File Location

**Default**: `~/.config/hcloud/cli.toml`

```toml
# Global settings
active_context = "production"

[[contexts]]
  name = "production"
  token = "your-64-char-token"
  
[[contexts]]
  name = "staging"
  token = "another-64-char-token"
```

## Server Management

### Workflow 4: Create Basic Server

```bash
# Minimal server creation
hcloud server create \
  --name my-server \
  --type cpx11 \
  --image ubuntu-24.04 \
  --location fsn1

# Server types (common):
# cpx11  - 2 vCPU, 2 GB RAM (shared)
# cpx21  - 3 vCPU, 4 GB RAM (shared)
# cpx31  - 4 vCPU, 8 GB RAM (shared)
# cpx41  - 8 vCPU, 16 GB RAM (shared)
# ccx13  - 2 vCPU, 8 GB RAM (dedicated)
# ccx23  - 4 vCPU, 16 GB RAM (dedicated)

# Locations:
# fsn1 - Falkenstein, Germany
# nbg1 - Nuremberg, Germany
# hel1 - Helsinki, Finland
# ash - Ashburn, USA
# hil - Hillsboro, USA

# Images:
# ubuntu-24.04, ubuntu-22.04
# debian-12, debian-11
# fedora-40, rocky-9, alma-9
```

### Workflow 5: Create Production Server

```bash
# 1. Create SSH key first (if not exists)
hcloud ssh-key create \
  --name deploy-key \
  --public-key-from-file ~/.ssh/id_rsa.pub

# 2. Create network (for private networking)
hcloud network create --name app-network --ip-range 10.0.0.0/16
hcloud network add-subnet app-network \
  --type cloud \
  --network-zone eu-central \
  --ip-range 10.0.1.0/24

# 3. Create firewall rules file
cat > firewall-rules.json <<'EOF'
{
  "rules": [
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ips": ["0.0.0.0/0", "::/0"],
      "description": "SSH"
    },
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "80",
      "source_ips": ["0.0.0.0/0", "::/0"],
      "description": "HTTP"
    },
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "443",
      "source_ips": ["0.0.0.0/0", "::/0"],
      "description": "HTTPS"
    }
  ]
}
EOF

# 4. Create firewall
hcloud firewall create --name web-firewall --rules-file firewall-rules.json

# 5. Create server with all options
hcloud server create \
  --name web-01 \
  --type cpx21 \
  --image ubuntu-24.04 \
  --location fsn1 \
  --ssh-key deploy-key \
  --network app-network \
  --firewall web-firewall \
  --labels environment=production,service=web,team=platform \
  --enable-backup \
  --user-data-from-file cloud-init.yaml

# 6. Enable deletion protection
hcloud server enable-protection web-01 --delete

# 7. Get server details
hcloud server describe web-01
```

### Workflow 6: Server Control Operations

```bash
# Power operations
hcloud server poweron my-server      # Start server
hcloud server shutdown my-server     # Graceful shutdown (ACPI)
hcloud server reboot my-server       # Graceful reboot
hcloud server reset my-server        # Hard reset (force)

# Check status
hcloud server describe my-server --output json | jq -r '.status'

# Enable/disable rescue mode
hcloud server enable-rescue my-server --ssh-key deploy-key
hcloud server reboot my-server  # Boot into rescue
# ... do maintenance ...
hcloud server disable-rescue my-server
hcloud server reboot my-server  # Boot normally

# SSH access
hcloud server ssh my-server

# SSH with custom user
hcloud server ssh my-server --user root

# Get server IP
hcloud server describe my-server --output json | jq -r '.public_net.ipv4.ip'
```

### Workflow 7: Snapshots and Backups

```bash
# Create snapshot (manual backup)
hcloud server create-image my-server \
  --type snapshot \
  --description "Before upgrade to v2.0" \
  --labels version=1.9,backup_type=manual

# Enable automatic backups (daily, 7-day retention)
hcloud server enable-backup my-server

# Disable backups
hcloud server disable-backup my-server

# List snapshots
hcloud image list --type snapshot

# List backups
hcloud image list --type backup

# Delete old snapshot