Add router_networks: fixed-IP router interfaces into external networks (mvm-s3)

mvm-s3 is a separate VK Cloud project whose admin pre-created two private
networks/subnets with a known IP per router. Unify project-managed
(private_network_cidrs, IPAM-assigned) and externally-owned (router_networks,
fixed-IP) private interfaces into one local.router_interfaces so both share
the existing port/dynamic-network mechanism instead of duplicating it.

Switch from implicit *.auto.tfvars loading to explicit -var-file per
environment (now two share this terraform/ directory) plus a dedicated
Terraform workspace for mvm-s3, so PROD's state and credentials are never
touched by mvm-s3 applies.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GHfG9FgpMrGdrvC1QUewTw

docs/QUICKSTART.md

@@ -10,7 +10,9 @@
 
 ## 2. Клонировать репозиторий и задать credentials
 
-`terraform/terraform.tfvars` — это закоммиченный обезличенный шаблон, реальные credentials в него вписывать **не нужно**. Вместо этого скопируйте `terraform/prod.auto.tfvars.example` в `terraform/prod.auto.tfvars` (этот файл в `.gitignore`, никогда не попадёт в git) и впишите туда реальные значения:
+Начиная с появления второго окружения (`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/"
@@ -21,7 +23,9 @@ region           = "RegionOne"
 user_domain_name = "users"   # или "service-users" для сервисного аккаунта svc-*
 ```
 
-Terraform подхватывает `*.auto.tfvars` автоматически, в дополнение к `terraform.tfvars` — ничего больше настраивать не нужно. Если у вас есть `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`.
+Если у вас есть `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` дополнительно отредактируйте:
 
@@ -34,7 +38,9 @@ private_network_cidrs = [
 ]
 ```
 
-`private_network_cidrs` — обязательная переменная без значения по умолчанию: один CIDR-префикс на каждую приватную сеть, к которой будут подключены интерфейсы роутеров (один префикс = одна общая сеть = один приватный интерфейс на роутер). Автоматической нарезки нет — префиксы не должны пересекаться. Берите `/28`, а не `/29`: VKCS сам создаёт служебные порты на каждой сети (замечен `network:dns`), которые тоже расходуют адреса из пула — `/29` (5 адресов) на практике оказался слишком тесным.
+`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 группы в проекте), не для обычного использования.
 
@@ -43,20 +49,38 @@ UUID системной Security Group `default` (уникален для каж
 Число роутеров и приватных сетей меняется правкой `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):
 
 ```bash
-terraform apply -var="router_count=4" -var='private_network_cidrs=["10.90.0.0/28","10.90.0.16/28","10.90.0.32/28"]'
+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. Развернуть
+## 4. Развернуть (PROD)
 
 ```bash
 cd terraform
 terraform init
-terraform plan
-terraform apply
+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:
+   ```bash
+   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-слой нужно дорабатывать отдельно.