terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
260766e0b24e8858adae8cad1a7f34cfa0a33663
tf_provider/docs/00_overview/for_nomo_chat.md
T

10 KiB
Raw Blame History

Сводка по разработке 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="<JWT>" — удобно для разработки, но не для 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/<version>/<platform>/...
    • Артефакты: бинарники, 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)

Команды и полезные ссылки (для демонстрации)

  • Примеры запросов для проверки токена:
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:
# ⛔ 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. Только после этого поллить статус операции.
Reference in New Issue View Git Blame Copy Permalink