# Описание REST API веб-интерфейса kind-k8s-develop **Базовый префикс:** `/api/v1` **Автор:** Сергей Антропов — [devops.org.ru](https://devops.org.ru) ## Как смотреть документацию | Способ | 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` на `` (по умолчанию `/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). --- ## GET /api/v1/health Проверка: `kind`/`kubectl` в PATH и ответ движка контейнеров (`docker info` / `podman info` по `CONTAINER_CLI`). `status`: `ok` — всё готово к созданию кластеров; `degraded` — чего-то не хватает (см. поля ниже). **Пример ответа 200 (JSON):** ```json { "status": "ok", "kind_in_path": true, "kubectl_in_path": true, "container_cli": "docker", "container_engine_ok": true, "container_engine_detail": null } ``` **Если сокет Docker недоступен:** ```json { "status": "degraded", "kind_in_path": true, "kubectl_in_path": true, "container_cli": "docker", "container_engine_ok": false, "container_engine_detail": "Cannot connect to the Docker daemon..." } ``` --- ## GET /api/v1/versions Список стабильных тегов `kindest/node` с Docker Hub (для выпадающего списка в UI). При `KIND_K8S_SKIP_VERSION_LIST=1` список пустой. **Пример ответа 200:** ```json { "tags": ["v1.32.0", "v1.31.4"], "skipped": false } ``` **Пример при пропуске загрузки:** ```json { "tags": [], "skipped": true, "reason": "KIND_K8S_SKIP_VERSION_LIST" } ``` --- ## GET /api/v1/stats Сводная статистика для дашборда. **Пример ответа 200:** ```json { "kind_clusters_count": 2, "local_cluster_dirs_count": 2, "total_workers_from_meta": 4, "jobs_total": 5, "jobs_recent_failed": 1 } ``` - `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/*` (без дубликатов). **Пример ответа 200 (массив):** ```json [ { "name": "dev", "registered_in_kind": true, "has_local_kubeconfig": true, "meta": { "cluster_name": "dev", "kubernetes_version_tag": "v1.29.4", "node_image": "kindest/node:v1.29.4", "worker_nodes": 2, "kubeconfig_patched_for_host": true } } ] ``` --- ## GET /api/v1/jobs Список последних фоновых заданий (создание кластера), от новых к старым. **Query:** `limit` (1–200, по умолчанию **30**). **Пример ответа 200 (массив `JobView`):** ```json [ { "job_id": "abc123", "kind": "create_cluster", "status": "success", "cluster_name": "dev", "created_at_utc": "2026-04-04T12:00:00+00:00", "message": "Кластер создан", "result": { "cluster_name": "dev", "kubernetes_version_tag": "v1.29.4" } } ] ``` --- ## GET /api/v1/clusters/{name}/kubeconfig Скачать файл `kubeconfig` (ответ — тело файла, `Content-Disposition` с именем `kubeconfig-{name}.yaml`). **Ошибка 404:** файла нет в `clusters/{name}/`. **Ошибка 400:** некорректное имя кластера. --- ## GET /api/v1/clusters/{name}/workloads `kubectl get nodes -o wide` и `kubectl get pods -A` по сохранённому kubeconfig. **Пример ответа 200:** ```json { "cluster_name": "dev", "nodes_rc": 0, "nodes_output": "NAME STATUS ROLES ...", "pods_rc": 0, "pods_output": "NAMESPACE NAME READY STATUS ...", "error": null } ``` Если kubeconfig нет: `error` — строка вида **`Нет сохранённого kubeconfig в clusters/<имя>/`**, поля вывода kubectl могут быть `null`. **Ошибка 400:** некорректное имя кластера. --- ## GET /api/v1/clusters/{name} Детали и попытка `kubectl get nodes -o wide` с **сохранённого** `clusters/{name}/kubeconfig` (если файл есть). **Пример ответа 200:** ```json { "name": "dev", "registered_in_kind": true, "has_local_kubeconfig": true, "kubeconfig_path": "/work/clusters/dev/kubeconfig", "meta": { "worker_nodes": 2 }, "kubectl_get_nodes_rc": 0, "kubectl_get_nodes": "NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME\n..." } ``` --- ## POST /api/v1/clusters Создание кластера **в фоне** (ответ **202**). **Тело запроса (JSON):** ```json { "name": "dev", "kubernetes_version": "1.29.4", "workers": 2 } ``` **Пример ответа 202:** ```json { "job_id": "a1b2c3d4e5f6...", "status": "queued", "message": "Создание кластера выполняется в фоне; опросите GET /api/v1/jobs/{job_id}" } ``` **Ошибка 400:** невалидное имя кластера или тело не проходит валидацию Pydantic. **Ошибка 409 (кластер уже есть в kind):** ```json { "detail": "Кластер с таким именем уже есть в kind" } ``` --- ## GET /api/v1/jobs/{job_id} Статус фонового задания создания. **В процессе (пример 200):** ```json { "job_id": "a1b2...", "kind": "create_cluster", "status": "running", "cluster_name": "dev", "created_at_utc": "2026-04-04T12:00:00+00:00", "message": null, "result": null } ``` **Успех (пример 200):** ```json { "job_id": "a1b2...", "kind": "create_cluster", "status": "success", "cluster_name": "dev", "created_at_utc": "2026-04-04T12:00:00+00:00", "message": "Кластер создан", "result": { "cluster_name": "dev", "kubernetes_version_tag": "v1.29.4", "node_image": "kindest/node:v1.29.4", "workers": 2, "kubeconfig_path": "/work/clusters/dev/kubeconfig", "kubeconfig_patched_for_host": true, "nodes_ready": true, "nodes_ready_message": "..." } } ``` **Ошибка 404:** ```json { "detail": "Задание не найдено" } ``` --- ## DELETE /api/v1/clusters/{name} `kind delete cluster` и удаление каталога `clusters/{name}/`. **Пример ответа 200:** ```json { "name": "dev", "kind_delete_ok": true, "summary": "kind delete: OK; удалена папка /work/clusters/dev" } ``` **Ошибка 400:** некорректное имя кластера. **Ошибка 500:** логическая ошибка удаления (тело с `detail`). --- ## GET / HTML-дашборд (не JSON): см. раздел «Веб-интерфейс и статика» выше.