docs: document AI terraform plan analysis (internal/ai + cmd/sless-plan + provider schema)
This commit is contained in:
Naeel
@@ -646,3 +646,66 @@ for _, k := range keys { envVars = append(envVars, corev1.EnvVar{Name: k, Value:
|
||||
|
||||
**Тесты:** 2 теста в `controllers/function_controller_unit_test.go`
|
||||
(4 env vars → алфавитный порядок после SLESS_ENTRYPOINT; пустой Env → только SLESS_ENTRYPOINT).
|
||||
|
||||
---
|
||||
|
||||
## 2026-03-12 — AI-анализ terraform plan через Google Gemini
|
||||
|
||||
**Решение:** Добавлен необязательный AI-анализ вывода `terraform plan` с уровнями детализации 0–5.
|
||||
АI невидим по умолчанию — не влияет на существующие `.tf` файлы и workflow.
|
||||
|
||||
**Причина:**
|
||||
- Разработчики хотят понимать что именно изменится в инфраструктуре перед применением.
|
||||
- Уровни позволяют самостоятельно выбирать глубину анализа (от краткого обзора до полного аудита).
|
||||
- Не ломает backward compatibility: `ai_hint_level` не указан → поведение идентично прежнему.
|
||||
|
||||
**Архитектура:**
|
||||
```
|
||||
provider "sless" { ai_hint_level = 3 }
|
||||
↓ os.Setenv("AI_HINT_LEVEL", "3") (в provider.Configure)
|
||||
sless-plan ← CLI обёртка над terraform plan
|
||||
↓ запускает terraform plan, захватывает вывод
|
||||
↓ если AI_HINT_LEVEL > 0 → internal/ai/analyzer.go
|
||||
↓ POST к Gemini REST API (net/http)
|
||||
↓ выводит анализ пользователю
|
||||
```
|
||||
|
||||
**Новые файлы:**
|
||||
| Файл | Назначение |
|
||||
|------|------------|
|
||||
| `internal/ai/provider.go` | `LLMProvider` interface + `Config` struct + `NewProvider` фабрика |
|
||||
| `internal/ai/google_gemini.go` | Gemini 2.0 Flash через `net/http` (без внешних зависимостей) |
|
||||
| `internal/ai/prompts.go` | Системные промпты для уровней 1–5, `BuildPrompt(level, plan)`, `LevelName(level)` |
|
||||
| `internal/ai/analyzer.go` | Оркестратор: `NewAnalyzer`, `Analyze`, `FormatResult`, `truncatePlan(8000)` |
|
||||
| `internal/ai/cloud_llm.go` | Заглушка: миграционный путь на облачный LLM в будущем |
|
||||
| `cmd/sless-plan/main.go` | CLI: запускает `terraform plan`, читает уровень, вызывает AI |
|
||||
|
||||
**Изменённые файлы:**
|
||||
- `terraform/provider/internal/provider/provider.go` — добавлен атрибут `ai_hint_level` (Optional Int64)
|
||||
|
||||
**Уровни анализа (env: `AI_HINT_LEVEL`):**
|
||||
| Уровень | Описание |
|
||||
|---------|----------|
|
||||
| 0 | Выключен (default) — AI не вызывается |
|
||||
| 1 | Только синтаксические ошибки и опечатки |
|
||||
| 2 | Базовый обзор изменений |
|
||||
| 3 | Умеренный: потенциальные проблемы + рекомендации |
|
||||
| 4 | Детальный: security review + best practices |
|
||||
| 5 | Полный аудит: всё включая compliance |
|
||||
|
||||
**Как передаётся уровень (приоритет по убыванию):**
|
||||
1. `--ai-level` флаг CLI
|
||||
2. `AI_HINT_LEVEL` env var (выставляется провайдером через `os.Setenv` в `Configure`)
|
||||
3. `TF_VAR_ai_hint_level` env var
|
||||
4. Дефолт: 0
|
||||
|
||||
**Почему `net/http` без Google SDK:**
|
||||
Gemini SDK требует внешней зависимости → `go.mod` провайдера должен оставаться неизменным.
|
||||
REST API Gemini достаточен: один endpoint, один JSON запрос/ответ.
|
||||
|
||||
**Backward compatibility:**
|
||||
- Провайдер без `ai_hint_level` → `config.AIHintLevel.IsNull() == true` → `os.Setenv` не вызывается.
|
||||
- `sless-plan` без `AI_HINT_LEVEL` → уровень 0 → AI не вызывается → вывод идентичен `terraform plan`.
|
||||
- Существующие `.tf` файлы изменять не нужно.
|
||||
|
||||
**Коммиты:** `d5ce8c2` (internal/ai + cmd/sless-plan), `582b589` (provider schema)
|
||||
|
||||
@@ -230,6 +230,37 @@
|
||||
| 6 | `replicas` field в FunctionSpec | Низкий (v1.1) |
|
||||
| 7 | RabbitMQ event triggers | Низкий (v2) |
|
||||
| 8 | Метрики → Victoria Metrics | Низкий |
|
||||
| 9 | `sless-plan` реально не запускает `terraform plan` — нужна интеграция в workflow (docs) | Средний |
|
||||
|
||||
---
|
||||
|
||||
## 2026-03-12 — AI-анализ terraform plan (ветка feat/ai-terraform-analysis)
|
||||
|
||||
| # | Компонент | Статус | Заметки |
|
||||
|---|-----------|--------|----------|
|
||||
| 1 | `internal/ai/provider.go` | ✅ | `LLMProvider` interface + `Config` struct + `NewProvider` фабрика |
|
||||
| 2 | `internal/ai/google_gemini.go` | ✅ | Gemini REST API через `net/http` (без внешних SDK) |
|
||||
| 3 | `internal/ai/prompts.go` | ✅ | Системные промпты уровней 1–5, `BuildPrompt`, `LevelName` |
|
||||
| 4 | `internal/ai/analyzer.go` | ✅ | Оркестратор: `NewAnalyzer`, `Analyze`, `FormatResult`, `truncatePlan(8000)` |
|
||||
| 5 | `internal/ai/cloud_llm.go` | ✅ | Заглушка для будущего облачного LLM |
|
||||
| 6 | `cmd/sless-plan/main.go` | ✅ | CLI обёртка над `terraform plan` + AI анализ после |
|
||||
| 7 | `terraform/provider/internal/provider/provider.go` | ✅ | `ai_hint_level` атрибут (опциональный Int64, default=0) в Schema и Configure |
|
||||
| 8 | `go build ./internal/ai/... && go build ./cmd/sless-plan/...` | ✅ | BUILD OK на VM |
|
||||
| 9 | `go build ./...` в terraform/provider/ | ✅ | BUILD OK на VM |
|
||||
| 10 | Коммит + пуш | ✅ | `d5ce8c2` (ai pkg + cmd) → `582b589` (provider) |
|
||||
|
||||
**Ветка:** `feat/ai-terraform-analysis`
|
||||
**Последний коммит:** `582b589`
|
||||
|
||||
**Как использовать:**
|
||||
```hcl
|
||||
provider "sless" {
|
||||
endpoint = "https://sless-api.kube5s.ru"
|
||||
token = var.token
|
||||
ai_hint_level = 3 # 0=off (default), 1–5 = уровень анализа
|
||||
}
|
||||
```
|
||||
Затем вместо `terraform plan` использовать `sless-plan` — предоставит анализ от Gemini.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user