add: documentation
This commit is contained in:
“Naeel”
@@ -0,0 +1,146 @@
|
||||
# Сводка по разработке 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)
|
||||
|
||||
---
|
||||
|
||||
## Команды и полезные ссылки (для демонстрации)
|
||||
- Примеры запросов для проверки токена:
|
||||
```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
|
||||
curl -H "Authorization: Bearer $TOKEN" https://deck-api.ngcloud.ru/api/v1/index.cfm/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
Block a user