tf_provider/docs/20_discovery/ai-integration-vision.md

Infrastructure Resources & AI Integration Vision

Date: 24 January 2026
Status: VDC/Edge/vApp resources implementation & AI architecture design

Current State

Resources Implemented

• ✅ VDC (Virtual Data Center) - service ID 21
• ✅ Edge Gateway - service ID 22
• ✅ vApp (Virtual Application) - service ID 26
• ✅ VM Instance - service ID 28

API Patterns Discovered

Creation Flow

1. POST /instances → {serviceId, displayName, descr} → 201 + Location: //{instanceId}
2. POST /instanceOperations → {instanceUid, operation: "create"} → 201 + Location: //{operationId}
3. GET /instanceOperations/{operationId}?fields=cfsParams → список параметров
4. POST /instanceOperationCfsParams → для каждого параметра отправить значение
5. POST /instanceOperations/{operationId}/run → запустить операцию → 201
6. POLLING: GET /instanceOperations/{operationId} → проверять operationIsInProgress: false
7. POLLING: GET /instances/{instanceId} → проверять explainedStatus: "running"

Critical Bug Fixed

Problem: Provider timeout после 10 минут, хотя VDC создаётся за ~45 секунд.

Root Cause:

1. JSON field был status вместо explainedStatus
2. Polling проверял только instance, пропуская завершение operation

Solution:

// Исправленная структура
type InstanceResponse struct {
    Status string `json:"explainedStatus"` // было: json:"status"
}

// Двухэтапный polling
1. Ждать operationIsInProgress: false (операция завершена)
2. Проверять explainedStatus: "running" (instance запущен)

Actual Creation Times (from API data)

• VDC: ~43-46 секунд
• Edge Gateway: ~5-10 минут (требует проверки)
• vApp: ~3-5 минут (требует проверки)
• VM: ~5-10 минут

VDC Lifecycle Quirk

Delete operation не удаляет VDC, а переводит в suspend:

operationReq := CreateOperationRequest{
    Operation: "suspend", // не "delete"!
}

Полное удаление: suspend → ждать 14 дней → удалить вручную через UI.

---

Data Sources for Existing Infrastructure

Problem Statement

Создание VDC+Edge+vApp занимает ~30-40 минут. Если инфраструктура уже существует, не нужно ждать.

Solution: Data Sources

# Поиск существующих ресурсов по имени
data "nubes_vdc" "existing" {
  display_name = "production-vdc"
}

data "nubes_edge" "existing" {
  display_name = "production-edge"
}

data "nubes_vapp" "existing" {
  display_name = "production-vapp"
}

# Создание только VM в существующей инфраструктуре (~5-10 мин вместо ~40)
# resource "nubes_vm_instance" "web" {
  vapp_uid = data.nubes_vapp.existing.id
  # ...
}

Flexible Deployment Pattern

Один конфиг - выбор через переменные:

variable "create_vdc" { type = bool }
variable "create_edge" { type = bool }
variable "create_vapp" { type = bool }

# Условное создание
resource "nubes_vdc" "new" {
  count = var.create_vdc ? 1 : 0
  # ...
}

# Условный поиск
data "nubes_vdc" "existing" {
  count = var.create_vdc ? 0 : 1
  display_name = var.existing_vdc_name
}

# Выбор ID
locals {
  vdc_id = var.create_vdc ? nubes_vdc.new[0].id : data.nubes_vdc.existing[0].id
}

Use Cases:

• create_vdc=true, create_edge=true, create_vapp=true → всё с нуля (~30-40 мин)
• create_vdc=false, create_edge=false, create_vapp=false → всё существует (~5-10 мин)
• create_vdc=false, create_edge=true, create_vapp=true → VDC корпоративный, свой Edge+vApp (~15-20 мин)

---

AI Integration Vision

Philosophy

"Домохозяйка-friendly" облако - любой человек без технических знаний может создать инфраструктуру описав что ему нужно обычным языком.

Architecture Concept

1. Композитный AI-ресурс nubes_application_stack

Input - естественный язык:

# resource "nubes_application_stack" "myapp" {
  ai_description = <<-EOT
    Создай простой сайт с базой данных
  EOT
  
  vdc_uid  = data.nubes_vdc.existing.id
  edge_uid = data.nubes_edge.existing.id
}

AI парсит через Gemini:

{
  "components": [
    {"type": "vm", "role": "web", "cpu": 2, "ram": 4, "image": "nginx"},
    {"type": "postgres", "version": "14", "storage": 50}
  ],
  "network": "shared"
}

Provider создаёт:

1. vApp (контейнер)
2. VM для nginx (с cloud-init)
3. VM для PostgreSQL (с cloud-init + конфиг)
4. Настраивает сеть между ними

Output:

Apply complete!

Outputs:
  web_vm_ip = "10.0.1.5"
  postgres_connection_string = "postgresql://10.0.1.6:5432/myapp"

2. Инкрементальные обновления через естественный язык

Концепция: История изменений как git changelog

# resource "nubes_application_stack" "myapp" {
  ai_description = <<-EOT
    # День 1 (23.01.2026)
    Создай простой сайт с базой данных
    
    # День 7 (30.01.2026)
    + добавь Redis для кеша
    
    # День 14 (06.02.2026)
    + добавь балансировщик на 2 фронтенда
    
    # День 20 (12.02.2026)
    - убери Redis, не пригодился
  EOT
}

AI видит:

• Базовая конфигурация (первая запись)
• + = добавить компонент
• - = удалить компонент
• Обычный текст = модификация

Provider применяет только delta:

• Не трогает существующие VM
• Создаёт новые компоненты
• Удаляет ненужные

Преимущества:

• Видна эволюция инфраструктуры
• Audit trail встроен
• Rollback = удалить последние строки
• Понятно что и когда менялось

3. AI-powered проверка квот и рекомендации

При terraform plan:

func (r *ApplicationStackResource) ModifyPlan(ctx, req, resp) {
    // Парсим AI описание
    aiParams := parseWithGemini(plan.AiDescription.ValueString())
    
    // Получаем квоты VDC
    vdcQuotas := getVDCQuotas(plan.VdcUid)
    usedResources := calculateUsedResources(plan.VdcUid)
    available := vdcQuotas - usedResources
    
    // Сравниваем с запросом AI
    if aiParams.TotalRAM > available.RAM {
        resp.Diagnostics.AddWarning(
            "Недостаточно ресурсов",
            fmt.Sprintf(`
AI запрашивает: %d GB RAM
Доступно в VDC: %d GB
Используется: %d GB

Рекомендации:
- Уменьшите количество VM
- Или увеличьте квоту VDC
- Или используйте другой VDC
`, aiParams.TotalRAM, available.RAM, usedResources.RAM))
    }
    
    // Обратная ситуация - избыточность
    if aiParams.TotalRAM < available.RAM * 0.1 {
        resp.Diagnostics.AddWarning(
            "Избыточная конфигурация",
            fmt.Sprintf(`
AI запрашивает: %d GB RAM для "%s"
Доступно: %d GB RAM в VDC

Можете смело увеличить ресурсы для лучшей производительности.
`, aiParams.TotalRAM, aiParams.Purpose, available.RAM))
    }
}

Вывод при terraform plan:

╷
│ Warning: Недостаточно ресурсов
│ 
│ AI запрашивает: 40 GB RAM
│ Доступно в VDC: 20 GB (квота) - 12 GB (используется) = 8 GB свободно
│ 
│ Рекомендации:
│ - Уменьшите количество VM до 1-2
│ - Или увеличьте квоту VDC
╵

4. Gemini API Integration

Technology Stack:

• Google Gemini API (есть аккаунт)
• HTTP JSON API
• Structured output parsing

Промпт пример:

Parse this infrastructure request into JSON:
"Создай простой сайт с базой данных + добавь Redis для кеша"

Return format:
{
  "components": [
    {"type": "vm", "role": "frontend", "cpu": 2, "ram": 4, "image": "nginx"},
    {"type": "postgres", "version": "14", "storage": 50},
    {"type": "redis", "ram": 2}
  ],
  "network": "shared",
  "purpose": "simple website with database and cache"
}

Provider код:

func parseWithGemini(description string, apiKey string) (*StackSpec, error) {
    reqBody := map[string]interface{}{
        "contents": []map[string]interface{}{
            {"parts": []map[string]string{{"text": buildPrompt(description)}}},
        },
    }
    
    resp, err := http.Post(
        "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key="+apiKey,
        "application/json",
        jsonBody(reqBody),
    )
    
    // Parse JSON response
    var result StackSpec
    json.Unmarshal(resp.Body, &result)
    return &result, nil
}

5. Advanced: Schedule & Lifecycle через AI

User input:

# resource "nubes_application_stack" "test_env" {
  ai_description = "Создай тестовое окружение, запусти через 2 дня на 8 часов"
}

AI парсит:

{
  "schedule": {
    "startAt": "2026-01-26T10:00:00Z",
    "duration": "8h",
    "autoDelete": true
  },
  "components": [...]
}

Provider behavior:

• Записывает метаданные в state
• Выдаёт Warning о необходимости внешнего оркестратора
• Или интегрируется с Kubernetes Operator для cron jobs

Full automation (с Operator):

Terraform Provider (создание ресурсов)
    ↓
Kubernetes Operator (расписание)
    ↓
CronJob (проверка времени)
    ↓
Terraform (автоматический destroy)

---

Unique Value Proposition

Что никто не делает

❌ Pulumi AI - генерит код, не управляет напрямую
❌ Google Duet - автодополнение, не композитные ресурсы
❌ AWS Copilot - фиксированные шаблоны, не AI парсинг

✅ Наше решение:

1. AI парсинг → композитный ресурс → проверка квот → рекомендации в одном флоу
2. История изменений через естественный язык как git changelog
3. Инкрементальные обновления - AI понимает delta, Provider применяет только изменения
4. "Домохозяйка-friendly" - нулевой порог входа

Example User Journey

Обычный пользователь без IT знаний:

1. Пишет в Terraform:

# resource "nubes_application_stack" "myshop" {
  ai_description = "Мне нужен интернет-магазин с корзиной и оплатой картой"
}

2. terraform plan показывает:

AI создаст:
- 2 VM для фронтенда (nginx) - 2 CPU, 4 GB RAM каждая
- 1 VM для бэкенда (Node.js) - 4 CPU, 8 GB RAM
- 1 PostgreSQL для данных - 50 GB storage
- 1 Redis для сессий - 2 GB RAM

Итого: 10 CPU, 18 GB RAM, 50 GB storage
Доступно в VDC: 20 CPU, 40 GB RAM, 200 GB storage ✅

3. terraform apply → через 20 минут готовый интернет-магазин

4. Через неделю добавляет:

ai_description = <<-EOT
  Мне нужен интернет-магазин с корзиной и оплатой картой
  + добавь систему рекомендаций товаров
EOT

5. AI понимает delta, создаёт только ML-сервис, не трогая существующее

---

Implementation Roadmap

Phase 1: Infrastructure Resources (Current)

• VDC, Edge, vApp, VM resources
• Data sources для существующих ресурсов
• Правильный polling (operation → instance)
• Тестирование Edge/vApp создания
• Update/Delete операции для всех ресурсов

Phase 2: AI Integration MVP

• Gemini API клиент в Provider
• Простой AI-парсинг для VM ресурса
• Warning'и с рекомендациями при plan
• Проверка квот VDC

Phase 3: Композитный ресурс

• nubes_application_stack ресурс
• AI парсинг complex descriptions
• Автоматическое создание vApp + multiple VMs
• Cloud-init генерация для разных компонентов

Phase 4: Advanced Features

• История изменений (git-like changelog)
• Инкрементальные обновления (delta detection)
• Интеграция с Kubernetes Operator для scheduling
• Terraform module генератор

---

Technical Notes

API Quirks

1. explainedStatus не status для instance state
2. operationIsInProgress для отслеживания операций
3. VDC delete = suspend (14 дней до полного удаления)
4. POST /run возвращает 201 мгновенно, реальная работа начинается после

Performance

• VDC: 45 сек
• Edge: 5-10 мин (TBD)
• vApp: 3-5 мин (TBD)
• VM: 5-10 мин
• Full stack: ~30-40 мин

Token Management

• JWT from Keycloak
• 2-hour expiry
• Stored in ~/.nubes_token
• Format: raw JWT (без "Bearer" prefix)
• Требует trim whitespace

---

Questions for Product Team

1. AI API Key: где хранить? Provider config? Environment variable? Terraform Cloud?
2. Scheduling: нужен ли Kubernetes Operator или достаточно метаданных в state?
3. Billing: как считать стоимость AI-созданных ресурсов для показа пользователю?
4. Templates: создавать ли библиотеку готовых AI-промптов? ("WordPress site", "Django app", etc.)
5. Validation: нужна ли human-approval после AI парсинга перед apply?