Terraform позволяет описать инфраструктуру Hetzner Cloud кодом: серверы, сети, файрволы, тома и DNS-записи создаются одной командой, изменения видны заранее в terraform plan, а конфигурацию можно хранить в git. Официальный провайдер — hetznercloud/hcloud, его поддерживает сама Hetzner; на ноябрь 2026 года актуальна версия 1.70.2 (выпущена 26 октября 2026 года, релизы на GitHub). Ниже — рабочий проект от установки до импорта уже существующих серверов, с примечаниями для тех, кто работает из России.
Что понадобится
- Terraform 1.5 или новее (блоки
import, используемые ниже, появились в 1.5) или совместимый OpenTofu. - Проект в Hetzner Console и API-токен с правами Read & Write (Security → API tokens). Токен действует на один проект.
- SSH-ключ ed25519 (
ssh-keygen -t ed25519). - По желанию — hcloud CLI: им удобно смотреть доступные типы серверов, образы и локации.
Установка Terraform и доступ к реестру из России
Обычный путь — скачать Terraform с сайта HashiCorp или установить из пакетного репозитория. Из российских сетей сайт HashiCorp и реестр registry.terraform.io бывают недоступны; на это прямо указывают, например, авторы провайдера HOSTKEY в своей документации. Рабочие варианты:
- Зеркало Yandex Cloud. Дистрибутивы Terraform выложены на
https://hashicorp-releases.yandexcloud.net/terraform/, а для провайдеров есть сетевое зеркало. Его подключают в файле настроек CLI:~/.terraformrcв Linux и macOS,%APPDATA%\terraform.rcв Windows (документация Yandex Cloud; аккаунт в Yandex Cloud не нужен). - OpenTofu. Открытый форк Terraform с собственным реестром; провайдер Hetzner доступен в нём под тем же адресом
hetznercloud/hcloud, а синтаксис конфигурации совпадает.
Настройка зеркала провайдеров:
provider_installation {
network_mirror {
url = "https://terraform-mirror.yandexcloud.net/"
include = ["registry.terraform.io/*/*"]
}
direct {
exclude = ["registry.terraform.io/*/*"]
}
}
Проверка установки: terraform version. Если после настройки зеркала провайдер не скачивается, удалите каталог .terraform в проекте и выполните terraform init -upgrade.
Структура проекта
Для небольшого проекта достаточно нескольких файлов в одном каталоге:
hetzner-infra/
├── versions.tf # версии Terraform и провайдера
├── variables.tf # параметры
├── main.tf # ресурсы
├── outputs.tf # что вывести после apply
├── cloud-init.yaml # первичная настройка серверов
├── terraform.tfvars # значения переменных (не коммитить, если там секреты)
└── .gitignore
В .gitignore сразу добавьте файлы состояния и локальный кэш:
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
crash.log
Провайдер и токен
Файл versions.tf. Ограничение ~> 1.70 разрешает обновления внутри ветки 1.x начиная с 1.70, но не перескок на 2.0:
terraform {
required_version = ">= 1.5.0"
required_providers {
hcloud = {
source = "hetznercloud/hcloud"
version = "~> 1.70"
}
}
}
# Токен берётся из переменной окружения HCLOUD_TOKEN
provider "hcloud" {}
Токен не пишите в файлы конфигурации. Передайте его через окружение:
export HCLOUD_TOKEN="..." # Linux, macOS
$env:HCLOUD_TOKEN = "..." # PowerShell
Провайдер также принимает аргумент token (например, из переменной с sensitive = true), а аргументами poll_interval и poll_function настраивается частота опроса API, если вы упираетесь в ограничения запросов (документация провайдера).
Переменные
Файл variables.tf:
variable "location" {
description = "Локация Hetzner Cloud: fsn1, nbg1, hel1, ash, hil, sin"
type = string
default = "fsn1"
}
variable "server_type" {
description = "Тип сервера, список: hcloud server-type list"
type = string
default = "cx23"
}
variable "web_count" {
type = number
default = 2
}
variable "admin_ips" {
description = "Адреса, с которых разрешён SSH"
type = list(string)
default = ["203.0.113.10/32"]
}
variable "ssh_public_key_path" {
type = string
default = "~/.ssh/id_ed25519.pub"
}
variable "domain" {
type = string
default = "example.ru"
}
Тип cx23 используется в примерах документации провайдера; актуальный список типов и их доступность по локациям смотрите командой hcloud server-type list -o columns=name,cores,memory,disk,location_available. Линейки Hetzner меняются, а часть типов бывает временно недоступна в отдельных локациях.
Ресурсы: ключ, сеть, файрвол, серверы
Файл main.tf. Серверы получают метку role=web, и файрвол применяется к ним по этой метке — новые серверы с той же меткой будут защищены автоматически.
resource "hcloud_ssh_key" "admin" {
name = "admin"
public_key = file(pathexpand(var.ssh_public_key_path))
}
resource "hcloud_network" "main" {
name = "main"
ip_range = "10.0.0.0/16"
}
resource "hcloud_network_subnet" "main" {
type = "cloud"
network_id = hcloud_network.main.id
network_zone = "eu-central"
ip_range = "10.0.1.0/24"
}
resource "hcloud_firewall" "web" {
name = "web"
rule {
direction = "in"
protocol = "tcp"
port = "22"
source_ips = var.admin_ips
description = "ssh"
}
rule {
direction = "in"
protocol = "tcp"
port = "80"
source_ips = ["0.0.0.0/0", "::/0"]
}
rule {
direction = "in"
protocol = "tcp"
port = "443"
source_ips = ["0.0.0.0/0", "::/0"]
}
rule {
direction = "in"
protocol = "icmp"
source_ips = ["0.0.0.0/0", "::/0"]
}
apply_to {
label_selector = "role=web"
}
}
resource "hcloud_server" "web" {
count = var.web_count
name = "web-${count.index + 1}"
image = "ubuntu-24.04"
server_type = var.server_type
location = var.location
ssh_keys = [hcloud_ssh_key.admin.id]
user_data = file("${path.module}/cloud-init.yaml")
backups = true
labels = {
role = "web"
env = "prod"
}
public_net {
ipv4_enabled = true
ipv6_enabled = true
}
network {
subnet_id = hcloud_network_subnet.main.id
ip = "10.0.1.${count.index + 10}"
alias_ips = []
}
lifecycle {
ignore_changes = [ssh_keys, user_data]
}
}
Пояснения к неочевидным местам:
network_zone = "eu-central"— сетевая зона для европейских локаций fsn1, nbg1 и hel1. Сервер и подсеть должны быть в одной зоне.alias_ips = []рекомендует сама документация провайдера: без этого из-за известной ошибки Terraform 1.4+ сервер может отключаться от сети и подключаться заново при каждом apply.ignore_changes = [ssh_keys, user_data]: SSH-ключи и cloud-init применяются только при создании, и их изменение в коде заставило бы Terraform пересоздать сервер вместе с диском.backups = trueвключает автоматические резервные копии — это платная опция; уберите её, если копии делаете сами.- Аргумент
datacenterустарел с версии провайдера 1.67.0; указывайтеlocation.
Файл cloud-init.yaml для первичной настройки:
#cloud-config
package_update: true
package_upgrade: true
packages: [ufw, fail2ban, unattended-upgrades]
runcmd:
- ufw default deny incoming
- ufw allow 22/tcp
- ufw allow 80/tcp
- ufw allow 443/tcp
- ufw --force enable
Почему ufw на сервере нужен даже при Cloud Firewall — в статье Hetzner Cloud Firewall или ufw.
Том, обратная DNS-запись и DNS-зона
Добавьте в main.tf том для данных, PTR-записи для серверов и DNS-зону. DNS-зоны Hetzner управляются тем же провайдером через ресурсы hcloud_zone и hcloud_zone_rrset.
resource "hcloud_volume" "data" {
name = "data"
size = 50
location = var.location
format = "ext4"
}
resource "hcloud_volume_attachment" "data" {
volume_id = hcloud_volume.data.id
server_id = hcloud_server.web[0].id
automount = true
}
resource "hcloud_rdns" "web" {
count = var.web_count
server_id = hcloud_server.web[count.index].id
ip_address = hcloud_server.web[count.index].ipv4_address
dns_ptr = "web-${count.index + 1}.${var.domain}"
}
resource "hcloud_zone" "main" {
name = var.domain
mode = "primary"
ttl = 3600
}
resource "hcloud_zone_rrset" "apex" {
zone = hcloud_zone.main.name
name = "@"
type = "A"
ttl = 300
records = [for s in hcloud_server.web : { value = s.ipv4_address }]
}
resource "hcloud_zone_rrset" "hosts" {
count = var.web_count
zone = hcloud_zone.main.name
name = "web-${count.index + 1}"
type = "A"
records = [{ value = hcloud_server.web[count.index].ipv4_address }]
}
Чтобы зона начала обслуживаться, у регистратора домена нужно указать NS-серверы Hetzner — их покажет вывод ниже. Если домен уже работает у другого DNS-провайдера, создавайте зону только после переноса всех существующих записей.
Выходные значения
Файл outputs.tf:
output "web_ipv4" {
value = { for s in hcloud_server.web : s.name => s.ipv4_address }
}
output "web_ipv6" {
value = { for s in hcloud_server.web : s.name => s.ipv6_address }
}
output "nameservers" {
value = hcloud_zone.main.authoritative_nameservers.assigned
}
Запуск: init, plan, apply
terraform init # скачает провайдер hetznercloud/hcloud
terraform fmt -recursive # выровняет форматирование
terraform validate # проверит синтаксис и ссылки между ресурсами
terraform plan -out tfplan # покажет, что будет создано
terraform apply tfplan # применит именно этот план
terraform output web_ipv4
Читайте план перед каждым apply. Строки must be replaced или -/+ у сервера означают удаление и создание заново — с потерей данных на диске. Чаще всего так срабатывает смена образа, локации или изменение аргумента, который нельзя поменять на живом сервере.
Изменение типа сервера (server_type) Terraform выполняет без пересоздания, но с выключением сервера на время операции. Если нужно оставить возможность уменьшить тип позже, используйте аргумент keep_disk = true.
Импорт уже существующих серверов
Если серверы создавались вручную в консоли, их можно взять под управление Terraform без пересоздания. Узнайте ID через hcloud server list и добавьте блок import:
import {
to = hcloud_server.legacy
id = "12345678"
}
import {
to = hcloud_firewall.legacy
id = "87654321"
}
Затем попросите Terraform сгенерировать описание ресурсов по их текущему состоянию:
terraform plan -generate-config-out=generated.tf
Проверьте сгенерированный файл, уберите лишние вычисляемые атрибуты и добейтесь, чтобы terraform plan показывал «No changes». Только после этого выполняйте terraform apply, который запишет ресурсы в состояние. Для старых версий Terraform есть команда terraform import hcloud_server.legacy 12345678.
Защита от случайного удаления
Аргумент delete_protection = true включает защиту в самом Hetzner, но, как сказано в документации провайдера, Terraform снимает эту защиту при удалении ресурса. От ошибочного terraform destroy защищает только lifecycle:
resource "hcloud_server" "db" {
name = "db-1"
image = "ubuntu-24.04"
server_type = "cx33"
location = "fsn1"
delete_protection = true
rebuild_protection = true
lifecycle {
prevent_destroy = true
}
}
У сервера delete_protection и rebuild_protection должны иметь одинаковые значения.
Состояние и секреты
- Файл
terraform.tfstateсодержит ID ресурсов, адреса, а иногда и чувствительные данные. Не коммитьте его в git. - Если с инфраструктурой работают несколько человек или CI, вынесите состояние в удалённый бэкенд с блокировками (например, S3-совместимое хранилище) и закройте к нему доступ.
- Для разных окружений (prod, stage) используйте разные проекты Hetzner и разные токены: токен действует на один проект, и ошибка в stage не заденет prod.
- Выданные токены периодически перевыпускайте, а старые удаляйте в консоли.
Удаление и переезд
terraform destroy удаляет всё, что описано в конфигурации. Это удобно для временных стендов и для завершения переезда к другому провайдеру: после переноса данных одна команда убирает все ресурсы Hetzner, и за них перестают начислять деньги. Пошагово переезд описан в статьях Миграция Hetzner Cloud в Timeweb Cloud и Переезд с Hetzner на HOSTKEY; у обоих провайдеров есть свои Terraform-провайдеры, так что подход «инфраструктура как код» сохраняется.
Типичные ошибки
- Тип сервера недоступен или устарел. Apply падает с ошибкой о типе сервера: проверьте
hcloud server-type listи колонкуdeprecated, выберите актуальный тип и локацию, где он есть. - Сервер пересоздаётся после правки cloud-init. Добавьте
user_dataвignore_changesили меняйте настройку уже работающих серверов через Ansible. - Сервер постоянно переподключается к сети. Задайте
alias_ips = []в блокеnetwork. - Ошибки 429 (rate limit) при большом числе ресурсов. Увеличьте
poll_intervalв блоке провайдера и уменьшите параллелизм:terraform apply -parallelism=5. - Файрвол назначен дважды. Не смешивайте
apply_toс меткой иfirewall_idsу сервера для одного и того же файрвола: используйте один способ. - Провайдер не скачивается. Проверьте доступ к реестру и настройку зеркала в
.terraformrcилиterraform.rc.
Частые вопросы
Какую версию провайдера hcloud использовать?
Актуальную из ветки 1.x: на ноябрь 2026 года это 1.70.2. Указывайте ограничение вида ~> 1.70 и обновляйтесь осознанно, прочитав список изменений: в нём объявляются устаревшие аргументы, например datacenter.
Где взять токен для Terraform?
В Hetzner Console откройте проект, раздел Security → API tokens, и создайте токен с правами Read & Write. Передавайте его через переменную окружения HCLOUD_TOKEN, а не в файлах конфигурации.
Можно ли управлять выделенными серверами Hetzner через этот провайдер?
Нет, провайдер hetznercloud/hcloud работает с Hetzner Cloud: серверы, сети, файрволы, тома, балансировщики, DNS-зоны, Storage Box. Выделенные серверы из Robot управляются через Robot Webservice — см. справку об API Hetzner.
Что делать, если registry.terraform.io недоступен?
Подключите сетевое зеркало провайдеров Yandex Cloud в файле настроек CLI или используйте OpenTofu с его реестром. Синтаксис конфигурации при этом не меняется.
Можно ли перенести существующие серверы под Terraform без простоя?
Да. Блоки import и команда terraform plan -generate-config-out создают описание по текущему состоянию ресурсов, ничего не пересоздавая. Важно добиться пустого плана перед первым apply.