Документация: README, api_routes, указатель app/docs
- README: веб-UI, структура static/templates, нет env.example, make setup, KIND_K8S_WEB_HOST, jobs в памяти, .gitignore, ссылки на /docs и ReDoc. - api_routes: сводная таблица маршрутов, UI/статика, поведение jobs (лимит 200), уточнение stats, коды 400 для kubeconfig/workloads/delete. - app/docs/README.md: навигация по документации приложения.
This commit is contained in:
Sergey Antropoff
11
app/docs/README.md
Normal file
11
app/docs/README.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Документация приложения (app/docs)
|
||||
|
||||
Каталог описаний для разработчиков и интеграции с UI.
|
||||
|
||||
| Файл | Назначение |
|
||||
|------|------------|
|
||||
| [api_routes.md](api_routes.md) | Полное описание REST API `/api/v1/*` с примерами JSON (ориентир для фронтенда и клиентов). |
|
||||
|
||||
После запуска сервиса доступны интерактивно: **Swagger** — `/docs`, **ReDoc** — `/redoc` (тот же порт, что и веб-UI).
|
||||
|
||||
**Автор:** Сергей Антропов — [devops.org.ru](https://devops.org.ru)
|
||||
@@ -3,7 +3,47 @@
|
||||
**Базовый префикс:** `/api/v1`
|
||||
**Автор:** Сергей Антропов — [devops.org.ru](https://devops.org.ru)
|
||||
|
||||
Интерактивная документация OpenAPI: после запуска `make docker up` откройте [http://127.0.0.1:6000/docs](http://127.0.0.1:6000/docs).
|
||||
## Как смотреть документацию
|
||||
|
||||
| Способ | URL / путь |
|
||||
|--------|------------|
|
||||
| Swagger UI (OpenAPI) | `http://127.0.0.1:<порт>/docs` (порт по умолчанию **6000**, см. `KIND_K8S_WEB_PORT`) |
|
||||
| ReDoc | `http://127.0.0.1:<порт>/redoc` |
|
||||
| Этот файл | `app/docs/api_routes.md` в репозитории |
|
||||
|
||||
## Веб-интерфейс и статика (не JSON)
|
||||
|
||||
| Маршрут | Описание |
|
||||
|---------|----------|
|
||||
| `GET /` | HTML-панель: статус среды (kind, kubectl, Docker/Podman), статистика, форма создания кластера, таблицы кластеров и заданий, модальное окно «узлы / поды», ссылки на API. |
|
||||
| `GET /ui` | Редирект **307** на `/` (удобный ярлык). |
|
||||
| `GET /static/…` | CSS (`style.css`), скрипт панели (`js/dashboard.js`); базовый URL API задаётся атрибутом `data-api-base` на `<body>` (по умолчанию `/api/v1`). |
|
||||
|
||||
Шаблоны: `app/templates/base.html` (шапка, навигация), `app/templates/dashboard.html` (контент панели).
|
||||
|
||||
---
|
||||
|
||||
## Сводка маршрутов API
|
||||
|
||||
| Метод | Путь | Кратко |
|
||||
|-------|------|--------|
|
||||
| GET | `/api/v1/health` | Среда: kind, kubectl, движок контейнеров |
|
||||
| GET | `/api/v1/versions` | Теги `kindest/node` (Docker Hub) или пусто при `KIND_K8S_SKIP_VERSION_LIST` |
|
||||
| GET | `/api/v1/stats` | Сводка для дашборда |
|
||||
| GET | `/api/v1/clusters` | Список кластеров |
|
||||
| POST | `/api/v1/clusters` | Создание в фоне (**202** + `job_id`) |
|
||||
| GET | `/api/v1/clusters/{name}` | Детали + `kubectl get nodes` при наличии kubeconfig |
|
||||
| GET | `/api/v1/clusters/{name}/kubeconfig` | Скачать файл kubeconfig |
|
||||
| GET | `/api/v1/clusters/{name}/workloads` | Узлы и поды (`kubectl`) |
|
||||
| DELETE | `/api/v1/clusters/{name}` | Удалить кластер и данные в `clusters/` |
|
||||
| GET | `/api/v1/jobs` | Последние задания создания |
|
||||
| GET | `/api/v1/jobs/{job_id}` | Статус одного задания |
|
||||
|
||||
### Фоновые задания (jobs)
|
||||
|
||||
- Хранятся **только в памяти** процесса uvicorn; после перезапуска контейнера история обнуляется.
|
||||
- В памяти держится не более **200** записей; при превышении старые задания вытесняются (`app/core/job_store.py`).
|
||||
- Создание кластера: `POST /api/v1/clusters` → опрос `GET /api/v1/jobs/{job_id}` (как в веб-UI).
|
||||
|
||||
---
|
||||
|
||||
@@ -82,13 +122,15 @@
|
||||
}
|
||||
```
|
||||
|
||||
Поле `total_workers_from_meta` может быть `null`, если ни в одном `meta.json` нет `worker_nodes`.
|
||||
- `total_workers_from_meta` может быть `null`, если ни в одном `meta.json` нет `worker_nodes`.
|
||||
- `jobs_total` — число заданий в текущей памяти процесса (не более 200).
|
||||
- `jobs_recent_failed` — сколько заданий в этом хранилище сейчас в статусе `failed` (не «последние N», а счётчик по всему снимку).
|
||||
|
||||
---
|
||||
|
||||
## GET /api/v1/clusters
|
||||
|
||||
Список имён: объединение `kind get clusters` и подкаталогов `clusters/*`.
|
||||
Список: объединение `kind get clusters` и подкаталогов `clusters/*` (без дубликатов).
|
||||
|
||||
**Пример ответа 200 (массив):**
|
||||
|
||||
@@ -113,9 +155,9 @@
|
||||
|
||||
## GET /api/v1/jobs
|
||||
|
||||
Список последних фоновых заданий (создание кластера), от новых к старым. Данные только в памяти процесса.
|
||||
Список последних фоновых заданий (создание кластера), от новых к старым.
|
||||
|
||||
**Query:** `limit` (1–200, по умолчанию 30).
|
||||
**Query:** `limit` (1–200, по умолчанию **30**).
|
||||
|
||||
**Пример ответа 200 (массив `JobView`):**
|
||||
|
||||
@@ -141,6 +183,8 @@
|
||||
|
||||
**Ошибка 404:** файла нет в `clusters/{name}/`.
|
||||
|
||||
**Ошибка 400:** некорректное имя кластера.
|
||||
|
||||
---
|
||||
|
||||
## GET /api/v1/clusters/{name}/workloads
|
||||
@@ -160,7 +204,9 @@
|
||||
}
|
||||
```
|
||||
|
||||
Если kubeconfig нет: `"error": "Нет сохранённого kubeconfig..."`, остальные поля подов/узлов — `null`.
|
||||
Если kubeconfig нет: `error` — строка вида **`Нет сохранённого kubeconfig в clusters/<имя>/`**, поля вывода kubectl могут быть `null`.
|
||||
|
||||
**Ошибка 400:** некорректное имя кластера.
|
||||
|
||||
---
|
||||
|
||||
@@ -186,7 +232,7 @@
|
||||
|
||||
## POST /api/v1/clusters
|
||||
|
||||
Создание кластера **в фоне** (ответ 202).
|
||||
Создание кластера **в фоне** (ответ **202**).
|
||||
|
||||
**Тело запроса (JSON):**
|
||||
|
||||
@@ -208,6 +254,8 @@
|
||||
}
|
||||
```
|
||||
|
||||
**Ошибка 400:** невалидное имя кластера или тело не проходит валидацию Pydantic.
|
||||
|
||||
**Ошибка 409 (кластер уже есть в kind):**
|
||||
|
||||
```json
|
||||
@@ -283,8 +331,11 @@
|
||||
}
|
||||
```
|
||||
|
||||
**Ошибка 400:** некорректное имя кластера.
|
||||
**Ошибка 500:** логическая ошибка удаления (тело с `detail`).
|
||||
|
||||
---
|
||||
|
||||
## GET /
|
||||
|
||||
HTML-дашборд (не JSON): форма создания, таблица кластеров, ссылки на Swagger.
|
||||
HTML-дашборд (не JSON): см. раздел «Веб-интерфейс и статика» выше.
|
||||
|
||||
Reference in New Issue
Block a user