sless-primer/VM/README.md

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

⚠️ Тестовое окружение. Пример работает с тестовым API Nubes и тестовым кластером sless. Не использовать в продакшне без предварительного согласования.

В этом примере используются только разовые джобы (sless_job) — для установки ПО на ВМ. Примеры с HTTP-сервисами (sless_service) появятся позднее.

Создаёт:

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

---

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

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.

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

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

---

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

cp terraform.tfvars.template terraform.tfvars

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

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 и т.д.) можно менять в любое время.

---

Запуск

terraform init
terraform apply

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

Outputs:

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

---

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

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:

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:

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

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

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

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

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

---

Удаление

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-ключ — создаётся вами на Шаге 2, в git не хранится
functions/	Код Python-функций для install-джобов