Руководство по ctk Rest Api

Руководство по ctk Rest Api#

Назначение#

Это Cluster Tool Kit (CTK) REST API — сервис для упрощенного мониторинга и перезагрузки Kubernetes-подов, через Rest API с ролевой моделью доступа и аудитом событий.

Авторизация и безопасность#

В системе предусмотрено два способа взаимодействия:

JWT Bearer (Рекомендуемый):#

Сначала получаем токен через /auth/login

Затем передаем его в заголовке: Authorization: Bearer <token> Эндпоинты этого типа начинаются с нижнего подчеркивания (например, /_status)

Basic Auth (Для простых скриптов):#

Логин и пароль передаются прямо в JSON-теле запроса. Эндпоинты без подчеркивания (например, /status).

Основные Эндпоинты#

1. Аутентификация#

POST /auth/login Зачем: Обмен логина/пароля на временный JWT токен. Лимит: 3 попытки в минуту по умолчанию.

Пример:

curl -X 'POST' \
  'https://ctk-rest.api/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "admin",
  "username": "admin"
}'

2. Работа с сервисами (через Bearer Token)#

GET /{service_name}/_status — Получить состояние пода. POST /{service_name}/_restart — Удалить под (K8s создаст новый).

  • Body (опционально): {«reason»: «Причина перезагрузки»}

Пример:

$ curl -X 'POST' \                                                                                              
  'https://ctk-rest.api/global-scheduler/_restart' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "test"
}'

3. Работа с сервисами (через Basic Auth)#

POST /{service_name}/status

  • Body: {«username»: «…», «password»: «…»} POST /{service_name}/restart

  • Body: {«username»: «…», «password»: «…», «reason»: «…»}

Пример:

$ curl -X 'POST' \
  'https://ctk-rest.api/ctk-restapi/restart' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "admin",
  "username": "admin",
  "reason": "test"
}'

4. Служебные#

GET /health — Проверка доступности API (без авторизации). GET /me — Инфо о текущем пользователе и его правах (нужен токен).

Форматы ответов#

Статус сервиса (StatusResponse) При успешном запросе вы получите объект с состоянием пода:

{
  "service": "global-scheduler",
  "status": "running",
  "pod_name": "gs-cluster-1-global-scheduler-5f986",
  "pod_status": "Running",
  "replicas": 1,
  "timestamp": "2026-02-20T..."
}

Перезагрузка (RestartResponse)

{
  "status": "success",
  "action": "pod-restart",
  "service": "global-scheduler",
  "deleted_pods": ["gs-cluster-1-global-scheduler-5f986"],
  "reason": "manual update"
}

Валидация и ограничения#

Reason Validation: В системе стоит жесткий фильтр на поле reason. Нельзя использовать спецсимволы bash (типа ;, |, &), SQL-инъекции или попытки выхода из директории (../). Rate Limiting: По умолчанию лимит на запросы к сервисам — 10 в минуту по умолчанию.

Встроенная документация: Если запустить в development режиме, по адресу /docs будет доступен Swagger, а по /redoc — расширенная документация Rest API.

Настройка#

Настройка сервиса происходит через интерактивный ресбук.

Kubernetes сервисы#

Скрипт настройки предложит автоматически добавить существующие в этой группе ресурсов сервисы, также сервисы можно добавлять и удалять вручную, можно отредактировать: имя сервиса и селектор.

Kubernetes сервисы
==================

Существующие сервисы:
  1. global-scheduler
  2. global-server-excl
  3. global-server-share
  4. haproxy
  5. grafana
  6. rabbitmq
  7. ctk-restapi
Действие: (a)dd, (e)dit, (d)elete, (q)uit:e
Имя сервиса для редактирования:haproxy
Редактирование сервиса 'haproxy'
K8s сервис:gs-cluster-1-haproxy
Селектор:app=gs-cluster-1-haproxy

После этого нужно будет создать пользователей, задать им права доступа к сервисам.

Ролевая модель#

service:all — полный доступ. service:view — только просмотр статуса всех сервисов. service:{name}:restart — право на перезагрузку только конкретного сервиса.

Пользователи
============

Форматы: service:all, service:view, service:restart, service:NAME:view, service:NAME:restart
Существующие пользователи:
  1. admin
  2. viewer
Действие: (a)dd, (e)dit, (d)elete, (q)uit:e
Имя пользователя для редактирования:admin
Редактирование пользователя 'admin'
Текущие разрешения: service:all
Новые разрешения (через запятую):service:view, service:restart, service:all
Содержание