Hetzner · Cloud

Terraform и Hetzner Cloud: провайдер hcloud, серверы, сеть, Firewall и DNS

Обновлено

Terraform позволяет описать инфраструктуру Hetzner Cloud кодом: серверы, сети, файрволы, тома и DNS-записи создаются одной командой, изменения видны заранее в terraform plan, а конфигурацию можно хранить в git. Официальный провайдер — hetznercloud/hcloud, его поддерживает сама Hetzner; на ноябрь 2026 года актуальна версия 1.70.2 (выпущена 26 октября 2026 года, релизы на GitHub). Ниже — рабочий проект от установки до импорта уже существующих серверов, с примечаниями для тех, кто работает из России.

Цикл работы Terraform с Hetzner Cloud: код .tf, init, plan, apply, ресурсы в проекте и файл состояния
Цикл работы: код, план изменений, применение, состояние.

Что понадобится

  • 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.