120 lines
9.6 KiB
Markdown
120 lines
9.6 KiB
Markdown
# Terraform Provider Development Strategy & AI Integration
|
||
|
||
## 1. Vision: "The Helpful Kitchen Assistant"
|
||
The provider should not just be a silent executor of commands. It should act as an intelligent assistant for users of all skill levels (the "Cook" persona). It must provide context, warnings, and advice *before* any potentially destructive or wasteful actions are taken.
|
||
|
||
## 2. Advanced Pre-Apply Logic
|
||
To prevent "bad applies" and incomplete infrastructure states, the provider will implement:
|
||
|
||
### A. Context-Aware Validation (Scanning the Cloud)
|
||
- **Data Sources as Sensors:** Use Data Sources not just for referencing existing resources, but as "sensors" to understand the current cloud state during `terraform plan`.
|
||
- **Pre-emptive Warnings:** Compare the proposed `plan` against current cloud limits, existing resource names, and regional availability.
|
||
- **Example:** Trigger a warning if a user is creating a 6th bucket while 5 existing ones are empty.
|
||
|
||
### B. Cascading & Logical Validation (Deep Validation)
|
||
- **Attribute Inter-dependency:** Check compatibility between linked resources (e.g., App vs DB versions, S3 permissions vs CDN requirements).
|
||
- **Early Termination:** If Resource A in a chain is logically "broken" or suboptimal, the provider should error out or warn on the entire chain before `apply` begins.
|
||
|
||
## 3. Human-Centric Output & AI Insights
|
||
- **Standardized Info:** `terraform plan` should output human-readable summaries of what's already in the cloud, not just what's being changed.
|
||
- **AI-Driven Advice:**
|
||
- The provider outputs a structured JSON state.
|
||
- An AI Agent (Sub-chef) analyzes this JSON.
|
||
- Result: "Hey, I noticed you're creating a DB in Region A but your VMs are in Region B. This will cause latency. Want to fix it?"
|
||
|
||
## 4. Implementation via Taffy API Specifics
|
||
- **Lifecycle Utilization:** Leverage the 3-step Taffy lifecycle (`Operation -> Parameters -> Run`).
|
||
- **Validation Step:** Use the `/validate-cfs` API endpoint during the Terraform `Plan` or `Create` phase (before the final `Run`) to ensure the cloud accepts the parameters without actually committing the change.
|
||
|
||
## 5. Reliability & Uncertainty Tracking
|
||
- All documentation and internal agent logic should use **Confidence Scores** (e.g., `[CONFIDENCE: 85%]`).
|
||
- Explicitly mark `[UNCERTAINTY]` tags for deprecated API features or areas where documentation contradicts observed behavior (from HAR/Traffic analysis).
|
||
|
||
---
|
||
*This document serves as the architectural north star for the project.*
|
||
|
||
## 6. Подресурсы (subresource) и поведение Terraform
|
||
|
||
### Зачем нужен ForceNew
|
||
Для подресурсов вроде `create_user`, `delete_user`, `create_database` часто **нет** операции `modify` в API. Это значит, что при изменении ключевых полей (например, `username` или `dbName`) мы не можем обновить объект на месте — только удалить и создать заново.
|
||
|
||
**ForceNew** — это стандартный механизм Terraform: изменение таких полей приводит к **замене** ресурса (Delete + Create). Это предотвращает ложные обновления, когда Terraform считает, что всё изменилось, а в API реально ничего не выполнено.
|
||
|
||
### Правило для генерации подресурсов
|
||
- Если у подресурса **нет** операции `modify`, то все его параметры считаются **ForceNew**.
|
||
- Если `modify` есть, то **ForceNew** получают параметры, которые участвуют в идентификации/удалении (ключи, по которым ресурс можно уникально определить).
|
||
|
||
### Итоговое поведение
|
||
- Изменение ключевых параметров подресурса => ресурс заменяется.
|
||
- Это соответствует возможностям API и сохраняет корректность состояния Terraform.
|
||
|
||
## 7. Каноничная lifecycle-логика для сервисов с suspend/resume
|
||
|
||
Этот раздел обязателен для всех агентов, генераторов и разработчиков.
|
||
Если в других документах встречаются старые правила (`resume_if_exists`, `delete_mode`), приоритет всегда у этого раздела.
|
||
|
||
Область действия:
|
||
- Только `instance`-ресурсы, у которых API поддерживает `suspend`/`resume`.
|
||
- Для сервисов без `suspend` действует обычная логика create/modify/delete.
|
||
|
||
Флаги:
|
||
- `adopt_existing_on_create` (optional, default: `false`) — разрешает усыновление уже `running` ресурса при create/apply.
|
||
- `suspend_on_destroy` (optional, default: `true`) — при destroy/удалении из манифеста выполнять `suspend` вместо удаления из state.
|
||
|
||
Правила по умолчанию:
|
||
- Никакого неявного adopt/import: без `adopt_existing_on_create=true` найденный `running` ресурс считается конфликтом.
|
||
- На destroy выполняется `suspend` по умолчанию (`suspend_on_destroy=true`).
|
||
- Режим state-only допускается только при явном `suspend_on_destroy=false`.
|
||
|
||
## 8. Обязательные правила apply / plan / destroy / modify
|
||
|
||
### Apply/Create (instance с suspend/resume)
|
||
- Всегда проверить облако по `resource_name` перед create.
|
||
- Если ресурс не найден в облаке или найден только в статусе `deleted` — всегда `create`.
|
||
- Если ресурс в статусе `suspend`:
|
||
- при `adopt_existing_on_create=true` и совпадении основных параметров — `resume` + `adopt`, и явное сообщение в plan/apply;
|
||
- при `adopt_existing_on_create=false` — hard error (явно требовать включить флаг для resume/adopt);
|
||
- при несовпадении — hard error с перечислением несовпавших ключей.
|
||
- Если ресурс в статусе `running`:
|
||
- при `adopt_existing_on_create=true` — adopt (import-поведение) с явным сообщением в plan;
|
||
- при `adopt_existing_on_create=false` — hard error "resource already exists".
|
||
- Если ресурс в статусе `not created` — hard error "проверьте ресурс в личном кабинете" (без auto-adopt/create).
|
||
- Если ресурс в статусе `creating`/`pending`/`failed` — hard error.
|
||
|
||
### Формат диагностик (обязательно)
|
||
- Диагностики должны быть многострочными и читаемыми.
|
||
- В тексте обязательно указывать:
|
||
- итоговое решение (`adopt`/`resume`/`error`),
|
||
- какой флаг повлиял (`adopt_existing_on_create`/`suspend_on_destroy`),
|
||
- детализированные поля (`resource_name`, `service_id`, `instance_uid`, `status`, `status_raw`, `operation_pending`, `operation_in_progress`) отдельными строками.
|
||
- Для конфликта `resource already exists` при `adopt_existing_on_create=false` диагностика обязана явно предлагать оба пути:
|
||
- изменить `resource_name`, если нужен новый ресурс;
|
||
- включить `adopt_existing_on_create=true` и повторить `apply` для импорта/усыновления существующего ресурса.
|
||
|
||
### Destroy / удаление из манифеста (instance с suspend/resume)
|
||
- Если `suspend_on_destroy=true` — выполнить `suspend`.
|
||
- Если `suspend_on_destroy=false` — удалить только из Terraform state, без delete/suspend вызовов в API (осознанный override).
|
||
|
||
### Modify
|
||
- При diff по immutable/create-only параметрам — hard error (replace запрещён).
|
||
- При diff только по mutable параметрам — выполнить `modify`.
|
||
|
||
### Replace
|
||
- Для сервисов с `suspend` запрещён любой implicit replace (`delete+create`).
|
||
- Попытка replace должна завершаться ошибкой на этапе plan.
|
||
|
||
## 9. Контрольный список для реализации
|
||
|
||
### Plan messages (обязательно)
|
||
- Явно указывать обнаруженный cloud status: `deleted`/`suspend`/`running`/`not created`/`creating`.
|
||
- Явно указывать, какой флаг повлиял на решение: `adopt_existing_on_create` или `suspend_on_destroy`.
|
||
- Для веток `resume` и `adopt` показывать причину выбора действия.
|
||
|
||
### Safety guards
|
||
- Для `suspend` + mismatch не допускать auto-resume.
|
||
- Для `running` без `adopt_existing_on_create=true` не допускать auto-adopt.
|
||
- После `resume`/`adopt` выполнять read-back и обновлять state только по фактическому ответу API.
|
||
|
||
### Терминология
|
||
- `resume_if_exists` и `delete_mode` считаются legacy-терминами и не используются в новой логике.
|