# Пример: Виртуальная машина (vApp + VM) в Nubes vDC

Создаёт:
- **vApp** — виртуальный каталог (контейнер для ВМ в VMware vDC)
- **ВМ** — Ubuntu 22.04, 2 CPU / 2 GB RAM / 20 GB disk
- **Serverless-джобы** — устанавливают ПО на ВМ по SSH после создания

---

## Быстрый старт

```bash
cp terraform.tfvars.template terraform.tfvars
# Заполни terraform.tfvars (инструкция ниже)
terraform init
terraform apply
```

---

## Шаг 1 — Получить данные из Личного Кабинета

### API-токен

> Личный Кабинет → правый верхний угол → **«Профиль»** → **«API-токены»** → **«Создать токен»**

Скопируйте JWT-строку целиком (`eyJhbGciOiJS...`).  
Один токен работает для обоих провайдеров — nubes (облако) и sless (serverless).

### UUID сервисов (vdc_uid и nsxt_uid)

> Личный Кабинет → **«Мои сервисы»** → нужный сервис → **«Параметры инстанса»** → поле UUID

| Параметр | Что искать в ЛК |
|---|---|
| `vdc_uid` | Сервис **«Виртуальный датацентр (vDC)»** → UUID |
| `nsxt_uid` | Сервис **«Сетевой шлюз периметра (Edge)»** → UUID |

UUID выглядит так: `e3c9e4f1-24da-4992-a003-f8a2a803a5f0`

> **Важно:** `vdc_uid` и `nsxt_uid` **не изменяются после первого `terraform apply`**.  
> Менять их нельзя — сломается terraform state.

---

## Шаг 2 — Сгенерировать SSH-ключ для ВМ

Публичный ключ прописывается в ВМ при создании — это **единственный** способ зайти по SSH.

```bash
# Выполнить в папке examples/VM/
ssh-keygen -t ed25519 -f ./vm_key -N "" -C "sless-demo-vm"
```

Создаст два файла: `vm_key` (приватный) и `vm_key.pub` (публичный).

---

## Шаг 3 — Заполнить terraform.tfvars

```bash
cp terraform.tfvars.template terraform.tfvars
```

Открыть `terraform.tfvars` и заполнить:

```hcl
api_token     = "eyJhbGciOiJS..."                        # из ЛК (шаг 1)
vm_public_key = "ssh-ed25519 AAAA..."                    # содержимое vm_key.pub (шаг 2)
vdc_uid       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"   # из ЛК (шаг 1)
nsxt_uid      = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"   # из ЛК (шаг 1)
```

Остальные параметры (`install_packages`, `base_packages` и т.д.) можно менять в любое время.

---

## Запуск

```bash
terraform init
terraform apply
```

После успешного `apply` Terraform выведет:

```
Outputs:

vm_id    = "..."
vm_state = {
  "externalIp" = "1.2.3.4"
  ...
}
vapp_id  = "..."
```

---

## Подключение по SSH

```bash
ssh -i ./vm_key ubuntu@<externalIp из vm_state>
```

Логин всегда `ubuntu`.

---

## Управление установкой ПО

Установка выполняется через serverless-джобы — Terraform запускает k8s Job, который подключается к ВМ по SSH и устанавливает пакеты.

### Флаги установки (в terraform.tfvars)

| Переменная | Что делает | По умолчанию |
|---|---|---|
| `install_packages` | Устанавливает пакеты из `base_packages` | `true` |
| `install_nginx` | Устанавливает nginx | `true` |
| `install_docker` | Устанавливает Docker CE + docker-compose-plugin | `true` |

### Как изменить список пакетов

В `terraform.tfvars`:

```hcl
base_packages = ["jq", "htop", "curl", "git", "python3-pip"]
```

Любые стандартные apt-пакеты Ubuntu 22.04.  
После изменения — увеличьте `install_run_id` и выполните `terraform apply`.

### Как перезапустить установку

sless_job — разовый джоб. При повторном `apply` Terraform не перезапускает его если ничего не изменилось.  
Чтобы запустить все install-джобы заново — увеличьте `install_run_id` на 1:

```hcl
# было:
install_run_id = 3
# стало:
install_run_id = 4
```

Затем `terraform apply`. Установка идемпотентна — повторное выполнение не ломает систему.

### Как отключить отдельный компонент

```hcl
install_docker = false   # не устанавливать Docker
```

После `apply` ресурс `sless_job.install_docker` будет удалён из state.  
Docker на уже созданной ВМ останется — Terraform не удаляет пакеты.

---

## Удаление

```bash
terraform destroy
```

Порядок автоматический: сначала suspend → потом delete.  
Параметр `suspend_on_destroy = true` решает это — без него удаление упадёт с ошибкой Nubes _«Услуга не остановлена»_.

---

## Справочник параметров

### Можно менять в любое время

| Параметр | Файл | Эффект |
|---|---|---|
| `vm_cpu`, `vm_ram`, `vm_disk` | `vm.tf` | ВМ будет изменена |
| `install_packages/nginx/docker` | `terraform.tfvars` | Джоб добавится или удалится |
| `base_packages` | `terraform.tfvars` | Пакеты изменятся — увеличить `install_run_id` + apply |
| `install_run_id` | `terraform.tfvars` | Перезапускает все install-джобы |

### Нельзя менять после первого apply

| Параметр | Файл | Причина |
|---|---|---|
| `vdc_uid`, `nsxt_uid` | `terraform.tfvars` | Идентифицируют сервисы в terraform state |
| `resource_name`, `vapp_name` | `vapp.tf` | Уникальные имена ресурсов в Nubes |
| `image_vm`, `user_login` | `vm.tf` | Неизменяемые параметры ВМ |
| `vm_public_key` | `terraform.tfvars` | Прописывается в ВМ один раз при создании |

---

## Файлы проекта

| Файл | Назначение |
|---|---|
| `terraform.tfvars.template` | **Шаблон** — скопировать в `terraform.tfvars` и заполнить |
| `terraform.tfvars` | Ваши значения (не в git — содержит секреты) |
| `main.tf` | Провайдеры + переменные `api_token` и `vm_public_key` |
| `variables.tf` | Все остальные переменные с описаниями |
| `vapp.tf` | Ресурс vApp (контейнер ВМ) |
| `vm.tf` | Ресурс ВМ (Ubuntu 22.04) |
| `sless.tf` | Serverless-джобы для установки ПО |
| `outputs.tf` | Вывод IP-адреса и ID ресурсов |
| `vm_key` / `vm_key.pub` | SSH-ключ для доступа к ВМ |
| `functions/` | Код Python-функций для install-джобов |