RU

Приложения

Первые шаги с Terraform

Знакомство с Terraform на Debian или Ubuntu: провайдеры, plan, apply, управление состоянием и защита секретов на универсальном примере.

6 мин чтения, обновлено 18 ноября 2026 г.

На этой странице

Ваши значения

Укажите их один раз, и команды в руководстве обновятся.

Terraform описывает инфраструктуру в текстовых файлах, сравнивает это описание с существующим состоянием и применяет только необходимые изменения. Он опирается на провайдеры (providers), которые умеют взаимодействовать с конкретным сервисом.

В этом руководстве основы показаны на примере, который работает без внешних аккаунтов: Terraform генерирует случайный пароль, инвентарь Ansible и локальный файл конфигурации.

Термин Значение
Провайдер Расширение, дающее доступ к сервису или ресурсу
Ресурс Объект, которым управляет Terraform
Переменная Входное значение конфигурации
Выходное значение (output) Значение, доступное после применения
План Список изменений, которые предлагает Terraform
Состояние (state) Файл, связывающий конфигурацию с реальными объектами

Предварительные требования

  • Машина под Debian 12/13 или Ubuntu 22.04/24.04: ваш компьютер или сервер администрирования
  • Пользователь с правами sudo
  • Исходящий доступ по HTTPS к apt.releases.hashicorp.com и registry.terraform.io

Terraform не слушает ни одного порта, и для этого примера не нужно открывать никаких входящих портов.

Установка Terraform

Добавьте официальный репозиторий HashiCorp, затем установите пакет:

Терминал
sudo apt update
sudo apt install -y wget gpg lsb-release
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y terraform
terraform version

Создание проекта

Терминал
mkdir -p ~/terraform-demo
cd ~/terraform-demo

Объявление Terraform и провайдеров

Создайте versions.tf:

hcl
terraform {
  required_version = ">= 1.11"

  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.9"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.9"
    }
  }
}

Объявление переменных

Создайте variables.tf:

hcl
variable "ssh_user" {
  description = "SSH-пользователь серверов"
  type        = string
}

variable "servers" {
  description = "Серверы для добавления в инвентарь (имя => IP-адрес)"
  type        = map(string)

  validation {
    condition     = length(var.servers) > 0
    error_message = "Объявите хотя бы один сервер."
  }
}

Задайте им значения в terraform.tfvars, который загружается автоматически:

hcl
ssh_user = "ВАШ_ПОЛЬЗОВАТЕЛЬ"

servers = {
  web1 = "IP_ВАШЕГО_СЕРВЕРА"
}

Описание ресурсов

Создайте шаблон инвентаря inventory.tftpl:

Текст
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}

Затем создайте main.tf:

hcl
resource "random_password" "app_token" {
  length  = 32
  special = false
}

resource "local_file" "inventory" {
  filename        = "${path.module}/generated/inventory.ini"
  file_permission = "0644"

  content = templatefile("${path.module}/inventory.tftpl", {
    servers  = var.servers
    ssh_user = var.ssh_user
  })
}

resource "local_sensitive_file" "app_env" {
  filename        = "${path.module}/generated/app.env"
  file_permission = "0600"
  content         = "APP_TOKEN=${random_password.app_token.result}\n"
}

И outputs.tf:

hcl
output "inventory_path" {
  description = "Путь к сгенерированному инвентарю"
  value       = local_file.inventory.filename
}

output "app_token" {
  description = "Токен, сгенерированный для приложения"
  value       = random_password.app_token.result
  sensitive   = true
}

Исключение локальных файлов из Git

Создайте .gitignore до первого коммита:

Текст
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/

А вот .terraform.lock.hcl, фиксирующий точные версии провайдеров, добавьте под версионный контроль.

Инициализация и проверка

Терминал
terraform init
terraform fmt
terraform validate
Команда Действие
terraform init Загружает провайдеры и подготавливает каталог
terraform fmt Приводит форматирование к единому виду
terraform validate Проверяет согласованность конфигурации

Планирование и применение

Сохраните план, чтобы применить в точности то, что вы просмотрели:

Терминал
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

В плане + обозначает создание, ~ — изменение, - — удаление, а -/+ — замену. Всегда читайте эти строки перед применением, особенно удаления и замены.

Проверьте результат:

Терминал
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform plan

У файла app.env должны быть права -rw-------, выходное значение app_token должно отображаться как <sensitive>, а последний план должен сообщать No changes.

Изменение инфраструктуры

Добавьте сервер в terraform.tfvars:

hcl
servers = {
  web1 = "IP_ВАШЕГО_СЕРВЕРА"
  web2 = "IP_ВТОРОГО_СЕРВЕРА"
}
Терминал
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

План сообщает о замене только файла инвентаря (1 to add, 1 to destroy): токен остаётся прежним. Сгенерированный файл затем можно использовать в плейбуке, как в руководстве Автоматизация серверов с помощью Ansible.

Как устроено состояние

После apply Terraform записывает в terraform.tfstate, чем он управляет. Просматривайте его предусмотренными командами, не изменяя вручную:

Терминал
terraform state list
terraform state show local_file.inventory
Команда Назначение
terraform state list Вывести список отслеживаемых ресурсов
terraform state show АДРЕС Показать ресурс
terraform state mv ИСТОЧНИК НАЗНАЧЕНИЕ Переименовать ресурс без его пересоздания
terraform state rm АДРЕС Прекратить отслеживать ресурс, не удаляя его
terraform import АДРЕС ID Привязать существующий объект, если провайдер это поддерживает

Ограничьте права на локальные файлы до минимума:

Терминал
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || true

Управление секретами

Не помещайте секреты в файлы .tf. Передавайте их через переменную окружения TF_VAR_:

hcl
variable "api_token" {
  description = "Токен API, используемый провайдером"
  type        = string
  sensitive   = true
}
Терминал
read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_token

Если значение нужно только для настройки провайдера или для аргумента только для записи (write-only), объявите его как эфемерное: тогда Terraform не сохранит его ни в состоянии, ни в плане.

hcl
variable "api_token" {
  description = "Токен API, используемый провайдером"
  type        = string
  sensitive   = true
  ephemeral   = true
}

Эфемерную переменную нужно снова передавать при terraform apply, и её нельзя использовать в любом аргументе. Для хранилища секретов обратитесь к руководству Установка HashiCorp Vault.

Удалённое хранение состояния

Как только проектом пользуются несколько человек или машин, поместите состояние в удалённое хранилище, зашифрованное, приватное и с блокировкой. Вот универсальный пример с бэкендом s3, который нужно добавить в блок terraform:

hcl
terraform {
  backend "s3" {
    bucket       = "mon-etat-terraform"
    key          = "demo/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

Передавайте учётные данные через окружение, а не в этом блоке, затем перенесите существующее состояние:

Терминал
terraform init -migrate-state

Использование другого провайдера

Логика остаётся той же для любого сервиса, у которого есть провайдер. Найдите его в реестре Terraform, прочитайте его документацию и проверьте, кто его поддерживает. Общий вид такой. editeur/service и аргументы вымышленные:

hcl
terraform {
  required_providers {
    service = {
      source  = "editeur/service"
      version = "~> 1.0"
    }
  }
}

provider "service" {
  api_token = var.api_token
}

Выдавайте токену API только строго необходимые права и начинайте с тестового проекта: apply реально воздействует на ресурсы аккаунта.

Обновление

Terraform обновляется через APT. Провайдеры обновляются в пределах ограничений version:

Терминал
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform plan

Просмотрите план, затем, если файл .terraform.lock.hcl изменился, добавьте его под версионный контроль.

Резервное копирование

Храните конфигурацию и .terraform.lock.hcl в приватном Git-репозитории. Для состояния включите версионирование удалённого хранилища. При локальном состоянии создайте защищённую копию:

Терминал
install -m 600 /dev/null "$HOME/terraform-demo-$(date +%F).tfstate"
terraform state pull > "$HOME/terraform-demo-$(date +%F).tfstate"

Эта копия содержит секреты: храните её в зашифрованном виде и вне сервера. Если состояние потеряно, Terraform больше не знает, какими объектами он управляет.

Уничтожение ресурсов

Просмотрите удаление, затем примените его:

Терминал
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplan

В этом примере удаляются только локальные файлы и токен. С реальным провайдером эта операция может стереть службы и их данные.

Если что-то не работает

Inconsistent dependency lock file

Запрошенные провайдеры не совпадают с файлом блокировки. После проверки изменения:

Терминал
terraform init -upgrade

Backend initialization required

Конфигурация бэкенда изменилась. Снова выполните terraform init или terraform init -migrate-state, чтобы перенести состояние.

Error acquiring the state lock

Блокировку удерживает другой запуск, либо запуск был прерван. Сначала убедитесь, что ни одна команда не выполняется. Только после этого используйте выведенный идентификатор:

Терминал
terraform force-unlock ID_БЛОКИРОВКИ

Saved plan is stale

Состояние изменилось с момента создания плана. Сформируйте новый план, просмотрите его, затем примените.

Failed to query available provider packages

Проверьте имя провайдера, ограничение version и доступ к registry.terraform.io:

Терминал
curl -I https://registry.terraform.io/.well-known/terraform.json

No value for required variable

Задайте переменную в terraform.tfvars, через -var или через TF_VAR_имя.

План хочет заменить ресурс

Найдите в плане пометку forces replacement. Если вы лишь переименовали ресурс, используйте terraform state mv или блок moved, а не соглашайтесь на его пересоздание.

Справочные материалы