Боль, которую мы закрываем, простая. Ты нашел в интернете пример на HCL, скопировал, запустил terraform init - и получил то таймаут до registry.terraform.org, то ошибку аутентификации, то непонятное folder_id is required. После этого урока ни одна из этих формулировок тебя не удивит.
Ставим Terraform и OpenTofu
Сначала о том, что вообще ставить. Terraform - продукт HashiCorp, с 2023 года он под лицензией BSL (не совсем open source). В ответ сообщество сделало форк OpenTofu - полностью открытый, совместимый по командам и формату state. На уровне команд это почти близнецы: где у одного terraform, у другого tofu. Весь HCL, все провайдеры, вся логика из этого курса работают одинаково. Выбирай по вкусу и по требованиям компании; если сомневаешься - бери OpenTofu, меньше юридических вопросов.
Самый бытовой способ установки по системам.
Linux (Debian/Ubuntu, через пакетный репозиторий HashiCorp):
Код: Выделить всё
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
Код: Выделить всё
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
# или OpenTofu:
brew install opentofu
Код: Выделить всё
winget install Hashicorp.Terraform
# или OpenTofu:
winget install OpenTofu.Tofu
Код: Выделить всё
terraform version
# либо
tofu version
Код: Выделить всё
tenv tf install 1.9.8
tenv tf use 1.9.8
tenv tofu install latest
Готовим Yandex Cloud: облако, каталог, сервисный аккаунт
Чтобы Terraform мог что-то создать, ему нужны три вещи: куда складывать ресурсы и чем доказать, что он это ты. Разберем иерархию Yandex Cloud, потому что она прямо отражается в настройках провайдера.
- Облако (cloud) - верхний контейнер, у него есть cloud_id.
- Каталог (folder) - внутри облака, именно сюда обычно и кладутся ресурсы; у него folder_id.
- Сервисный аккаунт (service account) - робот, от имени которого Terraform ходит в API. Ему выдают роли.
Код: Выделить всё
curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
exec -l $SHELL
yc init
Код: Выделить всё
yc config list
yc resource-manager cloud list
yc resource-manager folder list
Код: Выделить всё
yc iam service-account create --name tf-sa
yc resource-manager folder add-access-binding <folder_id> \
--role editor \
--subject serviceAccount:<service_account_id>
yc iam key create \
--service-account-name tf-sa \
--output key.json
Настраиваем провайдер yandex
Когда есть идентификаторы и ключ, описываем провайдер. Минимальный блок выглядит так (имена атрибутов взяты из документации провайдера, не выдумывай свои):
Код: Выделить всё
terraform {
required_providers {
yandex = {
source = "yandex-cloud/yandex"
version = ">= 0.100.0"
}
}
}
provider "yandex" {
service_account_key_file = "key.json"
cloud_id = "b1gxxxxxxxxxxxxxxxxx"
folder_id = "b1gyyyyyyyyyyyyyyyyy"
zone = "ru-central1-d"
}
Код: Выделить всё
provider "yandex" {
token = "t1.xxxxx..."
cloud_id = "b1gxxxxxxxxxxxxxxxxx"
folder_id = "b1gyyyyyyyyyyyyyyyyy"
zone = "ru-central1-d"
}
Код: Выделить всё
export YC_SERVICE_ACCOUNT_KEY_FILE="key.json"
export YC_CLOUD_ID="b1gxxxxxxxxxxxxxxxxx"
export YC_FOLDER_ID="b1gyyyyyyyyyyyyyyyyy"
export YC_ZONE="ru-central1-d"
А вот и главная российская засада. По умолчанию source = "yandex-cloud/yandex" разворачивается в полный адрес registry.terraform.org/yandex-cloud/yandex, и при terraform init клиент идет качать плагин именно с registry.terraform.org. С территории РФ этот реестр часто недоступен напрямую, и init виснет на стадии Initializing provider plugins или падает по таймауту.
Лечится это зеркалом. Yandex Cloud держит собственное зеркало провайдеров. Самый чистый способ - прописать его в файле конфигурации CLI ~/.terraformrc (на Windows - %APPDATA%/terraform.rc):
Код: Выделить всё
provider_installation {
network_mirror {
url = "https://terraform-mirror.yandexcloud.net/"
}
direct {
exclude = ["registry.terraform.org/*/*"]
}
}
Обзор основных команд CLI
Дальше весь курс крутится вокруг короткого набора команд. Запомни их сейчас.
- terraform init - инициализация рабочего каталога: качает провайдеры (через зеркало), готовит backend для terraform state. Запускается первым.
- terraform fmt - выравнивает форматирование .tf по канону. Привыкай гонять перед каждым коммитом.
- terraform validate - проверяет синтаксис и согласованность конфигурации, не ходя в облако.
- terraform plan - показывает, что будет создано, изменено и удалено. Сухой прогон без последствий.
- terraform apply - применяет план, реально создавая ресурсы. Спросит подтверждение yes.
- terraform destroy - сносит все, что описано в конфиге. На учебном стенде - твой лучший друг против лишних счетов.
Типичные грабли
- Таймаут на init из РФ - забыл зеркало. Симптом: висит на Initializing provider plugins. Лечение - ~/.terraformrc выше.
- token и service_account_key_file одновременно - провайдер ругнется. Оставь что-то одно.
- Старый source = "yandex.cloud/yandex" из древних гайдов. Правильный адрес - yandex-cloud/yandex (через дефис).
- key.json уехал в git - классика и беда. Сразу в .gitignore, а если уже закоммитил - ключ считается скомпрометированным, отзывай его в консоли.
- folder_id is required - не задан каталог ни в провайдере, ни через YC_FOLDER_ID.
- IAM-токен протух - живет около 12 часов. Для долгой работы бери ключ сервисного аккаунта.
Повтори руками, без этого дальше будет тяжело:
- Поставь Terraform или OpenTofu и проверь terraform version.
- Через yc init залогинься и забери cloud_id, folder_id командой yc config list.
- Создай сервисный аккаунт tf-sa, выдай роль editor, выгрузи key.json.
- Пропиши зеркало в ~/.terraformrc.
- Сделай папку, положи туда блок terraform {} и provider "yandex" {} из урока, запусти terraform init и убедись, что плагин скачался с зеркала. Затем terraform validate.
- Чем OpenTofu отличается от Terraform и почему их команды взаимозаменяемы?
- Какие два взаимоисключающих способа аутентификации есть у провайдера yandex и в каком случае какой удобнее?
- Почему terraform init может зависнуть из РФ и как именно это чинит зеркало terraform-mirror.yandexcloud.net?
- В каком порядке идут init, plan и apply и зачем вообще нужен отдельный шаг plan?
Terraform и OpenTofu - почти одно и то же, выбирай и не мучайся. Для работы с Yandex Cloud нужны cloud_id, folder_id, зона и способ входа: ключ сервисного аккаунта (надежнее) или IAM-токен (на 12 часов). Секреты держи в переменных окружения YC_*, а не в .tf. Из России обязательно прописывай зеркало провайдеров в ~/.terraformrc, иначе terraform init не достучится до registry.terraform.org. И заучи шесть команд: init, fmt, validate, plan, apply, destroy - на них держится вся инфраструктура как код. В следующем уроке наконец создадим первую реальную виртуалку.
