Как работает Terraform-провайдер Cloud.ru Evolution

Базовая архитектура: Terraform и провайдер

В работе Terraform можно выделить две основные части:

• Terraform — читает ваши .tf-файлы, отвечает за описание и управление инфраструктурным графом и состоянием, определяет последовательность операций — создать, обновить, удалить — и ничего не знает о платформе Evolution.

• Провайдер Cloud.ru — плагин, который выступает в роли «переводчика». Провайдер преобразует команды из манифеста в конкретные HTTP-вызовы к API продуктов Cloud.ru. Например, POST /v1/instances. Все взаимодействие с облаком происходит через его публичное API.

Цикл жизни: plan, apply и state

1. terraform plan — что будет сделано?

   1. Провайдер получает список ресурсов и их желаемое состояние.

   2. Для каждого ресурса в конфигурации провайдер запрашивает у API его текущее состояние (если ресурс уже существует). Для этого используется уникальный идентификатор, хранящийся в файле состояния .tfstate.

   3. Провайдер сравнивает желаемое состояние (код) с актуальным состоянием (из API).

   4. Результат сравнения по каждому ресурсу (create, update, delete, no-op) возвращается для формирования плана.

2. terraform apply — применяет манифест.

   1. Terraform определяет порядок операций на основе зависимостей (ресурс сети создается до ВМ).

   2. Terraform вызывает соответствующую функцию провайдера, например CreateInstance, UpdateLoadBalancer, для каждой операции.

   3. Провайдер выполняет операции строго последовательно в рамках одного ресурса. Он не может одновременно изменить размер диска и переименовать его.

   4. Это одна операция UPDATE к API, которая может включать несколько полей, но выполняется как единый вызов.

3. Файл состояния .tfstate.

   1. Для Terraform этот источник — единственный, по которому он определяет, какие ресурсы им управляются.

   2. После успешного применения провайдер записывает в состояние идентификаторы, возвращенные API (например, vm-12345). Без этих ID провайдер не сможет найти ресурс в облаке при следующем запуске.

      Внимание

      Не редактируйте этот файл вручную. Расшаривайте его через удаленный бэкенд, например, S3.

Ключевые ограничения и модели поведения

Понимание этих моментов спасет от многих часов отладки:

• Атомарность операций

  С точки зрения Cloud.ru, изменение ресурса (update) — это чаще всего замена или пересоздание (recreate), а не «патч». Например, изменение типа машины обычно требует остановки, удаления и создания новой. Провайдер пытается это смягчить, но логика зашита в API облака.

• Зависимости и параллелизм

  Terraform создает независимые ресурсы параллельно для скорости. Если ВМ A зависит от сети B (через depends_on или ссылку), провайдер создаст B первым, дождется успеха, а затем начнет создание A.

• Обработка ошибок и идемпотентность

  • Если операция создания завершилась ошибкой 409 Conflict (ресурс уже существует), провайдер не удалит его автоматически. Он попытается считать его атрибуты и «подхватить» в управление (import).

  • Провайдер стремится к идемпотентности: повторный вызов apply с той же конфигурацией не должен ничего менять в облаке (вы получите план «No changes»).

• Rate Limiting и квоты API

  Провайдер делает прямые вызовы к API. Если вы упретесь в лимиты запросов в секунду или в квоты своей учетной записи (например, «не более 5 IP-адресов»), API вернет ошибку, и apply встанет. Провайдер может использовать retry с экспоненциальной задержкой, но это не поможет при исчерпании квот.

• Чтение-после-записи (Read-after-write)

  Иногда ресурс в API появляется не мгновенно. После вызова Create, провайдер делает периодические запросы Read, чтобы дождаться перехода ресурса в статус ACTIVE и считать все его вычисляемые атрибуты (IP-адрес, DNS-имя).

• Роли и ограничения

  Администратор, использующий Terraform для управления облачной инфраструктурой, действует в рамках ролевой модели и политики доступа. Перед настройкой Terraform необходимо ознакомиться с документацией по ролям и определить минимальный набор разрешений, необходимый для создания, изменения и удаления ресурсов.

Отладка: что происходит под капотом?

Включите детальное логирование export TF_LOG=DEBUG. Вы увидите все HTTP-запросы и ответы между провайдером и API. Это главный инструмент для понимания того, «что пошло не так».

Внимание

В случае возникновения ошибок при работе с ресурсами, если вы не до конца понимаете, в чем проблема, рекомендуем включить режим детального логирования!

Если кто-то вручную изменил ресурс в облаке через личный кабинет или через API напрямую, следующее выполнение terraform plan обнаружит расхождение между фактическим состоянием и стейтом и предложит сделать refresh. Старайтесь избегать этого дрейфа состояний – используйте одну точку входа для управления облачной инфраструктурой.

Примечание

Дрейф состояния - это ситуация, при которой реальное состояние инфраструктуры отличается от того, что Terraform записал в своем .tfstate-файле.

Используйте terraform validate — при использовании данной команды, Terraform проверит ваши tf-файлы на корректность HCL-синтаксиса и согласованность конфигурации независимо от текущего состояния инфраструктуры и переменных. Применение ее перед terraform plan и terraform apply поможет избежать проблем на начальном этапе.

Проверяйте справочник API Cloud.ru Evolution — возможно существуют ограничения платформы.

Изучите примеры конфигураций — актуальные примеры ресурсов и источников данных доступны в разделе Справочник.

Итоговая модель

Главный принцип можно сформулировать следующим образом: Terraform принимает решения, какие изменения необходимы, а провайдер отвечает за то, как эти изменения выполнить в Evolution.