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

# 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

hcloud version
# Expected: hcloud v1.60.0 or later

Authentication

Workflow 1: Initial Setup with API Token

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

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

# 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

# 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

# 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

# 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

# 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

# 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
hcloud image delete snapshot-123456

# Restore from snapshot (create new server from image)
hcloud server create \
  --name my-server-restored \
  --image snapshot-123456 \
  --type cpx21 \
  --location fsn1

Workflow 8: Server Scaling and Resize

# List available server types
hcloud server-type list

# Power off server (required for resize)
hcloud server shutdown my-server

# Wait for shutdown
while [ "$(hcloud server describe my-server -o json | jq -r '.status')" != "off" ]; do
  echo "Waiting for shutdown..."
  sleep 2
done

# Change server type (upgrade/downgrade)
hcloud server change-type my-server --upgrade-disk cpx31

# Power on
hcloud server poweron my-server

# Note: --upgrade-disk increases disk size permanently (cannot shrink)
# Without --upgrade-disk, disk size stays the same

Network Infrastructure

Workflow 9: Private Network Setup

# 1. Create private network
hcloud network create \
  --name app-network \
  --ip-range 10.0.0.0/16 \
  --labels environment=production

# 2. Add cloud subnet (for Hetzner Cloud servers)
hcloud network add-subnet app-network \
  --type cloud \
  --network-zone eu-central \
  --ip-range 10.0.1.0/24

# 3. Add another subnet for different services
hcloud network add-subnet app-network \
  --type cloud \
  --network-zone eu-central \
  --ip-range 10.0.2.0/24

# 4. Add route (for external gateway)
hcloud network add-route app-network \
  --destination 192.168.0.0/16 \
  --gateway 10.0.1.1

# 5. Attach existing server to network
hcloud server attach-to-network my-server \
  --network app-network \
  --ip 10.0.1.10

# 6. Detach server from network
hcloud server detach-from-network my-server --network app-network

# 7. List network details
hcloud network describe app-network

Workflow 10: Firewall Management

# 1. Create firewall with rules file
cat > app-firewall.json <<'EOF'
{
  "rules": [
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ips": ["YOUR_IP/32"],
      "description": "SSH from office"
    },
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "443",
      "source_ips": ["0.0.0.0/0", "::/0"],
      "description": "HTTPS"
    },
    {
      "direction": "in",
      "protocol": "icmp",
      "source_ips": ["0.0.0.0/0", "::/0"],
      "description": "Ping"
    }
  ]
}
EOF

hcloud firewall create --name app-firewall --rules-file app-firewall.json

# 2. Apply firewall to server
hcloud firewall apply-to-resource app-firewall \
  --type server \
  --server web-01

# 3. Apply firewall to all servers with label
hcloud firewall apply-to-resource app-firewall \
  --type label \
  --label environment=production

# 4. Add individual rule
hcloud firewall add-rule app-firewall \
  --direction in \
  --protocol tcp \
  --port 8080 \
  --source-ips 10.0.0.0/16 \
  --description "Internal API"

# 5. Remove rule (by index, get from describe)
hcloud firewall describe app-firewall
hcloud firewall delete-rule app-firewall --index 2

# 6. Replace all rules
hcloud firewall replace-rules app-firewall --rules-file new-rules.json

# 7. Remove firewall from resource
hcloud firewall remove-from-resource app-firewall \
  --type server \
  --server web-01

# 8. List firewalls
hcloud firewall list

Workflow 11: Load Balancer Setup

# 1. Create load balancer
hcloud load-balancer create \
  --name app-lb \
  --type lb11 \
  --location fsn1 \
  --labels service=frontend

# Load balancer types:
# lb11 - Up to 20,000 connections
# lb21 - Up to 40,000 connections
# lb31 - Up to 60,000 connections

# 2. Add HTTP service
hcloud load-balancer add-service app-lb \
  --protocol http \
  --listen-port 80 \
  --destination-port 8080 \
  --http-sticky-sessions

# 3. Add HTTPS service with certificate
hcloud certificate create \
  --name app-cert \
  --type managed \
  --domain example.com \
  --domain www.example.com

hcloud load-balancer add-service app-lb \
  --protocol https \
  --listen-port 443 \
  --destination-port 8080 \
  --http-certificates app-cert \
  --http-sticky-sessions \
  --http-redirect-http

# 4. Add health check
hcloud load-balancer update-service app-lb \
  --listen-port 80 \
  --health-check-protocol http \
  --health-check-port 8080 \
  --health-check-interval 15 \
  --health-check-timeout 10 \
  --health-check-retries 3 \
  --health-check-http-path /health

# 5. Add server targets
hcloud load-balancer add-target app-lb --type server --server web-01
hcloud load-balancer add-target app-lb --type server --server web-02

# 6. Or add target by label (auto-includes all matching servers)
hcloud load-balancer add-target app-lb \
  --type label \
  --label service=web

# 7. Change algorithm
hcloud load-balancer change-algorithm app-lb --type round_robin
# Options: round_robin, least_connections

# 8. Get metrics
hcloud load-balancer metrics app-lb --type open_connections
hcloud load-balancer metrics app-lb --type requests_per_second

# 9. Enable deletion protection
hcloud load-balancer enable-protection app-lb --delete

Storage Management

Workflow 12: Volume Management

# 1. Create volume
hcloud volume create \
  --name data-vol \
  --size 50 \
  --location fsn1 \
  --format ext4 \
  --labels service=database

# 2. Attach volume to server
hcloud volume attach data-vol --server db-01

# 3. Mount volume (on server)
# SSH into server and mount
hcloud server ssh db-01
sudo mkdir -p /mnt/data
sudo mount /dev/disk/by-id/scsi-0HC_Volume_* /mnt/data

# 4. Detach volume
hcloud volume detach data-vol

# 5. Resize volume (server must be off or volume detached)
hcloud volume resize data-vol --size 100

# 6. Enable protection
hcloud volume enable-protection data-vol --delete

# 7. List volumes
hcloud volume list

# 8. Delete volume
hcloud volume delete data-vol

Workflow 13: Floating IP Management

# 1. Create floating IP
hcloud floating-ip create \
  --type ipv4 \
  --home-location fsn1 \
  --description "Primary web IP" \
  --labels service=web

# 2. Create IPv6
hcloud floating-ip create \
  --type ipv6 \
  --home-location fsn1

# 3. Assign to server
hcloud floating-ip assign 1.2.3.4 --server web-01

# 4. Configure on server (manual step)
# SSH into server and add IP to network interface
hcloud server ssh web-01
sudo ip addr add 1.2.3.4/32 dev eth0

# 5. Set reverse DNS
hcloud floating-ip set-rdns 1.2.3.4 --hostname web.example.com

# 6. Unassign from server
hcloud floating-ip unassign 1.2.3.4

# 7. Enable protection
hcloud floating-ip enable-protection 1.2.3.4 --delete

# 8. List floating IPs
hcloud floating-ip list

Automation Patterns

Workflow 14: Complete Infrastructure Provisioning

#!/bin/bash
set -euo pipefail

# Configuration
PROJECT="my-app"
LOCATION="fsn1"
NETWORK_CIDR="10.0.0.0/16"
SUBNET_CIDR="10.0.1.0/24"

# 1. Create private network
echo "Creating network..."
hcloud network create --name "${PROJECT}-network" --ip-range "$NETWORK_CIDR"
hcloud network add-subnet "${PROJECT}-network" \
  --type cloud \
  --network-zone eu-central \
  --ip-range "$SUBNET_CIDR"

# 2. Create firewall
echo "Creating firewall..."
cat > firewall.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
hcloud firewall create --name "${PROJECT}-firewall" --rules-file firewall.json

# 3. Create SSH key
echo "Creating SSH key..."
hcloud ssh-key create --name "${PROJECT}-key" --public-key-from-file ~/.ssh/id_rsa.pub || true

# 4. Create web servers
echo "Creating web servers..."
for i in 1 2 3; do
  hcloud server create \
    --name "${PROJECT}-web-${i}" \
    --type cpx21 \
    --image ubuntu-24.04 \
    --location "$LOCATION" \
    --network "${PROJECT}-network" \
    --firewall "${PROJECT}-firewall" \
    --ssh-key "${PROJECT}-key" \
    --labels "app=${PROJECT},role=web,index=${i}" \
    --enable-backup &
done
wait

# 5. Wait for servers to be ready
echo "Waiting for servers..."
for i in 1 2 3; do
  while [ "$(hcloud server describe "${PROJECT}-web-${i}" -o json | jq -r '.status')" != "running" ]; do
    sleep 2
  done
  echo "${PROJECT}-web-${i} is running"
done

# 6. Create load balancer
echo "Creating load balancer..."
hcloud load-balancer create \
  --name "${PROJECT}-lb" \
  --type lb11 \
  --location "$LOCATION"

# 7. Add HTTP service
hcloud load-balancer add-service "${PROJECT}-lb" \
  --protocol http \
  --listen-port 80 \
  --destination-port 80 \
  --health-check-protocol http \
  --health-check-port 80 \
  --health-check-http-path /health

# 8. Add targets by label (automatically includes all web servers)
hcloud load-balancer add-target "${PROJECT}-lb" \
  --type label \
  --label "role=web"

# 9. Output summary
echo ""
echo "Infrastructure created:"
echo "======================"
hcloud server list --output columns=name,ipv4,status | grep "${PROJECT}"
echo ""
LB_IP=$(hcloud load-balancer describe "${PROJECT}-lb" -o json | jq -r '.public_net.ipv4.ip')
echo "Load Balancer IP: $LB_IP"
echo ""
echo "Test: curl http://$LB_IP"

Workflow 15: Server Monitoring and Health Checks

#!/bin/bash
# Monitor server health and send alerts

# Get all production servers
SERVERS=$(hcloud server list -o json | jq -r '.[] | select(.labels.environment == "production") | .name')

for server in $SERVERS; do
  STATUS=$(hcloud server describe "$server" -o json | jq -r '.status')
  
  if [ "$STATUS" != "running" ]; then
    echo "⚠️  $server is $STATUS"
    # Send alert (example: Slack webhook)
    # curl -X POST -H 'Content-type: application/json' \
    #   --data "{\"text\":\"Server $server is $STATUS\"}" \
    #   "$SLACK_WEBHOOK_URL"
  else
    echo "✅ $server is running"
  fi
  
  # Check server metrics (CPU)
  CPU=$(hcloud server metrics "$server" --type cpu --start=$(date -u -d '5 minutes ago' +%s) -o json | jq -r '.time_series.cpu.values[-1][1]')
  echo "   CPU: ${CPU}%"
  
  if (( $(echo "$CPU > 90" | bc -l) )); then
    echo "   ⚠️  High CPU usage!"
  fi
done

Workflow 16: Cleanup and Resource Management

#!/bin/bash
# Clean up temporary/stopped resources

# Delete stopped servers with 'temp' label
echo "Cleaning up temporary servers..."
hcloud server list -o json | jq -r '.[] | select(.labels.temp == "true") | select(.status == "off") | .name' | while read server; do
  echo "Deleting $server..."
  hcloud server delete "$server"
done

# Delete unattached volumes older than 7 days
echo "Cleaning up unattached volumes..."
hcloud volume list -o json | jq -r '.[] | select(.server == null) | "\(.id) \(.created)"' | while read id created; do
  AGE=$(( ($(date +%s) - $(date -d "$created" +%s)) / 86400 ))
  if [ $AGE -gt 7 ]; then
    echo "Deleting volume $id (${AGE} days old)..."
    hcloud volume delete "$id"
  fi
done

# Delete old snapshots (keep last 3)
echo "Cleaning up old snapshots..."
hcloud image list --type snapshot -o json | \
  jq -r 'sort_by(.created) | reverse | .[3:] | .[] | .id' | \
  while read image_id; do
    echo "Deleting snapshot $image_id..."
    hcloud image delete "$image_id"
  done

Workflow 17: Batch Operations with JSON

# Get IPs of all running web servers
hcloud server list -o json | \
  jq -r '.[] | select(.labels.role == "web") | select(.status == "running") | "\(.name): \(.public_net.ipv4.ip)"'

# Generate Ansible inventory
echo "[web_servers]"
hcloud server list -o json | \
  jq -r '.[] | select(.labels.role == "web") | "\(.public_net.ipv4.ip) hostname=\(.name)"'

# Shutdown all dev servers
hcloud server list -o json | \
  jq -r '.[] | select(.labels.environment == "dev") | .name' | \
  xargs -I {} hcloud server shutdown {}

# Apply firewall to all servers with label
FIREWALL="prod-firewall"
hcloud server list -o json | \
  jq -r '.[] | select(.labels.environment == "production") | .name' | \
  while read server; do
    hcloud firewall apply-to-resource "$FIREWALL" --type server --server "$server"
  done

Best Practices

Resource Organization

# Use consistent labeling scheme
--labels environment=production,service=api,team=platform,version=v2.0

# Label-based operations
hcloud server list --selector environment=production
hcloud server list --selector service=web

# Use descriptive names
--name prod-web-01  # Good
--name server-123   # Bad

# Enable protection on critical resources
hcloud server enable-protection prod-db-01 --delete --rebuild
hcloud volume enable-protection prod-data --delete

Security Hardening

# 1. Restrict SSH to specific IPs
{
  "rules": [
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "22",
      "source_ips": ["YOUR_OFFICE_IP/32"],
      "description": "SSH from office only"
    }
  ]
}

# 2. Use private networks for inter-server communication
# Don't expose databases/APIs on public internet

# 3. Enable backups on critical servers
hcloud server enable-backup prod-db-01

# 4. Use SSH keys, never passwords
hcloud ssh-key create --name deploy-key --public-key-from-file ~/.ssh/id_rsa.pub

# 5. Regular security updates (cloud-init example)
#cloud-config
package_upgrade: true
packages:
  - unattended-upgrades

Cost Optimization

# 1. Use appropriate server types (don't over-provision)
hcloud server-type list  # Review pricing

# 2. Shutdown dev/staging servers when not in use
hcloud server shutdown dev-*

# 3. Use snapshots instead of keeping servers running
hcloud server create-image dev-server --type snapshot --description "Dev environment"
hcloud server delete dev-server
# Restore when needed

# 4. Clean up old snapshots/backups
hcloud image list --type snapshot
hcloud image delete old-snapshot-id

# 5. Use placement groups to reduce costs
# Spread: Distributes across physical hosts (HA)
# Max 10 servers per spread group
hcloud placement-group create spread --name ha-group

High Availability Patterns

# 1. Use multiple locations
hcloud server create --name web-fsn1 --location fsn1
hcloud server create --name web-nbg1 --location nbg1

# 2. Use load balancers with health checks
hcloud load-balancer add-service app-lb \
  --health-check-protocol http \
  --health-check-retries 3 \
  --health-check-interval 15

# 3. Use floating IPs for failover
# Assign floating IP to primary
hcloud floating-ip assign 1.2.3.4 --server primary
# On failure, reassign to secondary
hcloud floating-ip assign 1.2.3.4 --server secondary

# 4. Use placement groups for distribution
hcloud placement-group create spread --name web-spread
hcloud server create --placement-group web-spread

# 5. Enable backups
hcloud server enable-backup prod-server

Troubleshooting

Authentication Issues

# Check active context
hcloud context active

# List all contexts
hcloud context list

# Verify token works
hcloud server list
# If error: "unable to authenticate", token is invalid

# Re-authenticate
hcloud context delete my-project
hcloud context create my-project
# Enter new token

# Check config file
cat ~/.config/hcloud/cli.toml

Server Creation Failures

# Check location capacity
hcloud location list
hcloud server-type list

# Check if server type available in location
hcloud datacenter list

# Common errors:
# "insufficient resources" - Try different location
# "placement_group_limit_reached" - Max 10 servers per spread group
# "limit_reached" - Check project limits in console

# Verbose output for debugging
hcloud server create --name test --type cpx11 --image ubuntu-24.04 --debug

Network Connectivity Issues

# Check firewall rules
hcloud firewall describe my-firewall

# Check server network attachment
hcloud server describe my-server -o json | jq '.private_net'

# Check network routes
hcloud network describe my-network

# Test connectivity (from server)
hcloud server ssh my-server
ping -c 3 10.0.1.10  # Test private network

# Check if firewall is applied
hcloud firewall list
hcloud server describe my-server -o json | jq '.firewall_ids'

Performance Issues

# Check server metrics
hcloud server metrics my-server --type cpu
hcloud server metrics my-server --type network
hcloud server metrics my-server --type disk

# Check load balancer metrics
hcloud load-balancer metrics my-lb --type open_connections
hcloud load-balancer metrics my-lb --type requests_per_second

# Review server type specs
hcloud server-type describe cpx21

# Consider upgrading
hcloud server shutdown my-server
hcloud server change-type my-server --upgrade-disk cpx31
hcloud server poweron my-server

Common Error Messages

| Error | Cause | Solution | |-------|-------|----------| | unable to authenticate | Invalid/expired token | Re-create context with valid token | | server not found | Wrong context or server name | Check hcloud context active | | insufficient resources | Location at capacity | Try different location | | limit_reached | Project limit exceeded | Contact support or upgrade | | protected | Resource has deletion protection | Disable protection first | | server_already_attached | Already in network | Detach first, then re-attach | | ip_not_available | IP already assigned | Unassign from other resource |

Output Formats for Scripting

# JSON output (recommended for scripts)
hcloud server list --output json

# Parse with jq
hcloud server list -o json | jq '.[] | {name: .name, ip: .public_net.ipv4.ip}'

# YAML output
hcloud server describe my-server --output yaml

# Custom Go template
hcloud server list --output format='{{range .}}{{.Name}}: {{.PublicNet.IPv4.IP}}{{"\n"}}{{end}}'

# Table without header (for parsing)
hcloud server list --output noheader

# Select specific columns
hcloud server list --output columns=name,ipv4,status

# Combine options
hcloud server list -o noheader -o columns=name,ipv4 | while read name ip; do
  echo "Server: $name -> $ip"
done

Advanced Use Cases

Placement Groups

# Create spread group (HA - different physical hosts)
hcloud placement-group create spread --name ha-web

# Create servers in group
hcloud server create --name web-01 --placement-group ha-web --type cpx21
hcloud server create --name web-02 --placement-group ha-web --type cpx21

# Max 10 servers per spread group
# Use multiple groups for larger deployments

Primary IPs

# Create primary IPv4 (replaces default server IP)
hcloud primary-ip create \
  --type ipv4 \
  --assignee-type server \
  --datacenter fsn1-dc14 \
  --name web-primary-ip

# Assign to server during creation
hcloud server create \
  --name my-server \
  --type cpx11 \
  --image ubuntu-24.04 \
  --primary-ipv4 web-primary-ip

# Benefit: Keep IP when recreating server

User Data (Cloud-Init)

# Create cloud-init file
cat > cloud-init.yaml <<'EOF'
#cloud-config
package_upgrade: true
packages:
  - docker.io
  - git
  - curl

write_files:
  - path: /etc/docker/daemon.json
    content: |
      {"log-driver": "json-file", "log-opts": {"max-size": "10m"}}

runcmd:
  - systemctl enable docker
  - systemctl start docker
  - usermod -aG docker ubuntu
EOF

# Create server with user data
hcloud server create \
  --name docker-server \
  --type cpx21 \
  --image ubuntu-24.04 \
  --user-data-from-file cloud-init.yaml

DNS Integration (Experimental)

# Create DNS zone
hcloud zone create --name example.com

# Add records
hcloud zone add-record example.com --type A --name www --value 1.2.3.4
hcloud zone add-record example.com --type AAAA --name www --value 2001:db8::1

# List zones
hcloud zone list

# Export zone
hcloud zone export example.com

Resources

• Official CLI Repository: https://github.com/hetznercloud/cli
• Hetzner Cloud API Docs: https://docs.hetzner.cloud/
• Hetzner Cloud Console: https://console.hetzner.cloud/
• Community Forum: https://community.hetzner.com/
• API Changelog: https://docs.hetzner.cloud/changelog/

Version Information

This skill is based on hcloud CLI v1.60.0 (January 2026).