Skip to content

Начало работы с Nubes Terraform

Это руководство поможет вам установить инструменты, настроить доступ и развернуть вашу первую инфраструктуру в облаке Nubes, используя Terraform.

ИИ-помощники на этом сайте

В правом нижнем углу сайта документации есть две кнопки:

  • «LLM» — ассистент документации. Задайте вопрос своими словами — получите ответ со ссылками на страницы документации.
  • «TF» — проверка файла. Вставьте содержимое своего terraform.tfvars — ИИ вернёт исправленный файл и список изменений (что и почему поменял). Секреты (api_token, пароли) в поле не вставляйте — держите их в отдельном файле secrets.auto.tfvars.

ИИ-агент в вашей IDE

В репозитории примеров (Nail/tf_examples) есть файл AGENTS.md — инструкция для ИИ-агентов (GitHub Copilot, Claude, Cursor и др.). Агент прочитает её сам и поможет писать и проверять конфигурацию, опираясь на реальные схемы ресурсов, а не на догадки.

Что ИИ не делает

Ассистенты только помогают: не деплоят (terraform plan/apply запускаете вы), не читают ваши секреты и не заменяют проверку конфигурации по документации.

0. Установка Terraform

Для работы с инфраструктурой как кодом (IaC) потребуется утилита Terraform (версии 1.5 или выше).

  1. Скачивание:
  2. Установка:
    • Распакуйте скачанный архив.
    • Поместите исполняемый файл (terraform или terraform.exe) в папку, доступную в переменной окружения PATH.
  3. Проверка:
    • Откройте терминал (PowerShell, CMD, Bash или Terminal в macOS).
    • Введите команду terraform -version. Вы должны увидеть номер версии.

1. Подготовка конфигурации

Создайте рабочую директорию для вашего проекта и создайте основной файл конфигурации main.tf.

main.tf
terraform {
  required_providers {
    nubes = {
      source  = "tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes"
      version = "3.6.3"
    }
  }
}

provider "nubes" {
  api_endpoint = "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc"
  api_token = var.api_token
}

variable "api_token" {
  type      = string
  sensitive = true
}

Стенд nubes-test (обязательные адреса)

Эта документация относится к стенду nubes-test.

  • Личный кабинет: https://deck-test.ngcloud.ru/dashboard/
  • API endpoint: https://lk-api-gateway-test.ngcloud.ru/api/v1/svc

Безопасность

Никогда не храните токен прямо в main.tf и не коммитьте его. Держите токен в отдельном файле secrets.auto.tfvars (добавьте его в .gitignore) или передавайте через переменную окружения TF_VAR_api_token. Сам api_token в state провайдера не сохраняется, но другие секреты (пароли БД) могут попадать в state — храните state в защищённом backend.

2. Получение API токена

Токен (Access Token) необходим провайдеру для авторизации ваших действий в облаке.

Если нет ТОКЕНА доступа или хотите создать новый - В Личном Кабинете - на странице Профиля пользователя https://deck-test.ngcloud.ru/authorization/profile во вкладке Токены - нажать "Выпустить тех-токен" Значение токена показывается только при его создании, надо его сохранить

Создайте файл secrets.auto.tfvars и сохраните токен там (сам файл добавьте в .gitignore):

secrets.auto.tfvars
api_token = "eyJhbGciOiJ..." # Ваш длинный токен

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

Добавьте ресурсы, которые вы хотите создать, в файл main.tf или resources.tf.

Значения-заглушки нужно заменить

Значения вида k8s-4-sandbox-nubes-ru, my-s3, 235e0546-... в примерах ниже — демонстрационные. Замените их на свои: resource_realm — ваша ресурсная платформа (ЛК → услуга), s3_uid / s3_user_uid — имя/UID уже существующего экземпляра S3. Если нужного S3 ещё нет — сначала создайте его в ЛК.

Пример создания S3 бакета:

resource "nubes_s3bucket" "my_files" {
  resource_name = "bucket_0"
  bucket_name   = "my-unique-bucket-name"
  s3_user_uid   = "235e0546-..." # ← ЗАМЕНИТЕ: UID Корневой услуги S3 (ЛК → S3)
}

Или Postgres кластера:

resource "nubes_postgres" "db" {
  resource_name = "pg-tst0"

  startup_configuration = {
    resource_realm = "k8s-4-sandbox-nubes-ru" # ← ЗАМЕНИТЕ: ваша ресурсная платформа (ЛК)
  }
  cluster_configuration = {
    cpu      = 500 # milicores (1000 = 1 ядро)
    memory   = 512 # MB
    replicas = 1
    disk     = 10  # GB
  }
  access_configuration = {
    master_ip_space    = "no-needed"
    master_access_list = jsonencode([])
    slave_ip_space     = "no-needed"
    slave_access_list  = jsonencode([])
  }
  postgres_configuration = {
    version       = "17"
    ssl_required  = true
    pooler_master = false
    pooler_slave  = false
  }
  backup_configuration = {
    s3_uid   = "my-s3" # ← ЗАМЕНИТЕ: имя уже существующего S3 (не UUID)
    retain   = 7
    schedule = "0 0 * * *"
  }
  autoscale_configuration = {
    enabled  = false
    schedule = 0
    percent  = 10
    quota    = 100
  }
}

Подробные примеры конфигураций смотрите в разделе Resources документации.

4. Запуск

Теперь вы готовы применить конфигурацию:

  1. Инициализация: terraform init (загружает плагин провайдера).
  2. План: terraform plan (показывает, что будет сделано).
  3. Применение: terraform apply (создает инфраструктуру).

5. Почему провайдер использует Suspend/Adopt

Полное описание

Это краткое объяснение. Подробная таблица «ресурс → что при destroy → останется ли объект и тарификация» — в разделе «Как работает провайдер» §5.

Для этой логики используются флаги:

  • suspend_on_destroy
  • keep_on_destroy
  • adopt_existing_on_create

suspend_on_destroy

  • true (по умолчанию)
  • при terraform destroy инстанс уходит в Suspend;
  • при удалении ресурса из манифеста — тоже Suspend.
  • false
  • Terraform удаляет инстанс в облаке (операция delete, только для running).

keep_on_destroy

  • true — объект остаётся в облаке, Terraform только убирает его из state (state_only). Приоритетнее suspend_on_destroy.
  • false (по умолчанию) — обычное поведение (suspend или delete).

adopt_existing_on_create

  • false (по умолчанию)
  • если инстанс уже существует, Terraform вернёт ошибку.
  • true
  • Terraform может взять существующий инстанс под управление.

Как это связано с terraform import

Это похоже на terraform import, но срабатывает в обычном apply.

  • найден running → adopt;
  • найден suspended + обязательные параметры совпадают → resume + adopt.

Важно

Один инстанс должен быть только в одном state.

Если подключить один инстанс к двум манифестам, получится конфликт управления:

  • первый apply меняет ресурс;
  • второй apply откатывает или перезаписывает изменения.

Следующий шаг: изучите Справочник по командам Terraform для уверенной работы.

Проверенные примеры

Готовые сквозные сценарии — в разделе «Проверенные примеры»: