tf_provider/HISTORY/2026-07-02_api_gateway_migration.md

2026-07-02 — Миграция с deck-api на API Gateway (lk-api-gateway)

Контекст

Старый API: https://deck-api-{stand}.ngcloud.ru/api/v1/index.cfm?endpoint=/services/123 Новый API Gateway: https://lk-api-gateway-{stand}.ngcloud.ru/api/v1/svc/services/123

Ответы JSON идентичны. Различается только формат URL:

• Старый: proxy через index.cfm?endpoint=
• Новый: прямые REST-пути

Цель: перевести TEST-стенд на новый Gateway, сохранив совместимость со старым для dev/prod.

Архитектурное решение

Авто-детект режима по наличию index.cfm в URL:

• Есть index.cfm → старый proxy (?endpoint=)
• Нет index.cfm → новый REST (прямая конкатенация пути)

Один env-параметр NUBES_API_ENDPOINT управляет всем.

Изменения (11 файлов)

1. Генератор YAML: universal_rebuild/tools/service_spec_gen/generate_service_spec.go

• normalizeAPIEndpoint() — убрано принудительное добавление /index.cfm, теперь только trim trailing slash
• getViaProxy() → callAPI() — авто-детект: если index.cfm в URL → ?endpoint=, иначе → прямая конкатенация {base}{path}
• Добавлен метод isProxyAPI() для детекта
• Обновлён комментарий с документированием двух режимов

2. Ядро провайдера: universal_rebuild/internal/core/client.go

• Добавлены isProxyAPI() и buildURL(path string) string — единая точка конструирования URL
• Заменены все 4 места с хардкодом ?endpoint=:
  • FindExistingInstances (пагинированный поиск, строка ~515)
  • GetInstanceState (строка ~590)
  • GetInstanceStateRaw (строка ~637)
  • doRequest (POST/PUT/GET, строки ~838-853)

3. Оркестратор YAML: devops/01_generate_yamls.sh

• Убрана принудительная нормализация if [[ "$API_ENDPOINT" != */index.cfm ]] → автоматическая
• Python-скрипт: авто-детект "index.cfm" in endpoint → ?endpoint= vs прямой путь

4. Генератор документации: devops/02_generate_resources_and_docs_v2.sh

• Добавлена передача -api-endpoint "$DOCS_API_ENDPOINT" в docs_template_gen_v2
• Нормализация: если нет ни index.cfm, ни /svc → дописать /index.cfm (обратная совместимость)

5. Публикация доков: devops/04_build_and_publish_docs.sh

• normalize_api_endpoint() — убрано принудительное /index.cfm, только trim

6. Корневой скрипт: 01_generate_yamls.sh (корень)

• Python-скрипт: такой же авто-детект, как в devops/01

7-8. Шаблоны документации: docs_template_gen_v2/main.go + docs_template_gen/main.go

• Добавлен флаг -api-endpoint (default: старый deck-api)
• Все хардкоды api_endpoint = "https://deck-api...index.cfm" заменены на fmt.Sprintf
• Проброшено через writeResourceDocs → buildExamplePage → exampleBlock → buildSubresourceExamplePage

9-10. Провайдеры: internal/provider/provider.go + universal_rebuild/internal/provider/provider.go

• Добавлен TODO(api-gateway) комментарий над дефолтным apiEndpoint
• Сам дефолт не менялся (runtime провайдера теперь использует core.buildURL())

11. Профиль TEST: devops/profiles/test/profile.env

• NUBES_API_ENDPOINT → https://lk-api-gateway-test.ngcloud.ru/api/v1/svc

Бонус: версия в бинарник

• devops/build-provider.sh: go build теперь с -ldflags "-X main.version=${VERSION}" — версия из профиля вшивается в бинарник (раньше всегда была из main.go)

Анализ пайплайна (попутно)

Полный пайплайн: services_list.txt → 01_generate_yamls.sh → 02_generate_resources_and_docs_v2.sh → 03_build_and_upload_provider.sh → 04_build_and_publish_docs.sh.

Найденные проблемы (не исправлялись, зафиксированы):

• main.go Address = nubes-test (только для test, для prod нужно nubes)
• Нет сборки под darwin/arm64 (Apple Silicon)
• Корневой 01_generate_yamls.sh ссылается на несуществующий service_params_gen
• Кросс-стадийная валидация отсутствует (сбои 01 не видны в 02)

Оставшиеся deck-api в коде

Только как значения по умолчанию (переопределяются через NUBES_API_ENDPOINT):

• service_spec_gen/generate_service_spec.go:150 — getenvDefault("NUBES_API_ENDPOINT", "https://deck-api...")
• devops/01_generate_yamls.sh:108 — ${NUBES_API_ENDPOINT:-https://deck-api...}
• devops/02_generate_resources_and_docs_v2.sh:95 — аналогично
• devops/04_build_and_publish_docs.sh:13,87 — аналогично
• docs_template_gen_v2/main.go:91 — flag default
• docs_template_gen/main.go:81 — flag default
• internal/provider/provider.go:105 + universal_rebuild/... — с TODO

Хардкодов в теле функций/примеров больше нет.

Для перехода dev/prod

Достаточно поменять одну строку в profile.env:

NUBES_API_ENDPOINT="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"   # dev
NUBES_API_ENDPOINT="https://lk-api-gateway.ngcloud.ru/api/v1/svc"       # prod

Всё остальное — авто-детект.