Первые шаги с Terraform
Знакомство с Terraform на Debian или Ubuntu: провайдеры, plan, apply, управление состоянием и защита секретов на универсальном примере.
На этой странице
Ваши значения
Укажите их один раз, и команды в руководстве обновятся.
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:
terraform {
required_version = ">= 1.11"
required_providers {
local = {
source = "hashicorp/local"
version = "~> 2.9"
}
random = {
source = "hashicorp/random"
version = "~> 3.9"
}
}
}Объявление переменных
Создайте variables.tf:
variable "ssh_user" {
description = "SSH-пользователь серверов"
type = string
}
variable "servers" {
description = "Серверы для добавления в инвентарь (имя => IP-адрес)"
type = map(string)
validation {
condition = length(var.servers) > 0
error_message = "Объявите хотя бы один сервер."
}
}Задайте им значения в terraform.tfvars, который загружается автоматически:
ssh_user = "ВАШ_ПОЛЬЗОВАТЕЛЬ"
servers = {
web1 = "IP_ВАШЕГО_СЕРВЕРА"
}Описание ресурсов
Создайте шаблон инвентаря inventory.tftpl:
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}Затем создайте main.tf:
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:
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:
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_:
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 не сохранит его ни в состоянии, ни в плане.
variable "api_token" {
description = "Токен API, используемый провайдером"
type = string
sensitive = true
ephemeral = true
}Эфемерную переменную нужно снова передавать при terraform apply, и её нельзя использовать в любом аргументе. Для хранилища секретов обратитесь к руководству Установка HashiCorp Vault.
Удалённое хранение состояния
Как только проектом пользуются несколько человек или машин, поместите состояние в удалённое хранилище, зашифрованное, приватное и с блокировкой. Вот универсальный пример с бэкендом s3, который нужно добавить в блок terraform:
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 и аргументы вымышленные:
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 -upgradeBackend 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.jsonNo value for required variable
Задайте переменную в terraform.tfvars, через -var или через TF_VAR_имя.
План хочет заменить ресурс
Найдите в плане пометку forces replacement. Если вы лишь переименовали ресурс, используйте terraform state mv или блок moved, а не соглашайтесь на его пересоздание.