kind-k8s-develop — локальные кластеры Kubernetes (kind)

Образ kind-k8s-tools:local и Makefile поднимают веб-интерфейс (FastAPI) на порту 6000 на хосте: через браузер создаёте и удаляете кластеры, смотрите статистику. kubeconfig сохраняется в clusters/<имя>/. На хосте достаточно Docker (или Podman) и make; kind и kubectl — внутри контейнера.

Автор: Сергей Антропов — devops.org.ru

Зачем это нужно

• Быстро получить Kubernetes без облака (интеграционные тесты, манифесты, обучение).
• Версия кластера и число worker-нод задаются в веб-UI (или при необходимости скриптами/API).
• Количество кластеров не ограничено кодом (ограничения — ресурсы хоста и Docker).
• Артефакты на хосте: clusters/<имя>/ — удобно указать путь к kubeconfig в приложении или в kubectl.

Требования на хосте

Компонент	Назначение
Docker + Compose v2 (или Podman + compose)	Сборка образа и запуск веб-сервиса
make	make docker up / make podman up и вспомогательные цели
kubectl (опционально)	Проверка API с хоста: kubectl --kubeconfig=clusters/<имя>/kubeconfig get nodes

На хост не ставятся: Python, kind — всё в образе.

Смонтированы сокет Docker/Podman и каталог ./clusters → в контейнере /work/clusters.

После создания кластера из UI kubeconfig патчится на https://127.0.0.1:<порт> для доступа с хоста, см. kubeconfig_patch.py.

Быстрый старт

cd kind-k8s-develop
make setup           # опционально: интерактивно .env (скрипт в scripts/; Enter — дефолты как в compose; нужен python3)
make docker check-docker    # или: make podman check-docker
make docker up       # или: make podman up
# Браузер: http://127.0.0.1:6000  (порт: KIND_K8S_WEB_PORT в .env)

Из родительского каталога: make -C kind-k8s-develop docker up.

Логи и остановка: make docker logs / make podman logs, make docker down / make podman down.

Описание REST API и примеры JSON: app/docs/api_routes.md, интерактивно: /docs на том же порту.

Разработка UI и API без пересборки образа

В docker-compose.yml каталог ./app смонтирован в контейнер как /opt/kind-k8s/app — исправления в Python, шаблонах и static/ на хосте сразу видны внутри сервиса.

По умолчанию (KIND_K8S_UVICORN_RELOAD=1) uvicorn запускается с --reload и перезапускает процесс при изменении *.py, *.html, *.css, *.js в app/. Пересобирать образ нужно только после изменений Dockerfile, requirements.txt или скрипта scripts/run_uvicorn.sh.

Отключить reload: в .env задать KIND_K8S_UVICORN_RELOAD=0.

Дополнительно: CLI в одноразовом контейнере

Если нужен сценарий без UI (CI, скрипты):

docker compose run --rm --entrypoint python3 kind-k8s-web \
  /opt/kind-k8s/app/create_cluster.py --non-interactive --name dev --kubernetes-version 1.29.4 --workers 2

docker compose run --rm --entrypoint python3 kind-k8s-web \
  /opt/kind-k8s/app/delete_cluster.py --non-interactive --name dev --yes

Рабочий каталог сервиса в образе — /opt/kind-k8s/app; том clusters/ и сокет те же, что у docker compose up.

После успешного kind create по умолчанию выполняется kubectl wait готовности нод (KIND_K8S_WAIT_NODES, KIND_K8S_WAIT_NODES_TIMEOUT_SEC в .env).

Команды Makefile

Цель	Описание
make help	Краткая справка
make docker up / make podman up	Поднять веб-UI (kind-k8s-web)
make docker down / make podman down	Остановить compose в каталоге репозитория
make docker logs / make podman logs	Логи kind-k8s-web
make docker compose-build / make podman compose-build	Собрать образ kind-k8s-tools:local
make docker check-docker / make podman check-docker	Проверить выбранный CLI и compose version
make setup	Интерактивно заполнить .env: переменные и подсказки в scripts/setup_env_interactive.py, дефолты как в docker-compose
make clusters-dir	Создать каталог clusters/
make docker … / make podman …	Префикс обязателен для целей up, down, logs, compose-build, check-docker

Цели up, down, logs, compose-build и check-docker без docker/podman в той же команде завершатся с подсказкой.

Переменные окружения

Файл .env в корне репозитория подхватывает Compose. Создать его можно командой make setup (опрос по списку в scripts/setup_env_interactive.py) или вручную.

Переменная	Где используется	Назначение
KIND_VERSION	build-arg	Версия бинарника kind при сборке образа
KUBECTL_VERSION	build-arg	Версия kubectl в образе; в Dockerfile без build-arg — stable.txt; make setup предлагает закреплённый тег
KIND_K8S_WEB_PORT	ports	Порт на хосте для веб-UI (в контейнере 6000)
KIND_K8S_UVICORN_RELOAD	контейнер	1 (по умолчанию) — hot-reload при правках в ./app; 0 — без reload
KIND_K8S_APP_TITLE	контейнер	Заголовок в OpenAPI и HTML
KIND_K8S_WAIT_NODES	контейнер	0 — не ждать Ready нод после create
KIND_K8S_WAIT_NODES_TIMEOUT_SEC	контейнер	Таймаут kubectl wait (секунды)
CONTAINER_SOCKET	volume	Сокет Docker/Podman
KIND_K8S_PATCH_KUBECONFIG	контейнер	Патч server в kubeconfig на хост; по умолчанию включено (1 в compose и в make setup)
CONTAINER_CLI	контейнер	CLI для docker port
KIND_K8S_SKIP_VERSION_LIST	контейнер	Не ходить в Docker Hub за тегами
KIND_K8S_VERSION_LIST_DISPLAY	контейнер	Сколько тегов показывать в списке
KIND_K8S_HUB_TAGS_MAX_PAGES	контейнер	Лимит страниц API Hub
KIND_K8S_DEBUG	контейнер	Уровень DEBUG в логах
COMPOSE_BUILD_FLAGS	Makefile	Например make docker compose-build COMPOSE_BUILD_FLAGS=--platform linux/arm64

Podman (пример rootless)

export CONTAINER_SOCKET="$XDG_RUNTIME_DIR/podman/podman.sock"
make podman up

Файлы

Путь	Назначение
Makefile	Запуск веб-UI и вспомогательные цели
scripts/setup_env_interactive.py	Интерактивное создание .env (список переменных и дефолты внутри скрипта)
scripts/run_uvicorn.sh	Точка входа веб-сервиса: uvicorn с опциональным --reload
Dockerfile	Образ: kind, kubectl, docker-cli, FastAPI
requirements.txt	pip-зависимости веб-интерфейса
docker-compose.yml	Сервис kind-k8s-web, том ./clusters, сокет
app/main.py	FastAPI, дашборд
app/api/v1/	REST API
app/core/	Логика кластеров, задания, блокировки
app/docs/api_routes.md	Описание маршрутов с примерами JSON
app/create_cluster.py, delete_cluster.py, …	Используются веб-API и при ручном compose run

В UI и API список версий kindest/node по умолчанию тянется с Docker Hub (нужна сеть). В изолированной среде: KIND_K8S_SKIP_VERSION_LIST=1 — версию вводят вручную.

Где лежат данные на хосте

• clusters/<имя>/kind-config.yaml
• clusters/<имя>/kubeconfig
• clusters/<имя>/meta.json

Содержимое clusters/*/ не коммитится; в репозитории есть clusters/.gitkeep.

Ограничения

• Образ kindest/node:v… должен быть доступен для pull.
• На Windows без WSL удобнее WSL2 + Docker Desktop.
• Для проверки с хоста нужен отдельный kubectl (в образе kubectl только внутри контейнера).
• При exec format error у kind пересоберите образ: make docker compose-build COMPOSE_BUILD_FLAGS=--platform linux/arm64 (или make podman …, или linux/amd64).