Hetzner's API architecture spans three distinct endpoints (Cloud API, Robot API, Storage Box) with two different authentication mechanisms (Bearer tokens for Cloud/Robot, separate credentials for Storage Box), requiring separate credential management for each product line.
Hetzner Cloud API operations are asynchronous with action tracking — the CLI polls at 500ms intervals and the Go SDK requires explicit WaitFor() calls, establishing a converge-and-poll pattern as the standard automation idiom.
Hetzner's asynchronous API design propagates through the entire automation stack — CLI polls at 500ms intervals, Go SDK requires explicit WaitFor() calls, and Terraform (built on hcloud-go) inherits the same async convergence requirement — making action completion handling a universal automation concern.
Hetzner provides automation tools at three layers: the hcloud-go SDK for programmatic access, the hcloud CLI for interactive and scripted management, and the Terraform provider (built on hcloud-go) for infrastructure-as-code workflows.
Hetzner offers two complementary data protection strategies with inverse cost/control tradeoffs: automatic backups (simple, fixed 20% server cost, max 7 retained, no user intervention) and manual snapshots (full control over timing and retention, per-GB billing, unlimited count).
Hetzner's billing model appears simple (hourly with monthly caps, no commitment) but contains material cost traps: powered-off servers still billed, IPv4 charged when unassigned, and 40x regional traffic asymmetry — requiring active cost governance despite the pay-as-you-go branding.
As location consolidation makes location the sole billing axis and cross-location migration remains impossible, initial location choice creates an irreversible cost profile for the deployment's lifetime.
CCM development environment requires OpenTofu, k3sup, Docker, and Skaffold.
The Hetzner Cloud Controller Manager integrates Kubernetes with both the Hetzner Cloud API and the Robot API (dedicated servers).
The CCM load balancer algorithm annotation supports roundrobin (default) and leastconnections.
Hetzner Cloud Load Balancers are configured via Kubernetes annotations on Service objects (e.g., load-balancer.hetzner.cloud/algorithm-type).
Robot API integration requires ROBOTENABLED=true, ROBOTUSER, and ROBOT_PASSWORD environment variables.
CCM versions <= v1.30.0 will panic and crash after July 2026 due to removal of the server.datacenter API field; minimum safe version is v1.30.1.
The hcloud CLI enforces project-scoped isolation — each context binds to a single API token/project, only one is active at a time, switching is explicit (use/unset), and creation is interactive — establishing a single-project-at-a-time operational model that prevents accidental cross-project mutations.
The hcloud CLI follows a consistent resource identity pattern across all major resource types: describe commands accept name-or-ID, output supports JSON/YAML/custom format, and resources share the same label management subcommand structure.
Cost optimization on Hetzner is inseparable from architecture — the 40x regional traffic asymmetry makes location selection a billing decision, while resource binding (volumes, IPs, networks) makes location selection an architectural commitment, so cost-efficient architectures must account for location as a first-class design parameter from day one rather than treating it as a deployment detail.
Docker Swarm and HashiCorp Nomad support for the CSI driver is community-contributed and unofficial.
The Hetzner Cloud CSI driver is licensed under MIT.
The Hetzner Cloud CSI driver requires Kubernetes 1.19 or newer.
The Hetzner Cloud CSI driver supports only ReadWriteOnce (RWO) access mode — not ReadWriteMany or ReadOnlyMany.
Hetzner resources are location-coupled (servers, volumes, networks bound to their creation location), meaning moving workloads between locations requires recreating resources rather than migrating them in place.
Server operations include destructive paths (rebuild replaces root disk, poweroff/reset are non-graceful) and Hetzner's two data protection strategies have inverse cost/control tradeoffs (automatic backups: simple but capped at 7; snapshots: flexible but manual and per-GB), meaning data protection requires deliberate architectural decisions — there is no implicit safety net covering both convenience and retention depth.
German datacenters (NBG1, FSN1) are self-operated by Hetzner while international locations (US, Singapore) use third-party facilities, creating a sovereignty distinction relevant for data residency requirements.
Hetzner is systematically deprecating datacenter-level resource placement in favor of location-level across servers, Primary IPs, and resource attributes — a coordinated API migration signaling that datacenter IDs will become internal implementation details.
Hetzner DDoS protection is free and hardware-based, applied at the datacenter perimeter.
Hetzner Cloud employs multiple safeguard layers against destructive operations: resource protection (must disable before delete), deprecated image blocking (opt-in required), and explicit required flags — preventing accidental data loss through defense in depth.
Hetzner DNS provides full BIND-compatible zone management with 16 record types, three mutation strategies per RRSet (append/replace/delete), and support for both primary and secondary zones with AXFR.
Hetzner provides an end-to-end managed TLS lifecycle within a single provider — BIND-compatible DNS zone management for domain hosting, automatic managed certificate issuance via Let's Encrypt, and Load Balancer TLS termination with HTTP/2 and HTTP-to-HTTPS redirect — eliminating external DNS and certificate provider dependencies.
Hetzner's economic model is aggressively entry-friendly — no minimum contracts, hourly billing with monthly caps, and comprehensive free infrastructure services (firewalls, DDoS, private networks, IPv6, support) minimize both financial risk and ongoing overhead for new deployments.
Hetzner Cloud's billing model is fully elastic with no minimum commitment — hourly metering with monthly caps means costs scale linearly with usage but never exceed fixed rates.
EU data sovereignty is achievable using Hetzner's self-operated German datacenters with co-located Object Storage, but this sovereignty model cannot extend internationally — non-EU locations use third-party facilities and lack Object Storage entirely, making the EU sovereignty architecture a dead end for global expansion.
Hetzner Cloud Firewalls operate as decoupled top-level resources with many-to-many server relationships and dynamic label-selector application, enabling policy-as-code security management where firewall rules automatically apply to any server matching a label selector.
Hetzner Cloud firewalls combine powerful dynamic policy primitives (decoupled many-to-many server relationships, label-selector auto-application across the fleet) with protocol-specific configuration complexity (port valid only for TCP/UDP, direction-driven IP flag requirements, CIDR notation) — powerful at the policy level but requiring protocol-aware rule templating for reliable automation.
Firewall rule configuration has protocol-asymmetric requirements — port specification is valid only for TCP/UDP (not ICMP/ESP/GRE), direction determines which IP flag is required (source for inbound, destination for outbound), and CIDR notation is mandatory for all IP specifications.
Hetzner Cloud Firewalls are stateless and incur no additional cost.
Floating IPs are datacenter-scoped (same datacenter only) and persist independently of server lifecycle.
FTL2 can run hetzner.hcloud collection modules via FQCN syntax (e.g., ftl.hetzner.hcloud.server(...)) for all Cloud API resources.
FTL2 native modules execute in-process over SSH, running 250x faster than Ansible subprocess mode for post-provisioning configuration.
FTL2 has no native Hetzner modules yet; only an AWS EC2 module stub exists as a pattern for future implementation.
FTL2 runs Ansible collection modules directly from Python async/await code without YAML playbooks, achieving 3-17x faster execution than ansible-playbook.
FTL2 injects HCLOUDTOKEN via secretbindings configuration, preventing token exposure in code or audit logs.
FTL2 uses a .ftl2-state.json state file for idempotent provisioning and crash recovery of infrastructure resources.
Alias IPs allow a single server to hold multiple IP addresses on the same network.
The default Hetzner Cloud API endpoint is https://api.hetzner.cloud/v1; the separate Hetzner endpoint is https://api.hetzner.com/v1.
The default Hetzner API endpoint is https://api.hetzner.com/v1.
The default Hetzner Cloud API endpoint is https://api.hetzner.cloud/v1 and the default Hetzner (non-cloud) API endpoint is https://api.hetzner.com/v1.
When attaching a server to a network, IP address and subnet are auto-assigned by default; explicit assignment is optional.
The --network flag is the only required option for hcloud server attach-to-network.
Automatic backups cost 20% of instance price, with a maximum of 7 retained
The CAX (ARM Ampere) server series is the most cost-efficient Hetzner Cloud series.
CCX (dedicated vCPU) servers have higher RAM-to-CPU ratios than shared lines (e.g., CCX13 = 2 vCPU / 8GB vs CX22 = 2 vCPU / 4GB).
The hcloud certificate retry subcommand applies only to managed certificates, re-attempting automatic issuance after a failure.
Hetzner Cloud certificates can be either uploaded (user-provided) or managed (issued automatically by Hetzner via Let's Encrypt integration).
The hcloud CLI supports shell completions for bash, zsh, fish, and PowerShell.
The hcloud CLI config file is stored at ~/.config/hcloud/cli.toml.
The default hcloud CLI config file location is ~/.config/hcloud/cli.toml.
The default hcloud CLI poll interval for action progress is 500ms.
The hcloud CLI Docker image (hetznercloud/cli) is Alpine-based with config mounted at /config.toml.
The hcloud CLI is hosted at github.com/hetznercloud/cli.
The default Hetzner Cloud API endpoint is https://api.hetzner.cloud/v1.
The hcloud CLI default config file path is ~/.config/hcloud/cli.toml (TOML format).
Each hcloud context binds to a Hetzner Cloud API token, which is scoped to a single Hetzner Cloud project.
hcloud context create <name> is interactive and prompts for the API token.
Only one hcloud context is active at a time; it determines which project API calls target, and can be overridden per-command with --context.
hcloud context use sets the active context persistently; hcloud context unset clears/deactivates the current context.
Labels on hcloud server create-image use key=value syntax and can be specified multiple times via repeated --label flags.
The --type flag is required for hcloud server create-image and must be snapshot or backup.
The datacenter attribute is deprecated for Primary IPs and Servers in hcloud CLI v1.59.0; location is the replacement concept.
The hcloud datacenter command group is read-only with only two subcommands: list and describe.
DDoS protection is free and implemented via hardware appliances
The default Hetzner Cloud API endpoint is https://api.hetzner.cloud/v1.
The default hcloud CLI config file location is ~/.config/hcloud/cli.toml
The hcloud CLI default poll interval for checking action progress is 500ms.
The default poll interval for the hcloud CLI is 500ms.
Hetzner DNS supports 16 record types: A, AAAA, CAA, CNAME, DS, HINFO, HTTPS, MX, NS, PTR, RP, SOA, SRV, SVCB, TLSA, TXT.
The Hetzner DNS API uses the endpoint https://api.hetzner.com/v1, distinct from the Cloud API at api.hetzner.cloud.
DNS API support graduated to GA (no longer experimental) in hcloud CLI v1.57.0.
Both hcloud-go and hcloud-python experimental features may introduce breaking changes in minor releases.
The --type flag is required when applying a firewall to a resource, with two valid values: server and label_selector.
The --name flag is required when creating a firewall with hcloud firewall create.
hcloud firewall create accepts --rules-file to load rules from a JSON file, or - to read from stdin.
hcloud firewall describe accepts either a firewall name or ID as the positional argument.
hcloud firewall describe supports json, yaml, and custom format output via the -o flag.
Hetzner Cloud firewall rules support five protocols: tcp, udp, icmp, esp, and gre.
Firewall rule IP addresses must be specified in CIDR notation (e.g., 0.0.0.0/0 for all IPv4).
Using --type label_selector with hcloud firewall apply-to-resource dynamically applies the firewall to all resources matching the label.
Firewalls are decoupled from servers in a many-to-many relationship, applied individually via apply-to-resource and removed via remove-from-resource.
The --port flag on firewall rules is only valid for tcp and udp protocols; it cannot be used with icmp, esp, or gre.
Firewall rule port ranges use dash syntax (e.g., 80-85).
Firewall rule direction determines the required IP flag: in requires --source-ips, out requires --destination-ips.
Firewall rules can be managed individually (add-rule/delete-rule) or replaced in bulk from a file (replace-rules).
Firewalls are a top-level resource in Hetzner Cloud, managed through the hcloud firewall command group.
Hetzner Cloud Firewalls are stateless (not stateful) and free of charge
DDoS protection, firewalls, private networks, 24/7 support, and IPv6 are all free on Hetzner Cloud.
German datacenters (NBG1, FSN1) are Hetzner-operated; US and Singapore use third-party facilities
Hetzner Cloud API operations are async — client.Action.WaitFor() must be called before using results.
Go-built hcloud binaries do not have the correct version embedded.
hcloud-go supports the latest two Go minor versions, matching Go's official release policy.
hcloud-go v1 has been unsupported since February 2025.
The key v1-to-v2 breaking change in hcloud-go was ID fields moving from int to int64.
The hcloud-go v2 import path is github.com/hetznercloud/hcloud-go/v2/hcloud.
The default Hetzner API endpoint is https://api.hetzner.com/v1, separate from the Cloud API endpoint.
Hetzner Cloud uses hourly billing with monthly price caps — customers never pay more than the fixed monthly rate.
Primary IPv4 addresses are charged even when unassigned to a server; IPv6 is always free.
ISOs can be attached to servers during creation via hcloud server create --iso or mounted later for rescue/installation.
ISOs (vendor-provided installation media) are distinct from images (user-created snapshots/backups managed via hcloud image).
Users cannot upload custom ISOs through the hcloud CLI; ISOs are managed/provided by Hetzner.
ISOs in Hetzner Cloud are read-only resources via the CLI — only list and describe subcommands exist, with no create or delete operations.
The Load Balancer algorithm defaults to roundrobin if --algorithm-type is not specified; the other option is leastconnections.
Hetzner Cloud Load Balancer supports two algorithms: roundrobin (default) and leastconnections.
The --ip-range flag on hcloud load-balancer attach-to-network accepts a CIDR block (ipNet type) specifying which subnet to attach to.
The hcloud load-balancer attach-to-network command attaches a Hetzner Cloud Load Balancer to a private Network.
The --network flag is the only required option for hcloud load-balancer attach-to-network; IP and subnet are auto-assigned if omitted.
The load balancer balancing algorithm can be changed after creation using hcloud load-balancer change-algorithm.
Load Balancer type can be changed after creation using hcloud load-balancer change-type, enabling vertical scaling.
A Load Balancer can be attached to a network at creation time using the --network flag on hcloud load-balancer create.
hcloud load-balancer create requires both --name and --type flags.
The --expand-targets flag on hcloud load-balancer describe resolves label_selector targets to show the actual matched resources.
The inverse of hcloud load-balancer attach-to-network is hcloud load-balancer detach-from-network.
The --http-redirect-http flag on add-service redirects port 80 traffic to port 443.
Label-selector targets on Load Balancers are dynamic — servers matching the selector are automatically included or excluded.
The hcloud load-balancer metrics subcommand is marked as ALPHA and is not stable/GA.
Using --use-private-ip for Load Balancer targets requires the load balancer to be attached to a network that the target is also part of.
Hetzner Cloud Load Balancers can operate without a public interface (private-only mode) when attached to a network.
The only protection type available for Hetzner Cloud Load Balancers is delete.
Default health check values for Load Balancer services are: interval 15s, timeout 10s, retries 3.
Load Balancer services support three protocols: HTTP, HTTPS, and TCP.
Load Balancer sticky sessions are cookie-based, requiring --http-sticky-sessions plus --http-cookie-name and --http-cookie-lifetime configuration.
TCP protocol services require both --listen-port and --destination-port flags; HTTPS requires --http-certificates; HTTP needs only --protocol.
Load Balancer targets come in three mutually exclusive types per invocation: --server (name/ID), --label-selector (dynamic group), or --ip (direct IP address).
The hcloud load-balancer-type command group is read-only with only list and describe subcommands — load balancer types are predefined by Hetzner.
Cloud Server local SSD storage uses RAID10 configuration for fault tolerance
Locations are grouped into datacenters; a single location can contain multiple datacenters.
The hcloud location command group is read-only with only list and describe subcommands — locations are immutable infrastructure metadata defined by Hetzner.
Hetzner Cloud locations contain datacenters; datacenters are referenced when creating servers, volumes, and other location-bound resources.
In hcloud network add-route, --destination accepts ipNet type (CIDR notation) and --gateway accepts ip type (single address).
Routes are added to existing networks — the network must already exist before adding a route with hcloud network add-route.
The hcloud network add-route command requires both --destination (CIDR notation) and --gateway (single IP) flags.
The hcloud network add-subnet command requires --type and --network-zone as mandatory flags.
The hcloud network create command requires --name and --ip-range as mandatory flags.
The hcloud network describe command accepts either a network name or numeric ID as the argument.
Networks support --expose-routes-to-vswitch to bridge cloud network routes with dedicated server vSwitch connections.
The hcloud network expose-routes-to-vswitch subcommand enables hybrid connectivity between Hetzner Cloud networks and dedicated server vSwitches.
The IP range of an existing Hetzner Cloud network can be changed after creation using hcloud network change-ip-range.
Delete protection is the only protection type available for Hetzner Cloud networks.
Networks can be referenced by either ID or name in hcloud CLI commands.
Hetzner Cloud Networks support resource protection that must be explicitly enabled/disabled via enable-protection and disable-protection subcommands.
Hetzner Cloud Networks support three sub-resource types: subnets, routes, and labels.
The --ip-range flag on hcloud network add-subnet is optional; if omitted, Hetzner auto-allocates from the network's IP range.
Hetzner Cloud network subnets have exactly three types: cloud, server, and vswitch.
The --vswitch-id flag is required when subnet type is vswitch and only relevant for that type.
Hetzner Cloud subnets are scoped to a network zone (e.g., eu-central), not to a specific datacenter location.
Hetzner Cloud has no minimum contract; it is pure pay-as-you-go.
Hetzner Object Storage base tier is EUR 4.99/month including 1TB storage and 1TB egress.
Empty active buckets in Hetzner Object Storage still incur hourly charges.
Hetzner Object Storage is available in three EU regions only: FSN1, HEL1, NBG1 (no US or Singapore).
Ingress traffic, internal eu-central zone traffic, and all S3 API calls are free for Hetzner Object Storage.
Hetzner Object Storage limits: 100 buckets per account, 100 TB per bucket, 50M objects per bucket.
Objects smaller than 64 KB in Hetzner Object Storage are billed as 64 KB.
Unused included storage and egress in Hetzner Object Storage does not roll over month to month.
Hetzner Object Storage overage: storage EUR 0.0067/TB-h, egress EUR 1.00/TB.
Object Storage uses TB-hours billing: storage consumption = TB stored × hours stored; monthly quota is 744 TB-h (1 TB × 744 hours).
Hetzner Cloud provides official SDKs for Go and Python; community libraries exist for other languages
Servers are assigned to placement groups at creation time via hcloud server create --placement-group.
Placement Groups are assigned to servers at creation time to control physical host distribution.
The hcloud placement-group create command requires both --name and --type flags.
The hcloud placement-group describe command accepts either a name or ID as the <placement-group> argument.
Hetzner Cloud Placement Groups use the "spread" strategy (the only type currently supported) to ensure servers run on different physical hosts.
The hcloud placement-group command has seven subcommands: create, delete, describe, list, update, add-label, and remove-label.
The known placement group type is spread, which distributes servers across different physical hosts.
Powered-off Cloud Servers are still billed because resources remain allocated; billing stops only on deletion
hcloud server poweroff is a hard power cut; hcloud server shutdown is a graceful ACPI shutdown.
The hcloud primary-ip assign command requires the --server flag (accepting name or ID) to specify the target server.
The only currently supported assignee type for Primary IPs is server.
Primary IPs support an --auto-delete flag that automatically deletes the IP when its assigned resource is deleted; without it, the IP persists.
The hcloud primary-ip create command requires both --type (ipv4 or ipv6) and --name flags.
The --datacenter flag on hcloud primary-ip create is deprecated; --location or --assignee-id should be used instead (per 2025-12-16 datacenter phase-out).
Primary IPs are independent resources that persist when a server is deleted, unlike default server IPs.
The --enable-protection flag on hcloud primary-ip create only supports the delete protection type.
Reverse DNS (rDNS) records can be configured directly on Primary IPs via hcloud primary-ip set-rdns.
Primary IPs replace a server's default public IP, while Floating IPs are additional addresses routed via alias IPs or IP configuration.
Private-only servers (no public IP) require a jump host, VPN, or load balancer for access.
client.servers.create() returns a response object with .server and .root_password attributes, not the server directly.
The hcloud Python library is MIT licensed.
The official Hetzner Cloud Python SDK is installed via pip install hcloud.
The hcloud Python SDK references resources via typed objects: ServerType(name=...), Image(name=...).
hcloud server reboot is a graceful reboot; hcloud server reset is a hard reset.
hcloud server rebuild reinstalls the OS and is a destructive operation that replaces the root disk.
The default rescue type for hcloud server enable-rescue is linux64.
Enabling rescue mode with hcloud server enable-rescue does not automatically reboot the server; a separate reboot or reset action is required.
SSH keys for hcloud server enable-rescue are specified via --ssh-key and can be repeated for multiple keys; keys are referenced by ID or name.
The hcloud CLI resource management subcommands are: certificate, firewall, floating-ip, image, load-balancer, network, placement-group, primary-ip, server, ssh-key, storage-box, volume, zone.
The --datacenter flag on hcloud server create is deprecated; --location should be used instead (per 2025-12-16 changelog).
Deprecated images are blocked by default on hcloud server create; opt in with --allow-deprecated-image.
Servers created with hcloud server create receive both IPv4 and IPv6 by default; either can be disabled with --without-ipv4 or --without-ipv6.
Server protection options are limited to delete and rebuild, set via --enable-protection.
The hcloud server create command requires three flags: --name, --type, and --image.
hcloud server create starts the server automatically after creation by default (--start-after-create defaults to true).
User data for hcloud server create is loaded from a file via --user-data-from-file, not passed inline; use - for stdin.
Private-only servers are created with --without-ipv4 --without-ipv6 --network <net> flags on hcloud server create.
hcloud server describe accepts a server identifier by either name or ID.
hcloud server describe supports three output formats: json, yaml, and Go template format strings via -o.
hcloud server list has 22 available output columns including placementgroup, rescueenabled, privatenet, and backupwindow.
hcloud server list uses -l/--selector for label filtering, not --labels.
hcloud server list output format (-o) accepts noheader, columns=..., json, and yaml.
The --status flag on hcloud server list accepts multiple statuses (strings type).
The hcloud server metrics command is an ALPHA feature.
The --image flag is required for hcloud server rebuild; rebuild cannot proceed without specifying a source image.
hcloud server rebuild destroys the root disk but preserves the server resource (ID, IPs, volumes).
The hcloud server rebuild command supports a --user-data flag for passing cloud-init configuration during rebuild.
Server resource protection in Hetzner Cloud prevents accidental deletion and rebuild.
CAX server type prefix denotes shared vCPU on Ampere ARM processors
CCX server type prefix denotes dedicated AMD high-memory vCPU
CPX server type prefix denotes dedicated AMD general purpose vCPU
CX server type prefix denotes shared vCPU on Intel/AMD processors
The hcloud server-type command group is read-only with two subcommands: list and describe.
Server types are predefined by Hetzner — users select from them but cannot create custom types.
Hetzner Cloud has six datacenter locations: NBG1 (Nuremberg), FSN1 (Falkenstein), HEL1 (Helsinki), ASH (Ashburn), HIL (Hillsboro), SIN (Singapore)
Hetzner Cloud has six datacenters: nbg1-dc3 (Nuremberg), hel1-dc2 (Helsinki), fsn1-dc14 (Falkenstein), ash-dc1 (Ashburn), hil-dc1 (Hillsboro), sin-dc1 (Singapore).
Snapshots are manual point-in-time server images, billed per GB/month, distinct from automatic backups.
The --name flag is required when creating an SSH key with hcloud ssh-key create
hcloud ssh-key create accepts the public key via --public-key (inline) or --public-key-from-file (file path), and exactly one must be specified
SSH keys are a top-level resource in Hetzner Cloud, managed independently from servers
The hcloud ssh-key command group has seven subcommands: create, delete, describe, list, update, add-label, and remove-label
Storage Box support graduated to GA (no longer experimental) in hcloud CLI v1.61.0.
The hcloud storage-box snapshot command group has seven subcommands: create, delete, describe, list, update, add-label, remove-label.
Storage Box subaccounts are identified by id or name (not username) as of CLI v1.60.0.
Hetzner has three distinct APIs with different auth: Cloud API (Bearer token), Hetzner API (Bearer token for storage boxes), Robot API (Basic auth for dedicated servers).
Included traffic varies by region: 20TB/month (EU shared), 1TB (US), 0.5TB (Singapore)
The hcloud CLI bridges two distinct APIs: Hetzner Cloud API (api.hetzner.cloud) for cloud resources and Hetzner API (api.hetzner.com) for dedicated/DNS/storage-box services.
The hcloud CLI utility subcommands are: all, completion, config, context, version.
The hcloud CLI view-only (read-only) subcommands are: datacenter, iso, load-balancer-type, location, server-type, storage-box-type.
The hcloud volume attach command supports an --automount flag to automatically mount the volume on the server's filesystem after attachment.
A Hetzner Cloud Volume can only be attached to one server at a time.
The --server flag is required for hcloud volume attach — the command fails without it.
The --automount flag on hcloud volume create requires --server to also be specified.
hcloud volume create supports only two filesystem formats: ext4 and xfs.
hcloud volume create requires both --name and --size (in GB) as mandatory parameters.
hcloud volume create --enable-protection only supports delete protection.
The hcloud volume describe command accepts either a volume name or numeric ID as its argument.
hcloud volume describe supports three output formats: json, yaml, and format (custom formatting).
Volume resource protection must be explicitly disabled before a protected volume can be deleted.
Hetzner Cloud volumes can only be resized to a larger size; shrinking is not supported.
Hetzner Cloud Volume resize only allows increasing size, not shrinking.
The hcloud volume resize --size flag takes an integer value in GB and is required.
Volumes can be resized without data loss but only expanded (not shrunk), up to 10TB
Volumes have an independent lifecycle from servers — they persist when the attached server is deleted
Volumes are location-bound and must be in the same datacenter as the attached server
Maximum Hetzner Cloud Volume size is 10TB per volume
Maximum of 16 volumes can be attached to a single Cloud Server
Volumes are raw block devices that must be formatted before use
Volumes are triple-replicated across physical servers using a Ceph-backed distributed storage system
Windows 32-bit CLI builds were discontinued as of hcloud CLI v1.58.0.
hcloud zone add-records auto-creates the target RRSet if it does not already exist.
hcloud zone add-records requires three positional arguments: zone, record name, and record type.
The --record and --records-file options in hcloud zone add-records are mutually exclusive.
TTL in hcloud zone add-records is set at the RRSet level, not per individual record.
Hetzner Cloud DNS zone files use BIND format per RFC 1034/1035.
The default zone mode for hcloud zone create is primary.
The --enable-protection flag on hcloud zone create only supports delete as a value.
Secondary zones require the --primary-nameservers-file option when created with hcloud zone create.
The hcloud zone create --zonefile flag accepts - for stdin input.
Zone file import via hcloud zone import-zonefile replaces all existing RRSets — it is destructive, not additive.
Zone resource protection must be explicitly disabled before a zone can be deleted or modified.
Secondary DNS zones have configurable primary nameservers via hcloud zone change-primary-nameservers.
hcloud zone add-records appends to an RRSet, set-records replaces an RRSet, and remove-records deletes from an RRSet — three distinct operations.
The default hcloud CLI config file location is ~/.config/hcloud/cli.toml.
The default Hetzner Cloud API endpoint is https://api.hetzner.cloud/v1; the Hetzner (non-cloud) endpoint is https://api.hetzner.com/v1.
The hcloud floating-ip assign command takes two positional arguments: <floating-ip> and <server>.
Creating a Floating IP requires --type (ipv4 or ipv6) and exactly one of --home-location or --server.
A Floating IP must be explicitly assigned to a server before it routes traffic to that server.
Creating a Floating IP with --type ipv6 allocates a /56 network, while --type ipv4 gives a single address.
A Floating IP can only be assigned to servers in its home location.
Delete protection is the only protection type available for Floating IPs.
Floating IPs can be reassigned between servers (not permanently bound to one server).
Floating IPs exist independently of servers and persist after server deletion.
Specifying --server when creating a Floating IP automatically sets the home location based on that server's location.
There is no hcloud image create subcommand — images are created indirectly via hcloud server create-image (snapshots) or uploaded.
The hcloud image update command modifies image metadata, not the image content itself.
Primary IPs are bound to a server's lifecycle while Floating IPs are independent of any server.
Hetzner Cloud resources are available in six locations: FSN1, NBG1, HEL1, HIL, ASH, SIN.
The Hetzner Storage Box API endpoint (api.hetzner.com/v1) differs from the Cloud API endpoint (api.hetzner.cloud/v1), controlled by --hetzner-endpoint vs --endpoint flags.
Hetzner provides hybrid cloud-dedicated server connectivity at both Layer 2 (vSwitch network subnets with route exposure) and Layer 7 (Load Balancer targets with private IP routing), enabling unified infrastructure management across server types.
vSwitch provides Layer 2 connectivity between cloud and dedicated servers, with cloud-side support via vswitch-type subnets and route exposure — enabling hybrid architectures that span both Hetzner product lines.
Hybrid cloud-dedicated operations have a fundamental temporal mismatch — cloud resources converge through async polling (500ms CLI intervals, SDK WaitFor primitives) measured in seconds, while dedicated server lifecycle operations (boot config effective only on next restart, failover IP pre-staging across all targets) unfold over minutes to hours, creating fundamentally different operational cadences within a single deployment.
Hetzner Cloud images have an indirect lifecycle — no direct image create command exists (images are created via server create-image), updates modify only metadata (not content), deprecated images are blocked by default, and image type must be explicitly specified — making images a derived artifact of server operations rather than an independently managed resource.
Hetzner Cloud includes DDoS protection, firewalls, private networks, IPv6, and 24/7 support at no additional cost — infrastructure-level services are not metered separately from compute.
Hetzner provides a fully managed ingress pipeline from DNS resolution through TLS termination to hybrid load balancing — BIND-compatible zones with 16 record types, automatic certificate lifecycle via Let's Encrypt, HTTP/2 by default, sticky sessions, and cloud/dedicated server targeting — all within a single provider's control plane with no third-party dependencies required.
International Hetzner deployments face constraints at every architectural layer: compounded economic disadvantage (40x less traffic, missing Object Storage, third-party-operated facilities) AND structural lock-in (volumes, Floating IPs, and networks all location-bound), making cross-region architectures spanning EU and non-EU locations simultaneously more expensive, less feature-complete, and less flexible than EU-only deployments.
International Hetzner deployments face compounded disadvantage: systematically reduced included resources (40x less traffic, no Object Storage) AND the same billing traps (powered-off servers billed, IPv4 charged when unassigned), making non-EU total cost highly unpredictable.
Non-EU Hetzner locations are systematically disadvantaged: third-party operated, missing Object Storage, and 20-40x less included traffic than EU sites — making EU the only first-class deployment target.
Hetzner offers three IP types with distinct lifecycle semantics: Primary IPs (server-bound but persistent), Floating IPs (location-scoped, fully independent), and Alias IPs (multiple per server on a network) — each serving different HA and multi-homing patterns.
Hetzner Cloud Load Balancers use hourly billing with monthly caps, with pricing varying by region.
HTTP/2 is enabled by default on Hetzner Cloud Load Balancers.
Load Balancers can target both cloud VMs and dedicated servers, and with private-only mode plus label-selector dynamic targeting, they serve as the traffic entry point for hybrid architectures spanning both Hetzner product lines.
Hetzner load balancers provide integrated TLS termination with certificate management, health checking, and algorithm selection, serving as a managed ingress layer for both cloud and dedicated server targets.
Load Balancer service configuration has asymmetric per-protocol requirements — TCP demands explicit port mapping, HTTPS requires certificate attachment, while health checks share defaults (15s/10s/3) across all three protocols.
Hetzner Cloud Load Balancers can target both cloud servers and dedicated root servers.
Hetzner Cloud offers three load balancer tiers: LB11, LB21, and LB31.
Hetzner Cloud Load Balancers support two balancing algorithms: Round Robin and Least Connections.
Hetzner Load Balancers serve as unified ingress gateways combining hybrid cloud/dedicated targeting, integrated TLS termination with managed certificates and HTTP/2, dynamic label-selector service discovery, and private-only operation — converging multiple infrastructure concerns in a single resource.
LB11 supports 5 services, 25 targets, 10 SSL certificates, and 1 TB included traffic.
LB21 supports 15 services, 75 targets, 25 SSL certificates, and 2 TB included traffic.
LB31 supports 30 services, 150 targets, 50 SSL certificates, and 3 TB included traffic.
Consolidating resources in a single Hetzner location simplifies operations but concentrates exposure to location-specific billing characteristics and traffic cost asymmetries.
Hetzner is consolidating resource placement around locations (deprecating datacenter-level flags for servers, Primary IPs, and attributes) while simultaneously enforcing location-level resource binding (volumes, Floating IPs, networks) — reinforcing an architecture where location is the fundamental, inescapable unit of deployment and capacity planning.
Hetzner enables a fully managed private ingress pipeline from DNS resolution through TLS termination to hybrid load balancing at zero additional network/security cost — a complete ingress story without third-party dependencies or per-feature charges.
Multi-project Hetzner deployments require per-project Cloud API tokens plus account-level Robot API and Storage Box credentials, creating a credential management surface that grows with the number of projects.
Hetzner Cloud network connections are redundant 10 Gbit.
Hetzner Cloud networks follow a hierarchical zone-based topology — locations contain datacenters, subnets scope to network zones (not individual datacenters), and networks support three sub-resource types (subnets, routes, labels) with three subnet types (cloud, server, vswitch) — creating a multi-layered addressing model where the zone is the fundamental reachability boundary.
Hetzner Cloud private networks span within a single datacenter location.
Object Storage is available in only 3 of 6 Hetzner locations (FSN1, HEL1, NBG1 — all EU), leaving US (ASH, HIL) and APAC (SIN) workloads without local object storage.
Hetzner's built-in safety mechanisms have parallel gaps across both resource protection (predominantly delete-only, no role-based or conditional guards) and billing (hidden cost traps for idle and international resources), requiring external governance tooling for production-grade operational safety.
Hetzner placement groups support only the 'spread' strategy and servers are assigned to a placement group at creation time, providing anti-affinity for fault-domain distribution.
The combination of powered-off servers still being billed and IPv4 addresses being charged even when unassigned creates cost traps for idle resources that only deletion eliminates.
Primary IPs demand explicit lifecycle strategy decisions at creation time — type-locked (IPv4 vs IPv6), independently persistent by default (surviving server deletion), with optional auto-delete creating a binary choice between resource leak risk (orphaned charged IPs) and accidental deletion risk, while IPv4 charges accrue even on unassigned IPs.
Hetzner provides private networking, stateless firewalls, and DDoS protection at no additional cost, enabling network-isolated infrastructure without per-feature security charges.
Hetzner Cloud supports fully private infrastructure stacks — servers without public IPs, load balancers in private-only mode, and private networks — accessible only via jump hosts, VPNs, or internal LBs.
Hetzner enables complete private ingress architectures at zero additional network security cost — private-only load balancers with hybrid cloud/dedicated targeting serve as the sole entry point, backed by free stateless firewalls and DDoS protection, with no public IP exposure required for backend compute or storage infrastructure.
Hetzner's resource protection is broad in coverage (spans most resource types with multi-layer safeguards) but shallow in granularity — predominantly delete-only, with servers being the sole exception adding rebuild protection — creating a safety net that prevents accidental destruction but not accidental misconfiguration.
Included traffic varies 40x between EU (20TB) and Singapore (0.5TB), making region selection a primary cost driver for egress-heavy workloads.
Delete-only protection is the dominant protection pattern across Hetzner Cloud resources (Load Balancers, Primary IPs, Floating IPs, Networks, Volumes, Storage Boxes, Zones, RRSets), with servers being the notable exception that also supports rebuild protection.
Multiple core Hetzner Cloud resources — Volumes, Floating IPs, and private Networks — are bound to a single datacenter location, creating tight regional coupling that prevents cross-location resource mobility and constrains multi-region architecture patterns.
The Robot API enforces an aggressive security posture with IP blocking after 3 failed authentication attempts (10-minute lockout), variable rate limits calibrated to endpoint destructiveness (10/hr for destructive operations up to 5000/hr for queries), and HTTP Basic Auth requiring credential management per request.
The Hetzner Robot API base URL is https://robot-ws.your-server.de, distinct from the Cloud API at api.hetzner.cloud.
Robot API error responses use a structured { "error": { "status", "code", "message" } } JSON format.
The Robot API uses HTTP Basic Auth with Robot panel credentials, not Bearer tokens or API tokens like the Cloud API.
The Robot API combines legacy design conventions with aggressive security enforcement — HTTP Basic Auth over URL-encoded POST bodies, but with IP blocking after 3 failures and variable rate limits — creating an API that is simultaneously harder to integrate with and less forgiving of integration mistakes.
The Robot API uses legacy web conventions (HTTP Basic Auth, URL-encoded POST bodies, YAML via URL suffix) that contrast with the Cloud API's modern Bearer-token JSON design, reflecting its older dedicated-server heritage.
The Robot API manages dedicated/bare-metal servers only; cloud VMs are managed through the separate Cloud API.
Robot API POST parameters use application/x-www-form-urlencoded encoding, not JSON request bodies.
Robot API rate limits vary per endpoint from 10/hr (destructive ops like MAC generation, WOL) to 5000/hr (IP/subnet queries).
Three failed Robot API authentication attempts block the requesting IP for 10 minutes.
Appending .yaml to any Robot API endpoint returns YAML output instead of the default JSON.
Robot API boot configuration endpoints control what boots on the next server restart — rescue, Linux install, VNC install, or Windows install — each activated/deactivated via API.
Failover IPs must be configured on all potential destination servers before routing can be switched, not just the active target.
Robot API server cancellations can be both created (POST) and revoked (DELETE).
The hcloud zone rrset create flags --record and --records-file are mutually exclusive.
The hcloud zone rrset create command requires --name, --type, and one of --record or --records-file.
An RRSet (Resource Record Set) groups DNS records sharing the same name and type within a zone.
RRSet resource protection must be disabled before the RRSet can be deleted.
RRSets support three distinct record mutation commands: add-records (append), remove-records (selective delete), and set-records (full replace).
TTL is managed at the RRSet level via change-ttl, not per individual DNS record.
Hetzner's safety model is fundamentally user-responsible — both data protection (explicit backup/snapshot strategy with inverse cost/control tradeoffs) and resource protection (shallow delete-only guards without RBAC) require active user management rather than safe-by-default behavior.
Hetzner's safety and security model requires external unification — built-in protections are both shallow (delete-only, no RBAC) and inconsistent across APIs (aggressive Robot auth vs permissive Cloud), creating gaps that no single platform-native mechanism addresses.
SDK version migration cascades through the entire Hetzner automation ecosystem — hcloud-go's strict two-version support window and breaking v1→v2 changes (int to int64 IDs) propagate through the three-layer toolchain (CLI → SDK → Terraform provider), potentially forcing coordinated upgrades across all automation layers simultaneously.
Hetzner's Go SDK enforces a strict support window — v1 dropped Feb 2025 after v2's breaking ID type change (int to int64), only latest two Go versions supported — requiring proactive dependency management for any Go-based automation.
Hetzner enables secure hybrid cloud-dedicated architectures at zero additional network security cost — private networks, free firewalls and DDoS protection, vSwitch Layer 2 bridging, and private-mode Load Balancers all compose without per-service charges.
Hetzner's security posture is inconsistent across product lines — the Robot API enforces aggressive authentication security (IP blocking after 3 failures, rate limiting as low as 10/hr) while Cloud resource protection is broad but shallow (predominantly delete-only, no RBAC or conditional guards) — creating uneven security guarantees that require per-product-line security assessment rather than platform-wide assumptions.
Hetzner server creation involves multiple configuration dimensions (server type, image, location, network, SSH keys, user data, labels) where the defaults (auto-assigned IPv4/IPv6, no private network, no volumes) shape the initial topology and must be considered before creation since some are difficult to change afterward.
Server creation involves a wide decision surface where critical choices lock in permanently — placement group assignment is immutable post-creation (spread-only, creation-time binding), location determines all downstream resource constraints (Volumes, IPs, Networks), and the complex defaults matrix means implicit choices (auto-start, dual-stack, no placement group) have lasting architectural consequences.
Server lifecycle operations form a graceful-to-destructive spectrum in matched pairs: shutdown/reboot (graceful ACPI), poweroff/reset (hard immediate), rebuild (destructive OS reinstall) — each escalation level trading safety for reliability of effect.
Hetzner Cloud's four server series (CX shared, CPX dedicated, CCX high-memory dedicated, CAX ARM) span the full compute spectrum from cost-optimized shared workloads to memory-intensive dedicated applications.
Hetzner Cloud servers can be created without Primary IPs to make them private-network-only.
The tension between EU data sovereignty (self-operated German datacenters, co-located Object Storage, complete storage palette) and international reach (third-party facilities, missing Object Storage, 40x traffic cost asymmetry, location-bound resources) is irreconcilable within Hetzner alone — organizations needing both sovereign EU operations and international presence must adopt multi-provider architectures from the start, before location lock-in makes migration prohibitive.
Hetzner's network security layer — stateless firewalls with 5 protocols and hardware-based DDoS protection — operates at the infrastructure level at no additional cost, but the stateless design requires applications to handle connection tracking.
Storage Box access control is granular but operationally fragmented — subaccounts provide delegated access, but password management is reset-only (no set), home directory changes require a separate command, and general properties vs access settings use distinct update commands.
Creating a Storage Box requires four flags: --name, --type, --location, and --password
Storage Boxes adopt a secure-by-default isolation posture — external reachability is disabled by default requiring explicit opt-in, they operate on the separate Hetzner platform API (not the Cloud API), and they function as network-attached storage architecturally distinct from cloud-native block volumes.
hcloud storage-box describe supports JSON, YAML, and custom format string output formats
Storage Box external reachability is not enabled by default; it must be explicitly set with --reachable-externally
Storage Boxes are network-attached storage, a separate product from Hetzner Cloud Volumes (which are block storage)
Hetzner Storage Boxes support multiple access protocols (SSH/SCP, SFTP, rsync, Samba/CIFS, WebDAV, HTTPS) providing flexible data access patterns for different use cases from command-line backup to web-based file management.
Delete protection is the only protection type available for Storage Boxes (unlike servers which also have rebuild protection)
Storage Boxes are accessible via CIFS/SMB, SFTP, SCP, rsync, and BorgBackup protocols.
Storage Boxes occupy an operationally isolated position within the Hetzner ecosystem — secure by default (external reachability disabled) and on a separate API from cloud resources, with fragmented access control (reset-only passwords, separate home directory commands) — making integration into automated cloud workflows disproportionately complex relative to their storage utility.
Storage Box snapshots support the standard Hetzner label system via add-label and remove-label subcommands.
Changing a Storage Box subaccount's home directory uses a separate change-home-directory command rather than the general update command.
Storage Box subaccount password management uses reset-password (not set-password) — passwords can only be reset, not arbitrarily set.
Storage Box subaccounts have two distinct update commands: update for general properties and update-access-settings for protocol/access controls.
Storage Boxes support automatic snapshot plans and rollback to a previous snapshot state
Storage Boxes support subaccounts for delegated or segmented access control
Storage Boxes support a ZFS snapshot folder feature that can be made visible via --enable-zfs
Storage Boxes support three access protocols — Samba, SSH, and WebDAV — each toggled independently at creation time
Storage Box commands use the Hetzner platform API (api.hetzner.com/v1), distinct from the Hetzner Cloud API (api.hetzner.cloud/v1)
Acceptance tests (make testacc) create real Hetzner Cloud resources and incur costs; unit tests (make test) do not
The HCLOUD_TOKEN environment variable provides API authentication for the Terraform provider and its tests
The Terraform provider is built on top of the hcloud-go Go SDK for API communication
The provider's Go code has no backwards-compatibility guarantee; only HCL usage is considered stable
The Terraform provider registry identifier is hetznercloud/hcloud (not hetzner/hcloud)
Local provider development uses devoverrides in a .tfrc CLI config file pointed to by TFCLICONFIGFILE
The Hetzner Cloud Terraform provider uses Terraform Plugin Protocol version 6
The provider supports both Terraform and OpenTofu (any tool implementing Plugin Protocol v6)
Terraform provider development has no sandbox path — acceptance tests create real Hetzner Cloud resources incurring actual charges, local development requires CLI config file overrides via TFCLICONFIGFILE, and authentication relies entirely on the HCLOUDTOKEN environment variable with no mock or test-credential alternative.
TXT DNS records must consist of one or many quoted strings of up to 255 characters; the hcloud CLI will auto-format unquoted TXT records.
Volume attachment is an operationally non-trivial workflow with implicit ordering dependencies — exclusive single-server binding enforced, raw block device requiring manual formatting, automount conditional on server being specified at creation, and location co-residency required — making automated volume orchestration a multi-step process that cannot be simplified to a single API call.
Hetzner Cloud Volumes provide durable block storage (triple-replicated Ceph, expand-only resize) but are constrained to a single location and 10TB maximum, making cross-location replication an application-level concern.
Hetzner Volumes are highly durable (triple-replicated Ceph, expand-only resize) but architecturally constrained to single-server use cases — single writer at every layer (Cloud API one-attachment limit, CSI RWO-only) combined with location binding and 10TB caps rules out shared-storage, distributed filesystem, and cross-location replication patterns natively.
Hetzner Volumes impose rigid per-server operational constraints beyond their architectural single-writer limitation — maximum 16 attachments per server, raw block devices requiring explicit formatting before use (ext4 or xfs only), and automount dependent on server attachment at creation time.
Hetzner volumes enforce single-writer semantics at every layer of the stack: one server attachment at a time (Cloud API), ReadWriteOnce-only access mode (CSI/Kubernetes), and location-bound placement — ruling out shared-storage patterns without external solutions.
vSwitch provides Layer 2 connectivity between Hetzner Cloud servers and dedicated servers.