Hetzner Cloud Go SDK

Overview

The official Go SDK for Hetzner Cloud provides type-safe access to 23+ resource types with automatic retries, action polling, and comprehensive error handling. Use it for bots, automation, integrations, and complex workflows. For quick CLI operations, use hetzner:hcloud-cli instead.

Quick Setup

import "github.com/hetznercloud/hcloud-go/v2/hcloud"

// Create client
client := hcloud.NewClient(hcloud.WithToken("your-api-token"))

bash

go get github.com/hetznercloud/hcloud-go/v2/hcloud

Quick Reference

Task	Method
Servers
List servers	`client.Server.All(ctx)`
Get server	`client.Server.GetByID(ctx, 123)` or `GetByName(ctx, "web")`
Create server	`client.Server.Create(ctx, hcloud.ServerCreateOpts{})`
Delete server	`client.Server.Delete(ctx, server)`
Reboot/Reset	`client.Server.Reboot(ctx, server)` / `Reset(ctx, server)`
Networks
Create network	`client.Network.Create(ctx, hcloud.NetworkCreateOpts{})`
Attach server	`client.Server.AttachToNetwork(ctx, server, opts)`
Volumes
Create volume	`client.Volume.Create(ctx, hcloud.VolumeCreateOpts{})`
Attach volume	`client.Volume.Attach(ctx, volume, server)`
Actions
Wait for action	`client.Action.WaitFor(ctx, action)`
Poll with callback	`client.Action.WaitForFunc(ctx, callback, action)`

API Categories

See references/api-reference.md for complete method list:

•Servers (create, lifecycle, networking)
•Networks, subnets, routes
•Volumes
•Firewalls and rules
•Load balancers, targets, services
•Floating IPs, Primary IPs
•SSH keys, images, certificates
•DNS zones (GA in v2.30.0)
•Storage boxes (experimental)

Client Configuration

client := hcloud.NewClient(
    hcloud.WithToken("token"),                    // Required
    hcloud.WithEndpoint("https://api.hetzner.cloud/v1"), // Custom endpoint
    hcloud.WithApplication("myapp", "1.0.0"),     // User-Agent
    hcloud.WithDebugWriter(os.Stderr),            // Debug logging
    hcloud.WithHTTPClient(customClient),          // Custom HTTP client
    hcloud.WithRetryOpts(hcloud.RetryOpts{        // Retry config
        MaxRetries: 5,
        BackoffFunc: hcloud.ExponentialBackoff(2, time.Second),
    }),
    hcloud.WithPollOpts(hcloud.PollOpts{          // Action polling
        BackoffFunc: hcloud.ConstantBackoff(500 * time.Millisecond),
    }),
)

Common Patterns

See references/patterns.md for idiomatic patterns:

•Error handling
•Action polling
•Pagination
•Resource lookups

Action Handling

All long-running operations return an Action:

result, _, err := client.Server.Create(ctx, opts)
if err != nil {
    return err
}

// Wait for completion
if err := client.Action.WaitFor(ctx, result.Action); err != nil {
    return err
}

// Or with progress callback
err = client.Action.WaitForFunc(ctx,
    func(update *hcloud.Action) error {
        fmt.Printf("Progress: %.0f%%\n", update.Progress)
        return nil
    },
    result.Action,
)

Error Handling

import "github.com/hetznercloud/hcloud-go/v2/hcloud"

err := someAPICall()

// Check specific error codes
if hcloud.IsError(err, hcloud.ErrorCodeNotFound) {
    // Resource doesn't exist
}

// Get error details
if apiErr, ok := err.(*hcloud.APIError); ok {
    fmt.Printf("Error: %s - %s\n", apiErr.Code, apiErr.Message)
}

Common error codes:

•ErrorCodeNotFound - Resource doesn't exist
•ErrorCodeInvalidInput - Validation error
•ErrorCodeForbidden - Insufficient permissions
•ErrorCodeRateLimitExceeded - Rate limit hit (auto-retried)
•ErrorCodeConflict - Resource changed (auto-retried)
•ErrorCodeLocked - Another action running

Common Mistakes

Problem	Solution
Nil pointer panic	Always check error before using result
Action timeout	Use `ctx, cancel := context.WithTimeout(...)`
Missing pagination	Use `client.Server.All(ctx)` for complete list
Action failed	Check action error with `WaitFor()` return value
Rate limiting	SDK auto-retries, but add backoff for bulk ops