docs: HOWTO for cloud devops + update TEST_STAND manifests for new API Gateway

- HOWTO_IMPLEMENT_NEW_CLOUD_SERVICE.md: rules for implementing new managed services (naming, params, map-fixed blocks, operations, subresources, validation, checklist) - HOWTO_ADD_NEW_SERVICE.md: how to add service to terraform provider pipeline - TEST_STAND/*/main.tf: version 5.0.57, api_endpoint -> lk-api-gateway-test - TEST_STAND/POSTGRES/resources.tf: rewritten for new map-fixed param structure
2026-07-02 17:38:42 +04:00
parent 612aa53caf
commit 0c8223dd11
7 changed files with 550 additions and 39 deletions
@@ -0,0 +1,282 @@
+# Инструкция для DevOps облака: имплементация нового managed-сервиса
+
+> На основе анализа 43 сервисов Nubes Cloud (июль 2026).
+> Цель: единый стандарт, чтобы любой новый сервис был консистентен с существующими.
+
+---
+
+## 1. Классификация сервиса
+
+Выбери один из двух классов ДО начала проектирования параметров:
+
+| Класс | Признак | Размещение | Примеры |
+|---|---|---|---|
+| **Простой** | Не требует оркестрации K8s | VM, сеть, хранилище | s3bucket, vc_vm, dnszone, vcexternalip, harbor |
+| **Сложный (K8s)** | Разворачивается в Kubernetes через оператор | Pods на кластере | postgres, redis, kafka, clickhouse, flask, nextcloud |
+
+**Правило**: если сервис крутится в K8s → используй **map-fixed** блоки (раздел 3). Если нет → плоские параметры (раздел 2).
+
+---
+
+## 2. Простой сервис: плоские параметры
+
+### Обязательный минимум
+
+Каждый сервис ДОЛЖЕН иметь эти параметры в create:
+
+| code | data_type | required | Назначение |
+|---|---|---|---|
+| `resourceRealm` | `string` | true | Платформа/K8s-кластер для развёртывания |
+| `resourceName` | `string` | true | Человекочитаемое имя инстанса (displayName) |
+
+### Стандартные ресурсные параметры
+
+Добавляй по необходимости:
+
+| code | data_type | Назначение |
+|---|---|---|
+| `resourceInstances` | `integer > 0` | Количество реплик/нод (default: 1) |
+| `resourceMemory` | `integer > 0` | Память в MB |
+| `resourceCPU` | `integer > 0` | CPU в милликорах (1000 = 1 vCPU) |
+| `resourceDisk` | `string` | Диск в GB |
+
+### Прочие частые параметры
+
+| code | data_type | Где используется |
+|---|---|---|
+| `domain` | `string` | Сервисы с доменным именем (9 из 43) |
+| `ipSpaceName` | `string` | Сервисы с внешним IP |
+| `appConfiguration` | `map-fixed` | Приложения (nextcloud, superset, harbor, ...) |
+| `jsonEnv` | `json` | Переменные окружения (flask, nodejs) |
+| `storageConfig` | `map-fixed` | Хранилище (kafka, clickhouse) |
+
+---
+
+## 3. Сложный сервис (K8s): map-fixed блоки
+
+**Правило**: группируй параметры в логические блоки. Используй этот стандартный набор:
+
+### 3.1. startupConfiguration (sort: 10)
+**Назначение**: версия ПО, образ, всё что задаётся до старта.
+```
+appVersion, image, imageTag, ...
+```
+**required**: true. **is_modifiable**: false (не меняется после создания).
+
+### 3.2. clusterConfiguration (sort: 20)
+**Назначение**: размер кластера, ресурсы.
+```
+platform (= resourceRealm), instances, memory, cpu, disk
+```
+**required**: true. **is_modifiable**: true.
+
+### 3.3. accessConfiguration (sort: 30)
+**Назначение**: сетевой доступ.
+```
+needExternalAddressMaster, ipSpaceNameMaster,
+needExternalAddressSlave, ipSpaceNameSlave,
+allowNoSsl
+```
+**required**: true. **is_modifiable**: true.
+
+### 3.4. {service}Configuration (sort: 40)
+**Назначение**: специфичные для сервиса настройки.
+```
+enablePgPoolerMaster, enablePgPoolerSlave, s3Uid, jsonParameters, ...
+```
+**required**: true. **is_modifiable**: true.
+
+### 3.5. {service}Conf (sort: 50)
+**Назначение**: массив дополнительных конфигураций.
+Тип: `array-map-fixed`.
+**required**: false. **is_modifiable**: true.
+
+### 3.6. backupConfiguration (sort: 60)
+**Назначение**: политика резервного копирования.
+```
+schedule (cron), numToRetain, ...
+```
+**required**: true. **is_modifiable**: true.
+
+### 3.7. autoscaleConfiguration (sort: 70)
+**Назначение**: автоскейлинг.
+```
+autoScale (boolean), percentage, techWindow, quotaGb
+```
+**required**: true. **is_modifiable**: true.
+
+### Пример структуры для нового K8s-сервиса
+
+```
+create params (sort order):
+  10: startupConfiguration     map-fixed   required
+  20: clusterConfiguration     map-fixed   required   modifiable
+  30: accessConfiguration      map-fixed   required   modifiable
+  40: {name}Configuration      map-fixed   required   modifiable
+  50: {name}Conf              array-map   optional   modifiable
+  60: backupConfiguration      map-fixed   required   modifiable
+  70: autoscaleConfiguration   map-fixed   required   modifiable
+```
+
+---
+
+## 4. Именование параметров
+
+### ⛔ Жёсткие правила
+
+- **camelCase** для ВСЕХ кодов параметров: `resourceRealm`, `clusterConfiguration`, `dbName`
+- **Никакого snake_case**: ❌ `resource_realm`, ✅ `resourceRealm`
+- **Никакого хаотичного нейминга**: если параметр про память — везде `resourceMemory`, не `memoryQuota` или `memLimit`
+- **Префиксы**: общие параметры с префиксом `resource*` (resourceRealm, resourceCPU, resourceMemory, resourceDisk, resourceInstances)
+
+### Стандартный словарь
+
+| Концепт | Код параметра |
+|---|---|
+| Платформа/K8s-кластер | `resourceRealm` |
+| Количество реплик | `resourceInstances` |
+| Память (MB) | `resourceMemory` |
+| CPU (millicore) | `resourceCPU` |
+| Диск (GB) | `resourceDisk` |
+| Версия ПО | `appVersion` |
+| Домен | `domain` |
+| S3-ссылка | `s3Uid` |
+| IP-space | `ipSpaceName` |
+| Внешний IP для master | `needExternalAddressMaster` |
+| Внешний IP для slave | `needExternalAddressSlave` |
+| PgBouncer master | `enablePgPoolerMaster` |
+| PgBouncer slave | `enablePgPoolerSlave` |
+| Отключить SSL | `allowNoSsl` |
+| Автоскейлинг | `autoScale` |
+| Cron бэкапа | `backupSchedule` |
+
+---
+
+## 5. Операции
+
+### Обязательные (каждый сервис)
+
+| operation | kind | action |
+|---|---|---|
+| `create` | instance | create |
+| `delete` | instance | delete |
+
+### Настоятельно рекомендуемые
+
+| operation | kind | action | Зачем |
+|---|---|---|---|
+| `modify` | instance | modify | Изменение параметров без удаления |
+| `suspend` | instance | suspend | Остановка без удаления (биллинг!) |
+| `resume` | instance | resume | Запуск после suspend |
+
+**Правило**: если реализовал `suspend` → ОБЯЗАТЕЛЬНО реализовать `resume`. И наоборот.
+
+### Опциональные
+
+| operation | kind | action | У кого есть |
+|---|---|---|---|
+| `restart` | action | restart | postgres, mariadb, redis, kafka |
+| `recovery` | action | recovery | postgres, clickhouse |
+| `reconcile` | action | reconcile | 20 сервисов (универсальная синхронизация) |
+| `redeploy` | action | redeploy | flask, nodejs, lucee, nifi, superset |
+
+---
+
+## 6. Subresource'ы
+
+### Стандартные
+
+| subresource | operations | Параметры | У скольких сервисов |
+|---|---|---|---|
+| **user** | create_user, delete_user | `username` (string, regex), `role` (string, value_list) | 16 |
+| **database** | create_database, delete_database | `dbName` (string, regex), `dbOwner` (string) | 6 |
+
+### Специфичные
+
+| subresource | Где |
+|---|---|
+| `topic` | kafka (3 операции) |
+| `backup` | s3, postgres |
+| `vdc` | vcOrg |
+| `sub_user` | openwhisk |
+
+### Правила subresource'ов
+
+- **Именование операций**: `create_{subresource}`, `delete_{subresource}` (snake_case глагол + имя)
+- **Именование subresource**: одно слово, snake_case: `user`, `database`, `topic`
+- **Ссылка на родителя**: обязательный UUID-параметр, ссылающийся на родительский инстанс
+- **Параметр `role` для user**: ОБЯЗАТЕЛЬНО `value_list` с вариантами (например `[app_user, ddl_user]`)
+- **Параметр `dbName` для database**: ОБЯЗАТЕЛЬНО `regex: ^[A-Za-z0-9]+$`
+
+---
+
+## 7. Валидация параметров
+
+### Обязательно (где применимо)
+
+| Механизм | Когда | Пример |
+|---|---|---|
+| `value_list` | Ограниченный набор значений | `role: [app_user, ddl_user]` |
+| `regex` | Имена, идентификаторы | `dbName: ^[A-Za-z0-9]+$` |
+| `minlength` | Минимальная длина строки | `username: min 2` |
+| `maxlength` | Максимальная длина строки | `username: max 62` |
+| `minvalue` | Минимальное число | `resourceCPU: > 0` |
+| `maxvalue` | Максимальное число | — |
+| `default` | Значение по умолчанию | `deleteS3Bucket: true` |
+
+### ⛔ Запрещено
+
+- Параметр без `descr` (описание) — ВСЕГДА заполнять
+- Булевы параметры без `default` — если не указан, поведение неопределено
+- `required: true` для параметра с `default` — бессмысленно
+
+---
+
+## 8. Модифицируемость (is_modifiable)
+
+### Правило
+
+| Категория параметра | is_modifiable |
+|---|---|
+| Имя, версия ПО, платформа (startup) | **false** |
+| Ресурсы (CPU, память, диск, реплики) | **true** |
+| Доступ (IP, SSL, pooler) | **true** |
+| Бэкапы, автоскейлинг | **true** |
+| Всё что в modify-операции | **true** |
+
+106 из 435 параметров (24%) имеют `is_modifiable: true`.
+
+---
+
+## 9. Outputs
+
+**Не трогать.** Стандартный набор выходных параметров един для всех сервисов:
+
+```
+state_params       map
+state_out          map
+state_params_flat  map
+state_out_flat     map
+vault_secrets      map      sensitive
+vault_url          string
+vault_user_path    string
+vault_fields       list
+```
+
+---
+
+## 10. Чек-лист перед сдачей сервиса
+
+- [ ] `resourceRealm` есть в create (required)
+- [ ] `resourceName` есть в create (required)
+- [ ] Все коды параметров — camelCase
+- [ ] Для K8s-сервиса: 6 стандартных map-fixed блоков с правильными sort
+- [ ] `suspend` + `resume` либо есть оба, либо нет ни одного
+- [ ] `modify` содержит все `is_modifiable: true` параметры из create
+- [ ] У всех параметров заполнен `descr`
+- [ ] Булевы параметры имеют `default`
+- [ ] `username` для user-subresource имеет regex и minlength/maxlength
+- [ ] `role` для user-subresource имеет value_list
+- [ ] `dbName` для database-subresource имеет regex
+- [ ] MAN (service_man) заполнен: описание, параметры, примеры
+- [ ] MAN для каждой операции (operation.man) заполнен