diff --git a/generated/test/docs/getting-started.md b/generated/test/docs/getting-started.md new file mode 100644 index 0000000..cccdbcd --- /dev/null +++ b/generated/test/docs/getting-started.md @@ -0,0 +1,291 @@ +# Начало работы с 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 +```