hcloud-go

The Server resource manages networking through two primary interfaces: PublicNet for internet-facing traffic and PrivateNet for internal network communication.

Public Networking

• ServerPublicNet: Contains IPv4, IPv6, Floating IPs, and attached Firewalls.
• ServerPublicNetIPv4: Details for an IPv4 address, including IP, Blocked status, and DNSPtr.
• ServerPublicNetIPv6: Details for an IPv6 address, including a slice of ServerPublicNetIPv6DNSPtr for reverse DNS.

Private Networking

• ServerPrivateNet: Represents a private network interface, including the Network ID, IP, AliasIPs, and MACAddress.

type ServerPublicNet struct {
	IPv4        ServerPublicNetIPv4 `json:"ipv4"`
	IPv6        ServerPublicNetIPv6 `json:"ipv6"`
	FloatingIPs []int64             `json:"floating_ips"`
	Firewalls   []ServerFirewall    `json:"firewalls"`
}

type ServerPrivateNet struct {
	Network    int64    `json:"network"`
	IP         string   `json:"ip"`
	AliasIPs   []string `json:"alias_ips"`
	MACAddress string   `json:"mac_address"`
}

Server actions are asynchronous operations performed on a server. Each action has a corresponding Request struct and a Response struct that contains an Action object to track progress.

Common Actions

• Power Management: ServerActionPoweronRequest, ServerActionPoweroffRequest, ServerActionRebootRequest, ServerActionResetRequest, ServerActionShutdownRequest.
• Image & Recovery: ServerActionCreateImageRequest (creates a snapshot), ServerActionRebuildRequest (reinstalls an image), ServerActionEnableRescueRequest (enables rescue mode).
• Configuration: ServerActionChangeTypeRequest (resizes server), ServerActionChangeProtectionRequest (toggles delete/rebuild protection), ServerActionAttachISORequest (mounts an ISO).
• Networking: ServerActionAttachToNetworkRequest, ServerActionDetachFromNetworkRequest, ServerActionChangeDNSPtrRequest.
• Console: ServerActionRequestConsoleRequest (returns a WebSocket VNC URL and password).

// Example: Rebuild request
type ServerActionRebuildRequest struct {
	Image    IDOrName `json:"image"`
	UserData *string  `json:"user_data,omitempty"`
}

// Example: Console request
type ServerActionRequestConsoleRequest struct{}

type ServerActionRequestConsoleResponse struct {
	Action   Action `json:"action"`
	WSSURL   string `json:"wss_url"`
	Password string `json:"password"`
}

Use hcloud.NewClient to create a new client for interacting with the Hetzner Cloud API. You can pass several ClientOption functions to configure authentication, endpoints, and behavior.

Common options include:

• hcloud.WithToken(token string): Sets the API token for authentication.
• hcloud.WithEndpoint(endpoint string): Sets a custom Cloud API endpoint.
• hcloud.WithHetznerEndpoint(endpoint string): Sets a custom Hetzner API endpoint (experimental, used for Storage Boxes).
• hcloud.WithDebugWriter(io.Writer): Directs debug information to a writer (e.g., os.Stderr).
• hcloud.WithHTTPClient(httpClient *http.Client): Provides a custom HTTP client.
• hcloud.WithApplication(name, version string): Sets a custom User-Agent for the library.

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

client := hcloud.NewClient(
	hcloud.WithToken("YOUR_API_TOKEN"),
	hcloud.WithDebugWriter(os.Stderr),
)

To interact with the Hetzner Cloud API, initialize a client using hcloud.NewClient with functional options like hcloud.WithToken. You can then use the client.Server service to create, retrieve, or manage servers.

Important: Many API operations are asynchronous. When an operation returns an Action, you should use client.Action.WaitFor (often combined with actionutil.AppendNext) to ensure the process completes before proceeding with the result.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
	"github.com/hetznercloud/hcloud-go/v2/hcloud/exp/actionutil"
)

func main() {
	ctx := context.Background()

	client := hcloud.NewClient(
		hcloud.WithToken("token"),
		hcloud.WithApplication("my-tool", "v1.0.0"),
	)

	result, _, err := client.Server.Create(ctx, hcloud.ServerCreateOpts{
		Name:       "Foo",
		Image:      &hcloud.Image{Name: "ubuntu-24.0"},
		ServerType: &hcloud.ServerType{Name: "cpx22"},
		Location:   &hcloud.Location{Name: "hel1"},
	})
	if err != nil {
		log.Fatalf("error creating server: %s\n", err)
	}

	// Always await any returned actions, to make sure the async process is completed before you use the result:
	err = client.Action.WaitFor(ctx, actionutil.AppendNext(result.Action, result.NextActions)...)
	if err != nil {
		log.Fatalf("error creating server: %s\n", err)
	}

	server, _, err := client.Server.GetByID(ctx, result.Server.ID)
	if err != nil {
		log.Fatalf("error retrieving server: %s\n", err)
	}
	if server != nil {
		fmt.Printf("server is called %q\n", server.Name) // prints 'server is called "Foo"'
	} else {
		fmt.Println("server not found")
	}
}