“Naeel”
612aa53caf
- service_spec_gen: callAPI() auto-detects proxy vs REST mode by index.cfm presence
- core/client.go: buildURL() replaces all 4 ?endpoint= harcoded sites
- build-provider.sh: -ldflags -X main.version=${VERSION} for correct binary version
- 01_generate_yamls.sh (devops + root): Python auto-detect proxy vs REST
- 02_generate_resources_and_docs_v2.sh: pass -api-endpoint to doc generators
- 04_build_and_publish_docs.sh: normalize_api_endpoint without forced /index.cfm
- docs_template_gen + v2: -api-endpoint flag, hardcoded deck-api replaced
- provider.go (both): TODO(api-gateway) comments
- profiles/test/profile.env: NUBES_API_ENDPOINT -> lk-api-gateway-test
- HISTORY: 2026-07-02_api_gateway_migration.md
99 lines
6.1 KiB
Markdown
99 lines
6.1 KiB
Markdown
# 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
|
||
```
|
||
|
||
Всё остальное — авто-детект.
|