# Сводка по разработке Terraform-провайдера Nubes Дата: 2026-01-22 --- ## Краткое описание проекта ✅ Разрабатываем Terraform-провайдер для облака Nubes (рабочее локальное имя `mycloud`). Цель — дать клиентам возможность управлять сервисами облака (инстансы, S3, Kubernetes и др.) через Terraform с использованием современного Terraform Plugin Framework. --- ## Что уже реализовано (фактически) ✅ - Провайдер на Go, структура проекта и `main.go` (providerserver.Serve). - Минимальный ресурс `mycloud_dummy_instance` со схемой: `display_name`, `description`, `id`, `status`. - Реализованы методы Create, Read, Update, Delete для dummy ресурса. - Провайдер успешно создаёт экземпляр (POST /instances) и создаёт операцию (POST /instanceOperations). - При создании операции реализована логика отправки параметров операций (POST /instanceOperationCfsParams) для триггера — добавлена функция submitOperationParams. - Проведено тестирование: создание, обновление, удаление ресурсов — рабочие сценарии (хотя операции часто требуют ручного запуска в UI). --- ## Важные технические находки 🔎 - API Nubes использует двухшаговый паттерн: POST `/instances` → POST `/instanceOperations` → (нужен шаг запуска/submit). - UI показывает, что операция не всегда стартует автоматически; набор параметров (`instanceOperationCfsParams`) должен корректно заполниться. Некоторые параметры (например `mapExample`) требуют валидных значений — иначе 400 и операция не стартует. - Для запуска операции вручную нажимается кнопка "Выполнить" в UI; Network tab показал последовательность POST/PUT к `instanceOperationCfsParams` и затем GET к `instanceOperations/{uid}` (статус `dtSubmit` остаётся null, если операция не стартовала). --- ## Аутентификация: текущее состояние и план 🔐 - Сейчас: временный workaround — использовать JWT из браузера вручную через `export MYCLOUD_API_TOKEN=""` — удобно для разработки, но не для CI/продакшна. - Рекомендуемый рабочий путь: **Keycloak client_credentials** (OAuth2) или Service Account с long-lived key. - План: реализовать в провайдере поддержку client_credentials + автоматический refresh токена, а также чтение credentials из: - provider HCL parameters - переменных окружения - файла `~/.config/mycloud/credentials` (профили) - CLI login (опционально) — `nubes-cli login` (authorization code + refresh_token сохранение) --- ## Что добавить в провайдер (текущие задачи) 🛠️ 1. Поддержка OAuth2 client_credentials + автообновление токена. (высокий приоритет) 2. Улучшить Create/Update/Delete: после создания операции обеспечить корректную последовательность установки параметров и проверку запуска; увеличить retry/timeout. 3. Добавить ресурсы: `mycloud_vm_instance` (VM) и `mycloud_s3_bucket` (S3) — MVP набор. 4. Добавить sensitive поле `admin_config_b64` для Kubernetes-кластеров и показать пример с `local_file` для автоматической записи kubeconfig (с предупреждениями по state security). --- ## Registry & Deployment (публикация провайдера) 📦 - Подход: хранить релизы провайдера как S3 объекты: - Структура: `/providers/mycloud/mycloud///...` - Артефакты: бинарники, `SHA256SUMS`, `index.json`, GPG подписи - Быстрый PoC: S3 + self-hosted GitHub Actions runner в k8s (actions-runner-controller). - Продакшн: S3 + оператор для управления сборками. --- ## Operator для автоматизированной публикации (идея) 🤖 - CRD `ProviderBuild` (или `TerraformProviderRelease`) — контроллер запускает Job на событие (git tag / создание CR): - запускает build job (cross‑build) - прогоняет тесты - генерирует SHA/GPG - загружает артефакты в S3 - обновляет статус CR (urls, checksums, logs) --- ## CI / Runner — рекомендации ⚙️ - Для контейнерной сборки можно использовать GitHub Actions (hosted) для PoC. - Для контроля и приватности рекомендовано ставить self-hosted runner в Nubes (VM или k8s). actions-runner-controller — удобный вариант. - Секреты (S3 creds, GPG keys, Keycloak client_secret) хранить в Vault/Kubernetes Secrets. --- ## UX: kubeconfig и автоматизация для пользователей 🧑‍💻 - Варианты: 1) кнопка «Download kubeconfig» на UI (простой FE таск), 2) `nubes-cli get-kubeconfig`, 3) провайдер возвращает `admin_config_b64` (sensitive) и пример `local_file` в документации. - Рекомендация: поддержать все 3 варианта (FE кнопка — удобство; CLI — power users; Terraform — infra-as-code flow), но сначала реализовать провайдер+CLI minimal. --- ## Оценки по времени (ориентировочно) - OAuth2 client_credentials + token refresh: 8–16ч - VM resource + S3 resource: 24–40ч - CLI `nubes-cli` (minimal login + get-kubeconfig): 8–16ч - S3 PoC + runner setup + publish script: 8–16ч - Operator skeleton (CRD + basic controller): 3–5 дн --- ## Приоритеты и план работ (короткая дорожная карта) 🗺️ 1. (1–3 дня) Stabilize provider: fix autostart of operations, add token quick-improvements. 2. (3–7 дней) Add VM + S3 resources, tests, examples. 3. (1–2 дня) PoC: S3 + runner + publish script. 4. (3–7 дней) Operator skeleton для автоматических билдов и публикации (K8s CRD). --- ## Текущие блокеры / вопросы для DevOps - Хотим ли мы сразу выдавать service client (client_id/secret) в Keycloak для CI? (рекомендуется для production later) - Хотим ли развернуть S3‑подход в тестовом кластере? (рекомендуется для HA) --- ## Команды и полезные ссылки (для демонстрации) - Примеры запросов для проверки токена: ```bash curl -s -X POST "https://keycloak.nubes.ru/realms/cloud/protocol/openid-connect/token" \ -d 'grant_type=client_credentials' \ -d 'client_id=YOUR_ID' \ -d 'client_secret=YOUR_SECRET' ``` - Проверка API: ```bash # ⛔ LEGACY: в примере ниже deck-api заменён на Gateway. curl -H "Authorization: Bearer $TOKEN" https://lk-api-gateway.ngcloud.ru/api/v1/svc/instances ``` --- ## Файлы проекта (важные местоположения) - `internal/provider/provider.go` — конфигурация провайдера - `internal/provider/dummy_resource.go` — dummy resource (создание, операции, submitOperationParams) - `test/main.tf` и `examples/main.tf` — пример использования - `docs/discovery/development-journey.md` — подробная история разработки (есть) - `docs/for_nomo_chat.md` — этот файл --- Если нужно, могу экспортировать эту сводку в PDF или другой формат и подготовить короткую презентацию для начальника. Хочешь, добавлю ещё краткий `README` с шагами для запуска PoC (S3 + self-hosted runner + build workflow)? *Файл сохранён по пути*: `docs/for_nomo_chat.md` --- Автор: GitHub Copilot (Raptor mini (Preview)) ## Новые находки по API (22.01.2026) 🔎 ⚠️ **Найден недостающий метод "Execute"!** В документации обнаружен эндпоинт, который выполняет ту самую роль кнопки "Выполнить": - `POST /instanceOperations/{instanceOperationUid}/run` - Описание: "Запуск выполнения операции". **План исправлений в провайдере:** 1. После `submitOperationParams` (заполнения параметров) нужно вызвать `validate-cfs` (опционально, для проверки). 2. Вызвать `POST /instanceOperations/{uid}/run`. 3. Только после этого поллить статус операции.