tf_provider/docs/curated/pipeline/vdc_edge_ip_snat.md

Как развернуть цепочку: vDC → Edge → внешние IP → SNAT → vApp → ВМ → Штурвал

Пошаговая инструкция. Готовые файлы примера — в репозитории tf_examples, папка fullpipe_chain.

Что получится в итоге:

• виртуальный датацентр (vDC);
• сетевой шлюз периметра (Edge) с балансировщиком AVI;
• внешние IP на организации;
• SNAT на шлюзе;
• виртуальный каталог (vApp) и виртуальная машина (ВМ) внутри него — с доступом по SSH;
• Kubernetes-кластер Штурвал (сервис 150) на этой сети.

Организацию создайте заранее в ЛК — Terraform её не создаёт и не удаляет. Кластер Штурвал создаётся десятки минут, поэтому провайдер ждёт его до часу (operation_timeout = "60m"); ВМ тоже создаётся небыстро (у неё отдельный таймаут 15m), остальные ресурсы — минуты.

Что нужно перед началом

Требование	Зачем	Где смотреть
Terraform 1.5 или новее	работает провайдер	terraform version
Токен API	доступ к ЛК	ЛК → Профиль → Токены → «Технический»
Организация в Cloud Director	всё создаётся внутри неё	услуга «Организация в Cloud Director»
Edge с балансировщиком AVI	без ALB кластер Штурвал не поднимется	nsxt_need_enable_avi = true, nsxt_virtual_services_count >= 3
Внешние IP: не меньше 3 + 1 под ВМ	адрес Kubernetes API, адрес Ingress, адрес ВМ и запас	ip_count = "4"
SNAT на Edge	выход в интернет для машин кластера и для ВМ	ресурс nubes_vc_nsxt_snat
Публичный SSH-ключ	вход на ВМ по SSH	~/.ssh/id_ed25519.pub → vm_user_public_key
Запас vCPU в vDC	Штурвал занимает 8 vCPU из 8 при настройках по умолчанию, и тогда ВМ не включится	vdc_cpu_allocated

Порядок из чек-листа услуги 150 (именно так связаны ресурсы в примере): организация → vDC → Edge (ALB, AVI ≥ 3) → внешние IP (≥ 3) → SNAT → vApp → ВМ → кластер Штурвал. Минимум для кластера: 1 мастер-нода и 1 воркер-нода по 4 vCPU / 8 ГБ RAM / 50 ГБ диска; минимум для ВМ: 1 vCPU / 1 ГБ RAM (в примере — 2 vCPU / 2 ГБ).

1. Скачайте пример

git clone https://gitea.services.ngcloud.ru/Nail/tf_examples.git
cd tf_examples/fullpipe_chain

Понадобится Terraform 1.5 или новее. Провайдер скачается сам при terraform init.

2. Возьмите значения в ЛК

Значение	Где взять	Пример
api_token	ЛК → Профиль → Токены → «Технический»	eyJhbGciOi...
organization	ЛК → услуга «Организация в Cloud Director» → название услуги	organ
vdc_network_provider	ЛК → создание vDC → «Сетевой провайдер»	snb1
vdc_provider_vdc	ЛК → создание vDC → «Provider VDC»	Intel Broadwell 2.4
vdc_storage_config	ЛК → создание vDC → доступные дисковые политики	SATA
ip_space_name	ЛК → карточка организации → внешние IP	internet-ipv4-v1

3. Заполните значения

cp terraform.tfvars.example terraform.tfvars
nano terraform.tfvars

Файл terraform.tfvars выглядит так:

# Токен из ЛК
api_token = "eyJhbGciOi..."

# Организация из ЛК (создана заранее)
organization = "organ"

# Внешние IP
ip_space_name = "internet-ipv4-v1"
ip_count      = "4"                        # 3 под Штурвал + 1 под ВМ

# vDC
vdc_resource_name    = "fullpipe-vdc"          # имя услуги в ЛК, любое
vdc_network_provider = "snb1"                  # ЛК → создание vDC → «Сетевой провайдер»
vdc_provider_vdc     = "Intel Broadwell 2.4"   # ЛК → создание vDC → «Provider VDC»
vdc_cpu_allocated    = 8                       # vCPU, шт.
vdc_cpu_guaranteed   = 0                       # резервирование vCPU, %: 0, 50 или 80
vdc_mem_allocated    = 32                      # RAM, ГБ
vdc_storage_config   = "[{\"name\":\"SATA\",\"size\":\"200\"}]"   # политика и размер, ГБ

# Edge (сетевой шлюз периметра)
nsxt_resource_name          = "fullpipe-edge"  # имя услуги в ЛК, любое
nsxt_vdc_type               = "vdc"            # родитель: vdc или vdcGroup
nsxt_need_enable_avi        = true             # балансировщик AVI (ALB)
nsxt_virtual_services_count = 3                # виртуальных сервисов AVI: 1..4 (Штурвал: не меньше 3)
nsxt_ip_addr_pool           = "10.10.102.0/24" # пул адресов routed-сети, маска /24
nsxt_main_dns               = "81.22.46.22"    # основной DNS
nsxt_second_dns             = "185.247.187.77" # второй DNS

# vApp и ВМ
vapp_name          = "fullpipe-vapp-01"    # имя vApp: маска ^[a-z0-9][a-z0-9.-]{3,61}[a-z0-9]$, уникально в организации
vm_name            = "web01"              # имя ВМ: задаёт имя IP Set {vapp_name}-{vm_name}
vm_image           = "Ubuntu_22-20G"      # RockyLinux_9-16G-cloudinit | Ubuntu_22-20G | Debian_13-20G
vm_cpu             = 2                    # vCPU, 1..64
vm_ram             = 2                    # RAM, ГБ, 1..256
vm_disk            = 20                   # дополнительный диск, ГБ
vm_user_login      = "ubuntu"             # учётка SSH
vm_user_public_key = "ssh-ed25519 AAAA..." # содержимое ~/.ssh/id_ed25519.pub
vm_same_snat       = false                # false — за общим SNAT шлюза

Описание всех параметров — в variables.tf. terraform.tfvars с токеном никому не передавайте и не коммитьте в git.

4. Выполните команды

terraform init     # один раз — скачает провайдер
terraform plan     # покажет, что будет создано: 7 ресурсов (vDC, Edge, IP, SNAT, vApp, ВМ, Штурвал)
terraform apply    # создаст (подтвердить: yes)

5. Проверьте результат

terraform output   # UUID и имена созданных услуг

И в ЛК: появились vDC, Edge, vApp с ВМ и кластер Штурвал, на организации выделены внешние IP, на шлюзе включён SNAT. Повторный terraform plan должен показать No changes.

Адрес ВМ виден в terraform output vm_state_flat — поля externalConnect (внешний IP), internalConnect (адрес в routed-сети) и fqdn: ssh <vm_user_login>@<externalConnect>.

Кластер создаётся десятки минут — провайдер ждёт его (operation_timeout = "60m"), в ЛК он появится со статусом running. Адреса Kubernetes API и Ingress — в terraform output shturval_state_params (поля kubernetesApiAddress и ingressAddress).

6. vApp и ВМ

Виртуальная машина живёт внутри vApp: vApp привязывается к vDC (vdc_uid) и к Edge (nsxt_uid), а ВМ — к vApp (vapp_uid) и получает адрес в routed-сети шлюза. Своей сети у vApp нет.

Ресурс	Услуга	Ключевые параметры
nubes_vapp	26	vapp_name (уникальное в организации, маска DNS-имени), vdc_uid, nsxt_uid
nubes_vc_vm_v3	28	vapp_uid, vm_name, vm_cpu, vm_ram, vm_disk, image_vm, user_login, user_public_key, ip_space_name, access_port_list

Параметры ВМ

Параметр	Значения
image_vm	RockyLinux_9-16G-cloudinit, Ubuntu_22-20G, Debian_13-20G
vm_cpu / vm_ram	1..64 шт. / 1..256 ГБ
vm_disk	дополнительный диск, ГБ (основной диск зависит от образа)
user_login	учётка SSH (по умолчанию myuser)
access_port_list	[{ "port": "22", "type": "tcp" }]; type — tcp, udp или all
access_ip_list	белый список адресов; по умолчанию ["0.0.0.0/0"]

image_vm, vm_name, user_login, user_public_key и vapp_uid — create-only (менять нельзя). vm_cpu, vm_ram, vm_disk, access_port_list, ip_space_name меняются операцией modify.

Внешний доступ

ip_space_name	Что это значит
internet-ipv4-v1	у ВМ есть внешний адрес: в vm_state_flat появятся externalConnect и fqdn
no-needed	внешнего адреса нет, доступ только изнутри

Адрес берётся из квоты организации, поэтому при внешнем доступе нужен 4-й адрес (ip_count = "4"). При same_snat = false (по умолчанию) ВМ публикуется за общим SNAT шлюза.

Пример результата на живом стенде:

vm_state_flat = {
  "externalConnect" = "185.247.187.235"
  "internalConnect" = "10.10.102.4"
  "fqdn"            = "web01.85ea682f-...dev.nubes.ru"
}

Что проверять при создании ВМ

1. Запас vCPU в vDC. Штурвал при настройках по умолчанию занимает 8 vCPU из 8 (2 ноды × «TKG 4CPU 8RAM»). Тогда ВМ не включится: платформа отдаёт [400:VALIDATION] Unable to perform this action на этапе power-on, а инстанс остаётся в статусе not created. Лечится увеличением vdc_cpu_allocated.
2. Квота IP. ip_count ≥ 4, иначе внешний адрес для ВМ не выделится.
3. Ключ. Публичный ключ кладите в terraform.tfvars, не в репозиторий.
4. Время. ВМ создаётся и включается с customization (запись учётки и ключа) — на живом стенде операция шла больше 15 минут. В примере стоит operation_timeout = "15m"; при медленной платформе увеличьте его. Симптом таймаута — «операция … не завершилась за установленный таймаут».
5. Проверка. ssh <vm_user_login>@<externalConnect> и terraform plan → No changes.

7. Удаление: «заморозка» вместо удаления

terraform destroy

По умолчанию пример повторяет рабочую конфигурацию — при destroy объекты не удаляются:

Ресурс	Что делает destroy	Флаг в примере
Кластер Штурвал	suspend: выключается, данные и адреса сохраняются	suspend_on_destroy = true
vDC	suspend	suspend_on_destroy = true
Edge	не трогается: у эджа нет операции suspend	keep_on_destroy = true
SNAT	не выключается	keep_on_destroy = true
Квота внешних IP	не меняется: адреса держит кластер Штурвала	keep_on_destroy = true
vApp	suspend: выключаются все ВМ внутри каталога	suspend_on_destroy = true
ВМ	suspend	suspend_on_destroy = true

Приоритет флагов: keep_on_destroy важнее suspend_on_destroy. Следующий apply усыновит объекты по имени и разморозит кластер и vDC (adopt_existing_on_create = true → resume). Организация не удаляется никогда.

Полное удаление — осознанно: поставьте keep_on_destroy = false и suspend_on_destroy = false и удаляйте по порядку: кластер → ВМ → vApp → квота IP (count = 0) → SNAT → Edge → vDC. Квоту нельзя опустить ниже занятых адресов, поэтому — только после удаления кластера и ВМ; vApp удаляется лишь после suspend (полное удаление — через 14 дней), а vDC — через 14 дней после suspend.

Файлы примера

Файл	Что делает
versions.tf	версия Terraform и провайдера Nubes
provider.tf	подключение к API (токен, адрес)
variables.tf	все параметры с описанием
vdc.tf	виртуальный датацентр
edge.tf	сетевой шлюз периметра (Edge)
modifiers.tf	внешние IP на организации + SNAT на шлюзе
vm.tf	vApp и ВМ: переменные vApp/ВМ, оба ресурса и выводы (отключается удалением файла)
shturval.tf	Kubernetes-кластер Штурвал: переменные Штурвала, группы воркеров и сам ресурс
outputs.tf	UUID и имена созданных услуг (vDC, Edge, vApp, ВМ, Штурвал)
terraform.tfvars.example	шаблон значений (копируется в terraform.tfvars)

Подробнее про два последних ресурса — на странице «Ресурсы-модификаторы (IP организации, SNAT)».