Getting Started with the Hetzner Terraform Provider

Managing Hetzner cloud resources manually can be time‑consuming and error‑prone. The Hetzner Terraform Provider lets you define servers, networks, firewalls, and more as code, enabling repeatable and version‑controlled deployments. In this guide, we’ll walk you through installation, configuration, and common use‑cases, so you can start automating your Hetzner environment today.

Why Use Terraform with Hetzner?

• Infrastructure as Code (IaC): Store configurations in Git, review changes, and roll back with ease.
• Consistency: Avoid drift between environments by applying the same declarative definitions.
• Scalability: Provision dozens of servers or networks with a single command.
• Multi‑cloud readiness: Combine Hetzner resources with other providers (AWS, Azure) in one Terraform workspace.

Prerequisites

Before diving in, make sure you have the following:

1. A Hetzner Cloud account with an API token.
2. Terraform installed (v1.5+ recommended).
3. Basic knowledge of Terraform syntax (resources, variables, state).

Installing the Hetzner Provider

The provider is distributed through the public Terraform Registry. Add it to your main.tf file:

terraform {   required_providers {     hcloud = {       source  = "hetznercloud/hcloud"       version = "~> 1.45"     }   } } 

Run terraform init to download the plugin and initialize the working directory.

Configuring Authentication

Provide your API token using one of these secure methods:

• Environment variable: export HCLOUD_TOKEN=your-token
• Terraform variable (recommended for CI/CD):

  variable "hcloud_token" {   type = string   description = "Hetzner Cloud API token"   sensitive = true }  provider "hcloud" {   token = var.hcloud_token } 

Creating Your First Server

Below is a minimal configuration that creates a single cloud server:

resource "hcloud_server" "web" {   name        = "web-01"   image       = "ubuntu-22.04"   server_type = "cx31"   location    = "nbg1"   ssh_keys    = [hcloud_ssh_key.my_key.id] }  resource "hcloud_ssh_key" "my_key" {   name       = "my-key"   public_key = file("~/.ssh/id_rsa.pub") } 

Run terraform apply and confirm. Terraform will provision the server and output its IP address.

Adding a Firewall

Secure the server with a Hetzner firewall rule:

resource "hcloud_firewall" "web_fw" {   name = "web-fw"    rule {     direction = "in"     protocol  = "tcp"     port      = "22"     source_ips = ["0.0.0.0/0"]   }    rule {     direction = "in"     protocol  = "tcp"     port      = "80"     source_ips = ["0.0.0.0/0"]   } }  resource "hcloud_server_network" "attach_fw" {   server_id   = hcloud_server.web.id   network_id  = hcloud_firewall.web_fw.id } 

Managing Networks and Subnets

When you need isolated environments, define a private network:

resource "hcloud_network" "private" {   name    = "private-net"   ip_range = "10.0.0.0/16" }  resource "hcloud_subnet" "app" {   network_id = hcloud_network.private.id   type       = "cloud"   ip_range   = "10.0.1.0/24"   network_zone = "eu-central" } 

Attach servers to the subnet by using the hcloud_server_network resource.

State Management Best Practices

• Store state remotely (e.g., Terraform Cloud, S3 with DynamoDB lock) to enable team collaboration.
• Enable prevent_destroy on critical resources such as firewalls or load balancers.
• Use terraform fmt and terraform validate before each commit.

Common Pitfalls and How to Avoid Them

Issue	Resolution
API rate‑limit errors	Implement retry and timeouts in the provider block or batch resource creation.
Server type not available in region	Check Hetzner’s availability matrix and use lookup maps to select a supported type.
Drift after manual changes	Run terraform refresh regularly or avoid manual console edits.

FAQ

Do I need a paid Hetzner plan to use the provider?

No. The provider works with any account that has an API token, including free trial credits.

Can I manage Load Balancers with Terraform?

Yes. Use the hcloud_load_balancer resource to define listeners, target groups, and health checks.

How do I rotate SSH keys?

Update the hcloud_ssh_key resource, then run terraform apply. Existing servers will automatically receive the new key on next reboot.

Is there a way to retrieve the server’s public IP after creation?

Reference hcloud_server.web.ipv4_address in outputs or other resources.

Next Steps

Now that you have the basics down, consider these extensions:

• Deploy a hcloud_load_balancer with multiple backend servers for HA.
• Integrate hcloud_dns_record to automate DNS entries.
• Use modules to encapsulate common patterns (e.g., web‑tier, database‑tier).

Call to Action

Ready to automate your Hetzner infrastructure? Download the starter Terraform module and kick off your first deployment today!