docs: add getting-started guide with terraform init/plan/apply/destroy workflow
This commit is contained in:
“Naeel”
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user