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

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

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

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

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

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

---

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

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

```hcl
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/](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`:

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

---

## 3. Команды Terraform

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

```bash
terraform init
```

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

```bash
terraform plan
```

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

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

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

```bash
terraform destroy
```

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

### `terraform state list` / `terraform state show`
Просмотр ресурсов под управлением Terraform.

```bash
terraform state list
terraform state show nubes_postgres.baza
```

---

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

### PostgreSQL

Скопируйте из [примера PostgreSQL](postgres_example.md) — заполните `TODO` своими значениями.

```hcl
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

```hcl
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"`. Для долгих операций можно увеличить:

```hcl
operation_timeout = "15m"
```

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

---

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

```hcl
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. Типичный рабочий процесс

```bash
# 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
```