tf_provider/generated/test/docs/getting-started.md

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

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

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

Версия 1.0 или выше.

1. Скачать: hashicorp.com/terraform/install или Yandex Cloud Mirror (без VPN)
2. Установить: распаковать, положить terraform в PATH
3. Проверить: terraform -version

---

1. Конфигурация провайдера

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

terraform {
  required_providers {
    nubes = {
      source  = "registry.kube5s.ru/nubes-test/nubes"
      version = "5.1.2"
    }
  }
}

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
}

!!! info "TEST стенд" - Личный кабинет: https://deck-test.ngcloud.ru/dashboard/ - API: https://lk-api-gateway-test.ngcloud.ru/api/v1/svc

!!! tip "Безопасность" Не храните токен в main.tf. Используйте terraform.tfvars или переменные окружения.

---

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

1. Зайдите в Личный кабинет → Профиль → Токены
2. Нажмите «Выпустить тех-токен»
3. Сохраните токен — он показывается только один раз

Создайте terraform.tfvars:

api_token = "eyJhbGciOi..." # Ваш токен

---

3. Команды Terraform

terraform init

Загружает провайдер. Выполняется один раз при старте проекта. При смене версии — terraform init -upgrade.

terraform init

terraform plan

Показывает что будет создано/изменено/удалено. Безопасно, ничего не меняет.

terraform plan

terraform apply

Применяет изменения. Создаёт/меняет/удаляет ресурсы в облаке.

terraform apply
# или сразу без подтверждения:
terraform apply -auto-approve

terraform destroy

Удаляет ВСЕ ресурсы из манифеста.

terraform destroy

!!! warning "Suspend vs Destroy" По умолчанию terraform destroy не удаляет инстанс — переводит в Suspend. См. раздел 5.

terraform state list / terraform state show

Просмотр ресурсов под управлением Terraform.

terraform state list
terraform state show nubes_postgres.baza

---

4. Примеры ресурсов

PostgreSQL

Скопируйте из примера PostgreSQL — заполните TODO своими значениями.

resource "nubes_postgres" "baza" {
  resource_name = "pg-tst01"

  cluster_configuration {
    cpu      = 500
    memory   = 512
    replicas = 1
    disk     = 10
  }

  startup_configuration {
    resource_realm = "k8s-3-sandbox-nubes-ru"
  }

  access_configuration {
    master_access_list = jsonencode(["10.0.0.0/8"])
    master_ip_space    = "no-needed"
    slave_access_list  = jsonencode([])
    slave_ip_space     = "no-needed"
  }

  postgres_configuration {
    version       = "17"
    ssl_required  = true
    pooler_master = false
    pooler_slave  = false
  }

  backup_configuration {
    s3_uid   = "UUID-вашего-S3" # Обязательно
    retain   = 7
    schedule = "0 0 * * *"
  }

  autoscale_configuration {
    enabled  = false
    schedule = 0
    percent  = 10
    quota    = 100
  }
}

S3 Bucket

resource "nubes_s3bucket" "my_files" {
  resource_name = "bucket_0"
  bucket_name   = "my-unique-bucket-name"
  s3_user_uid   = "UUID-вашего-S3"
}

Подробные примеры — в разделе Ресурсы (левое меню), вкладка Example у каждого ресурса.

---

5. Suspend, Adopt и жизненный цикл

Провайдер не удаляет инстансы при terraform destroy по умолчанию. Вместо этого переводит в Suspend.

suspend_on_destroy (по умолчанию true)

Значение	terraform destroy	Удаление из манифеста
true	Инстанс → Suspend	Инстанс → Suspend
false	Только удаление из state	Только удаление из state

adopt_existing_on_create (по умолчанию false)

Значение	Поведение при apply
false	Если инстанс уже есть → ошибка
true	running → adopt под управление; suspended + совпадение параметров → resume + adopt

operation_timeout

Таймаут ожидания операции. По умолчанию "10m". Для долгих операций можно увеличить:

operation_timeout = "15m"

!!! warning "Один инстанс — один state" Не подключайте один инстанс к двум манифестам — получите конфликт управления.

---

6. Связка сервисов (Lucee + PostgreSQL)

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

  startup_configuration {
    resource_realm = "k8s-3-sandbox-nubes-ru"
  }

  cluster_configuration {
    cpu      = 500
    memory   = 512
    replicas = 1
    disk     = 10
  }

  access_configuration {
    master_access_list = jsonencode(["10.0.0.0/8"])
    master_ip_space    = "no-needed"
    slave_access_list  = jsonencode([])
    slave_ip_space     = "no-needed"
  }

  postgres_configuration {
    version       = "17"
    ssl_required  = true
    pooler_master = false
    pooler_slave  = false
  }

  backup_configuration {
    s3_uid   = "UUID-вашего-S3"
    retain   = 7
    schedule = "0 0 * * *"
  }

  autoscale_configuration {
    enabled  = false
    schedule = 0
    percent  = 10
    quota    = 100
  }
}

resource "nubes_lucee" "app1" {
  resource_name  = "lucy1"
  resource_realm = nubes_postgres.db2.startup_configuration.resource_realm
  domain         = "web03"
  git_path       = "https://github.com/user/repo.git"

  json_env = jsonencode({
    testds_class            = "org.postgresql.Driver"
    testds_bundleName       = "org.postgresql.jdbc"
    testds_bundleVersion    = "42.6.0"
    testds_connectionString = "jdbc:postgresql://$${nubes_postgres.db2.state_out_flat[\"internalConnect.master\"]}:5432/postgres"
    testds_username         = nubes_postgres.db2.vault_secrets["adminUser"]
    testds_password         = nubes_postgres.db2.vault_secrets["adminPass"]
  })

  app_version = "5.4"

  depends_on = [nubes_postgres.db2]
}

---

7. Типичный рабочий процесс

# 1. Клонируем/создаём проект
mkdir my-infra && cd my-infra

# 2. Создаём main.tf (скопировать из примера выше)
# 3. Создаём terraform.tfvars с токеном

# 4. Инициализация
terraform init

# 5. Проверка плана
terraform plan

# 6. Применение
terraform apply

# 7. При необходимости — удаление
terraform destroy