terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: разложить рабочие материалы по NOTES/ и HOW_TO/, корневой README — карта проекта

Browse Source 
- NOTES/: 10_plans, 20_prompts, 30_analysis, 40_chat_summaries, 60_reference + README в каждой папке
- HOW_TO/: все общие инструкции (сборка/заливка, DevOps-ранбук, добавление сервиса, миграция, генерация доков) + индекс «что нужно -> какой файл»
- новый README.md: карта проекта, пайплайн, стенды, реестр, запреты/грабли
- HOWTO-UPLOAD.md: исправлена легаси-схема версий (prod=1.*, dev=2.*, test=3.*)
- DEVOPS_BUILD_PIPELINE.md: пути скриптов -> TOOLS/scripts, universal_rebuild/main.go -> provider/main.go
- howitwasdone.md / MIGRATION_PLAN_FOR_AGENT.md: пометки о соответствии старых путей
- внутри перенесённых файлов обновлены ссылки на новые пути
This commit is contained in:
Repinoid
2026-09-24 07:51:38 +03:00
parent 2d8e435dd4
commit f7fffb9ed7
31 changed files with 549 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HOW_TO/DEVOPS_BUILD_PIPELINE.md
+12 -9
View File
@@ -1,6 +1,9 @@
# DevOps Runbook: Provider Build Pipeline
This repo root contains the 4 scripts for the full provider build pipeline.
> Перенесено из корневого `README.md` 2026-09-24 (в корне теперь — карта проекта).
> Пути и версии в тексте приведены к текущему состоянию репозитория.
Пайплайн сборки провайдера. Скрипты живут в `TOOLS/scripts/` (НЕ в корне репозитория).
## Overview
@@ -12,7 +15,7 @@ This repo root contains the 4 scripts for the full provider build pipeline.
## Documentation publishing instructions
The verified documentation generation and publishing pipeline is documented in
[`HISTORY/2026-09-03_docs_upload_pipeline_verified.md`](HISTORY/2026-09-03_docs_upload_pipeline_verified.md).
[`../HISTORY/2026-09-03_docs_upload_pipeline_verified.md`](../HISTORY/2026-09-03_docs_upload_pipeline_verified.md).
It covers the generated docs source, MkDocs build, the separate documentation
S3 bucket, VM upload and mirror steps, stand-specific URLs, and the legacy
script that must not be used.
@@ -39,10 +42,10 @@ Provider naming defaults:
## Step 1: Generate YAMLs from API
Script: `01_generate_yamls.sh`
Script: `TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/<стенд>`
Input list of services:
- `services_list.txt` (service_id only)
- `TOOLS/config/services_list.txt` (service_id only)
Token options:
- `TOKEN_FILE=/home/naeel/terra/HH-MM-SS.token`, or
@@ -51,7 +54,7 @@ Token options:
Example:
```bash
export TOKEN_FILE=/home/naeel/terra/08-33-41.token
./01_generate_yamls.sh
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
```
## Step 2: Generate Go resources and docs
@@ -83,7 +86,7 @@ Example:
export S3_ENDPOINT=https://s3.msk-1.ngcloud.ru
export S3_ACCESS_KEY=...
export S3_SECRET_KEY=...
./03_build_and_upload_provider.sh 2.0.2
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
```
## Step 4: Build and publish docs
@@ -95,7 +98,7 @@ Example:
export S3_ENDPOINT=https://s3.msk-1.ngcloud.ru
export S3_ACCESS_KEY=...
export S3_SECRET_KEY=...
./04_build_and_publish_docs.sh 2.0.2
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev 2.0.18
```
## Notes
@@ -103,8 +106,8 @@ export S3_SECRET_KEY=...
- The GPG private key must remain stable across releases. Do not regenerate per build.
- If the key is regenerated, the registry server must be updated to serve the new public key.
- Terraform will fail with `authentication signature from unknown issuer` if the registry public key does not match the signing key.
- `services_list.txt` is the source of truth for which services are generated.
- If the provider version changes, update `universal_rebuild/main.go`.
- `TOOLS/config/services_list.txt` — источник правды по тому, какие сервисы генерируются.
- Если меняется версия провайдера — обновить `provider/main.go` (ранее `universal_rebuild/main.go` — устаревший путь).
## One-time GPG bootstrap (do this once, keep the key stable)
HOW_TO/HOWTO-UPLOAD.md
+19 -15
View File
@@ -4,11 +4,15 @@
**Первая цифра версии жёстко привязана к стенду. НЕ ПУТАТЬ.**
| Стенд | Namespace | Первая цифра | Профиль |
| Стенд | Namespace | Диапазон | Профиль |
|---|---|---|---|
| **PROD** | `nubes` | `2.*` | `TOOLS/config/prod` |
| **DEV** | `nubes-dev` | `3.*` | `TOOLS/config/dev` |
| **TEST** | `nubes-test` | `5.*` | `TOOLS/config/test` |
| **PROD** | `nubes` | `1.*` | `TOOLS/config/prod` |
| **DEV** | `nubes-dev` | `2.*` | `TOOLS/config/dev` |
| **TEST** | `nubes-test` | `3.*` | `TOOLS/config/test` |
> ⛔ ЛЕГАСИ (не использовать): `prod=2.*`, `dev=3.*`, `test=5.*`, `0.0.1`.
> Примеры версий ниже в этом файле могут содержать легаси-номера — подставляйте актуальную
> из `../VERSIONS.md`.
## Архитектура конфигурации
@@ -23,7 +27,7 @@ TOOLS/config/
│ NUBES_API_ENDPOINT = ...dev...
│ TOKEN_FILE = secrets/dev.token
│ NAMESPACE = nubes-dev
│ VERSION = 3.x.x
│ VERSION = 2.x.x ← актуальную брать из VERSIONS.md
│
├── test/profile.env
└── prod/profile.env
@@ -65,7 +69,7 @@ cd ~/tf_provider
### Шаг 3 — Собрать и залить в реестр
```bash
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 3.1.13
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
```
Компилирует (linux/windows/darwin), подписывает GPG, заливает в S3.
@@ -75,7 +79,7 @@ cd ~/tf_provider
```bash
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev && \
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev && \
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 3.1.13
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
```
## Быстрая заливка (без перегенерации YAML/Go)
@@ -83,14 +87,14 @@ cd ~/tf_provider
Если YAML'ы и Go-код уже сгенерированы и не менялись — только шаг 3:
```bash
# DEV
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 3.1.13
# DEV (2.*)
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
# TEST
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 5.1.17
# TEST (3.*)
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 3.0.1
# PROD
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/prod 2.1.23
# PROD (1.*)
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/prod 1.0.1
```
Креды S3 подхватываются из `secrets/.s3cfg_registry`. Или через env:
@@ -129,7 +133,7 @@ curl -s https://tf-registry.containerk8s.services.ngcloud.ru/v1/providers/nubes/
## Актуальные версии
Файл [`VERSIONS.md`](VERSIONS.md) — единственный источник правды. После каждой заливки — обновить.
Файл [`../VERSIONS.md`](../VERSIONS.md) — единственный источник правды. После каждой заливки — обновить.
## Terraform-конфиг пользователя
@@ -138,7 +142,7 @@ terraform {
required_providers {
nubes = {
source = "tf-registry.containerk8s.services.ngcloud.ru/nubes-dev/nubes"
version = "3.1.13"
version = "2.0.18"
}
}
}
HOW_TO/MIGRATION_PLAN_FOR_AGENT.md
+8 -1
View File
@@ -1,5 +1,12 @@
# План миграции в Nubes Managed Kubernetes — Инструкции для агента
> ⚠️ **Пути `universal_rebuild/*` в этом плане — от ПРЕЖНЕЙ раскладки репозитория.** Актуально:
> `universal_rebuild/internal/*` → `provider/internal/*`; `universal_rebuild/resources_yaml` →
> `generated/<стенд>/resources_yaml`; `universal_rebuild/tools/gen` → `TOOLS/resource-generator`.
> Также план писался ДО смены схемы версий: актуально `prod=1.*`, `dev=2.*`, `test=3.*`.
> Часть про миграцию `registry.kube5s.ru` → `registry.nubes.ru` — ИСТОРИЧЕСКАЯ: актуальный реестр
> `tf-registry.containerk8s.services.ngcloud.ru` (бакет `nubes-terraform-registry`).
**Создан:** 2026-03-13 (Opus 4.6)
**Исполнитель:** Sonnet 4.6
**Статус:** Ожидает исполнения
@@ -24,7 +31,7 @@ Nubes (nubes.ru) — российский cloud-провайдер, собств
**Обязательно прочитать перед работой:**
- `REPO_CONTENTS.md` — карта репозитория
- `.github/copilot-instructions.md` — правила работы (IMMUTABILITY POLICY)
- `docs/CODEBASE_ANALYSIS_AND_ROADMAP.md` — анализ кодовой базы
- `NOTES/30_analysis/CODEBASE_ANALYSIS_AND_ROADMAP.md` — анализ кодовой базы
---
HOW_TO/README.md
+66
View File
@@ -0,0 +1,66 @@
# HOW_TO — все инструкции проекта
Здесь лежат **общие инструкции**: как собрать/залить провайдер, как добавить сервис, как устроены
процессы. Отсюда начинать, если нужно что-то «сделать руками».
> Публикуемая пользовательская документация — в `../docs/` (mkdocs).
> Рабочие материалы (планы, промпты, анализы) — в `../NOTES/`.
---
## Индекс: что нужно → какой файл
| Нужно | Файл | Кому |
|---|---|---|
| **Собрать и залить провайдер** (YAML → Go → бинарник → S3) | [`HOWTO-UPLOAD.md`](HOWTO-UPLOAD.md) | Релиз-инженеру |
| **Полный DevOps-ранбук пайплайна** (4 шага: генерация, ресурсы+доки, сборка, публикация доков) + GPG-bootstrap | [`DEVOPS_BUILD_PIPELINE.md`](DEVOPS_BUILD_PIPELINE.md) | DevOps |
| **Добавить новый сервис** в провайдер (полный цикл) | [`HOWTO_ADD_NEW_SERVICE.md`](HOWTO_ADD_NEW_SERVICE.md) | Разработчику провайдера |
| **Имплементировать новый managed-сервис** (со стороны облака) | [`HOWTO_IMPLEMENT_NEW_CLOUD_SERVICE.md`](HOWTO_IMPLEMENT_NEW_CLOUD_SERVICE.md) | DevOps облака |
| **Понять, как всё устроено на практике** (закрытый developer-guide) | [`howitwasdone.md`](howitwasdone.md) | Разработчику провайдера |
| **Генерация документации** (архитектура, пайплайн, правила для LLM) | [`LLM_DOCS_GENERATION.md`](LLM_DOCS_GENERATION.md) | Разработчику доков |
| **План миграции + runbook реестра** (обновление, откат, troubleshooting, мониторинг) | [`MIGRATION_PLAN_FOR_AGENT.md`](MIGRATION_PLAN_FOR_AGENT.md) | Агенту/инженеру |
---
## Короткий путь: собрать и залить (3 шага)
```bash
cd /home/naeel/TF/tf_provider
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
```
Полные детали, требования, проверка после заливки и структура S3 — в [`HOWTO-UPLOAD.md`](HOWTO-UPLOAD.md).
## Текущие версии (источник правды)
[`../VERSIONS.md`](../VERSIONS.md). Схема нумерации: **prod = `1.*`, dev = `2.*`, test = `3.*`**
(легаси `prod=2.*`, `dev=3.*`, `test=5.*`, `0.0.1` — НЕ использовать). Обоснование схемы:
[`../NOTES/10_plans/PLAN_FLASH_reversion_cleanup.md`](../NOTES/10_plans/PLAN_FLASH_reversion_cleanup.md).
---
## Где лежит остальное (чтобы не искать вслепую)
| Тема | Где |
|---|---|
| Операционные runbook'и (API-токены, стенды, мониторинг, откат, тестирование, реестр) | `../docs/ops/` |
| Внутренние справки/разборы по сборке и архитектуре | `../docs/help/` (напр. `BUILD.md`, `build-and-publish.md`) |
| Пайплайн публикации документации | `../DOCS_PIPELINE/README.md`, `../DOCS_PIPELINE/publish-docs.sh` |
| Правила генерации кода провайдера (ОБЯЗАТЕЛЬНЫ для генератора) | `../TOOLS/ARCHITECTURE.md` |
| Скрипты пайплайна | `../TOOLS/scripts/` |
| Конфиги стендов и общий реестр | `../TOOLS/config/` (`registry.env`, `<стенд>/profile.env`, `services_list.txt`) |
| Секреты (не коммитить) | `../secrets/` |
| Текущая задача по IaC/`modify` | `../NOTES/40_chat_summaries/CHAT_RESUME_IAC_2026-09-24.md` |
---
## ⛔ Частые грабли (не наступать)
- **Не вызывать** устаревшие бинарники `TOOLS/*/bin/` — скрипт `02_*` сам пересобирает генераторы.
- **Не путать** схемы версий: только `prod=1.*`, `dev=2.*`, `test=3.*`.
- **Не использовать** старый API `index.cfm` и хосты `registry.kube5s.ru` / `deck-api.ngcloud.ru` — закрыты.
- **GPG-ключ** подписи не перегенерировать: иначе registry и `terraform init` сломаются
(`authentication signature from unknown issuer`).
- **S3-бакеты разделены**: бинарники — `nubes-terraform-registry`, документация — `terraform-registry`.
HOW_TO/howitwasdone.md
+7
View File
@@ -2,6 +2,13 @@
<!-- Актуальный API: https://lk-api-gateway.ngcloud.ru/api/v1/svc -->
# How It Was Done — Developer Guide (закрытая страница)
> ⚠️ **Пути в этом документе — от ПРЕЖНЕЙ раскладки репозитория (`universal_rebuild/*`).**
> Актуальное соответствие: `universal_rebuild/internal/*` → `provider/internal/*`;
> `universal_rebuild/resources_yaml` → `generated/<стенд>/resources_yaml`;
> `universal_rebuild/tools/gen` → `TOOLS/resource-generator`;
> `universal_rebuild/tools/service_params_gen` → `TOOLS/yaml-generator`.
> Смысл описанного сохраняется, но пути в тексте сверять по этому соответствию.
**Filename & Versioning:** howitwasdone.md / 2026‑02‑04 / Draft v1
Этот документ — единый технический мануал. Он доступен только по прямой ссылке и не включён в публичную навигацию.