CloudRouterAdvanced/docs/QUICKSTART.md

Quick Start (самостоятельное развёртывание)

Пошаговая инструкция для самостоятельного развёртывания сценария из этого репозитория на VK Cloud.

1. Подготовка

• Аккаунт VK Cloud с включённым API/CLI-доступом, project_id.
• SSH-ключ загружен в VK Cloud (имя ключа понадобится в terraform.tfvars).
• Установлены terraform (≥1.13) и ansible.

2. Клонировать репозиторий и задать credentials

Начиная с появления второго окружения (mvm-s3, см. docs/changes/2026-09-09-mvm-s3-external-networks-*.md), в этом каталоге terraform/ живут конфиги нескольких VK Cloud проектов одновременно — поэтому credentials больше не подхватываются автоматически (*.auto.tfvars), а передаются явным -var-file для каждого окружения. Так один набор реальных credentials никогда не «протечёт» в apply другого окружения.

terraform/terraform.tfvars — закоммиченный обезличенный шаблон (общие некоторые значения), реальные credentials в него вписывать не нужно. Для PROD скопируйте terraform/prod.secrets.tfvars.example в terraform/prod.secrets.tfvars (этот файл в .gitignore, никогда не попадёт в git) и впишите туда реальные значения:

auth_url         = "https://infra.mail.ru:35357/v3/"
username         = "<ваш VK Cloud логин или сервисный аккаунт>"
password         = "<пароль>"
project_id       = "<ваш project_id>"
region           = "RegionOne"
user_domain_name = "users"   # или "service-users" для сервисного аккаунта svc-*

Если у вас есть openrc.sh для сервисного аккаунта — соответствие полей: OS_AUTH_URL→auth_url, OS_USERNAME→username, OS_PASSWORD→password, OS_PROJECT_ID→project_id, OS_REGION_NAME→region, OS_USER_DOMAIN_NAME→user_domain_name.

Если у вас остался старый prod.auto.tfvars с версии до этого изменения — переименуйте его в prod.secrets.tfvars (значения не меняются), он больше не подхватывается автоматически.

В самом terraform.tfvars дополнительно отредактируйте:

ssh_key_name = "<имя загруженного SSH-ключа>"

private_network_cidrs = [
  "10.90.0.0/28",
  "10.90.0.16/28",
]

private_network_cidrs (по умолчанию []) — один CIDR-префикс на каждую project-managed приватную сеть (Terraform сам создаёт сеть/подсеть, адрес назначает Neutron IPAM): один префикс = одна общая сеть = один приватный интерфейс на роутер. Автоматической нарезки нет — префиксы не должны пересекаться. Берите /28, а не /29: VKCS сам создаёт служебные порты на каждой сети (замечен network:dns), которые тоже расходуют адреса из пула — /29 (5 адресов) на практике оказался слишком тесным.

Если вместо (или в дополнение к) private_network_cidrs нужны приватные интерфейсы в уже существующих сетях (созданных заранее, в том числе в другом VK Cloud проекте, с фиксированным IP на каждый роутер) — используйте router_networks (по умолчанию {}), пример реального использования — окружение mvm-s3, см. terraform/mvm-s3.tfvars и шаг 4а ниже.

UUID системной Security Group default (уникален для каждого проекта VK Cloud) вычисляется автоматически через data.vkcs_networking_secgroup, вручную задавать не нужно. Переменная default_security_group_id — override только на крайний случай (нестандартное имя/SDN группы в проекте), не для обычного использования.

3. (Опционально) масштабирование

Число роутеров и приватных сетей меняется правкой router_count/private_network_cidrs прямо в terraform.tfvars (сейчас там уже реальные значения этого PROD-деплоя — 3 роутера). Значение из terraform.tfvars всегда перекрывает TF_VAR_* (у tfvars-файла более высокий приоритет), так что TF_VAR_router_count сработает, только если убрать router_count из terraform.tfvars. Разовый override без правки файла — через -var в командной строке (он перекрывает даже tfvars):

terraform apply -var-file=terraform.tfvars -var-file=prod.secrets.tfvars \
  -var="router_count=4" -var='private_network_cidrs=["10.90.0.0/28","10.90.0.16/28","10.90.0.32/28"]'

4. Развернуть (PROD)

cd terraform
terraform init
terraform workspace select default   # state PROD-окружения
terraform plan  -var-file=terraform.tfvars -var-file=prod.secrets.tfvars
terraform apply -var-file=terraform.tfvars -var-file=prod.secrets.tfvars

Каждая ВМ сама донастроит сеть при первой загрузке (network-init.sh.tpl) и перезагрузится.

4а. Развернуть окружение mvm-s3 (внешние сети с фиксированными IP)

mvm-s3 — отдельный VK Cloud проект с собственным Terraform state (workspace), где обе приватные сети роутеров уже созданы администратором заранее (см. docs/changes/2026-09-09-mvm-s3-external-networks-*.md) — Terraform их не создаёт, только подключает роутеры к ним по UUID с заранее известным IP на каждый роутер (terraform/mvm-s3.tfvars).

1. Скопируйте terraform/mvm-s3.secrets.tfvars.example в terraform/mvm-s3.secrets.tfvars и впишите реальные credentials проекта mvm-s3, а также реальное ssh_key_name в terraform/mvm-s3.tfvars (сейчас там плейсхолдер).
2. Разверните в отдельном workspace, чтобы не задеть state PROD:

   cd terraform
   terraform workspace new mvm-s3   # один раз; в дальнейшем - terraform workspace select mvm-s3
   terraform plan  -var-file=terraform.tfvars -var-file=mvm-s3.tfvars -var-file=mvm-s3.secrets.tfvars
   terraform apply -var-file=terraform.tfvars -var-file=mvm-s3.tfvars -var-file=mvm-s3.secrets.tfvars
   

3. Ожидаемый результат: 4 роутера, без project-managed приватных сетей (private_network_cidrs = []), с 2 фиксированными IP-адресами каждый (primary/backup) из router_networks.

Чтобы вернуться к работе с PROD: terraform workspace select default + прежние -var-file (см. шаг 4) — стейты не пересекаются.

5. Настроить Ansible

⚠️ Важно: ansible/inventory.ini и роли (base/frr_router/keepalived) пока жёстко рассчитаны на 2 роутера с интерфейсами eth0/eth1 (VRRP-схема) — под новую N-роутерную/N-NIC архитектуру ещё не адаптированы. Для дефолтных значений (router_count=2, 2 записи в private_network_cidrs) впишите реальные wan_ip/lan_ip/GRE/BGP-параметры роутеров в inventory.ini вручную. При масштабировании выше 2 роутеров или интерфейсов Ansible-слой нужно дорабатывать отдельно.

cd ansible
ansible-playbook -i inventory.ini site.yml

6. Проверить

• SSH на публичные IP роутеров, cat /var/log/network-config.log — лог настройки интерфейсов.
• ip a, networkctl — убедиться, что eth0 (WAN) и eth1..ethN (приватные) подняты корректно.
• FRR/strongSwan/keepalived статусы — см. раздел "Under the Hood" в README.md.

Локальная офлайн-проверка поставки (без облака)

terraform/tests/setup-local-terraform.sh
venv/bin/pytest terraform/tests -v