tf_provider/docs/HOWTO_IMPLEMENT_NEW_CLOUD_SERVICE.md

Инструкция для 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) заполнен