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

Образ kind-k8s-tools и Makefile: поднять kind на машине с Docker (или Podman + compose), сохранить kubeconfig в clusters/<имя>/ на хосте. Python-скрипты и бинарники kind/kubectl лежат внутри образа — на хосте достаточно Docker, make и при необходимости kubectl для проверки API.

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

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

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

Требования на хосте (основной сценарий)

Компонент	Назначение
Docker + Compose v2	Сборка образа и запуск (docker compose)
make	Цели create, delete, list, …
kubectl (опционально)	Проверка кластера с хоста после создания

На хост не ставятся: Python, kind, curl для kind — всё уже в образе kind-k8s-tools.

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

После make create kubeconfig патчится на https://127.0.0.1:<порт> (apiserver с хоста), см. kubeconfig_patch.py.

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

cd kind-k8s-develop
make setup           # опционально: интерактивно заполнить .env
make check-docker    # опционально: проверить docker compose
make create          # интерактивно: имя, версия образа нод, workers
kubectl --kubeconfig="$(pwd)/clusters/<имя>/kubeconfig" get nodes   # kubectl с хоста, если установлен
make delete

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

Команды Makefile

Цель	Описание
make help	Справка
make setup	Интерактивно заполнить .env по env.example (scripts/setup_env_interactive.py, нужен python3)
make check-docker	Проверить docker и docker compose
make compose-build	Собрать образ kind-k8s-tools
make create	Интерактивно создать кластер (в контейнере)
make delete	Интерактивно удалить кластер и clusters/<имя>/
make list	kind get clusters в контейнере
make status	Статус узлов (kubectl в контейнере)
make status CLUSTER=имя	Один кластер
make kubeconfig CLUSTER=имя	Путь к clusters/<имя>/kubeconfig на хосте
make create-compose / make delete-compose	То же, что create / delete (совместимость)

Локальный запуск скриптов на хосте (без образа)

Если kind, kubectl и Python уже в PATH (kind: установка):

Цель	Описание
make check-host	Проверить docker, kind, kubectl, python3
make create-host	app/create_cluster.py на хосте
make delete-host	app/delete_cluster.py на хосте
make status-host	app/cluster_status.py на хосте

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

Шаблон: env.example. Удобно выполнить make setup или скопировать в .env в корне этого каталога — Compose подхватывает .env при запуске отсюда.

Переменная	Где используется	Назначение
KIND_VERSION	docker-compose (build-arg)	Версия бинарника kind в образе при compose build / make compose-build.
CONTAINER_SOCKET	docker-compose (volume)	Сокет Docker/Podman на хосте (по умолчанию /var/run/docker.sock).
KIND_K8S_PATCH_KUBECONFIG	контейнер (environment)	1 / true — всегда патчить server в kubeconfig на 127.0.0.1:<порт>.
CONTAINER_CLI	контейнер (environment)	CLI к API контейнеров для docker port (по умолчанию docker).
KIND_K8S_SKIP_VERSION_LIST	контейнер	1 — не ходить в Docker Hub, версия только с клавиатуры.
KIND_K8S_VERSION_LIST_DISPLAY	контейнер	Сколько строк списка версий показать (по умолчанию 50, макс. 500).
KIND_K8S_HUB_TAGS_MAX_PAGES	контейнер	Лимит страниц API Hub при сборе тегов (по умолчанию 60, макс. 200).
KIND_K8S_DEBUG	контейнер	1 — уровень логов DEBUG для модулей kind-k8s.
COMPOSE	только Makefile	Команда Compose, по умолчанию docker compose; Podman: COMPOSE='podman compose'.
COMPOSE_BUILD_FLAGS	только Makefile	Аргументы к compose build, например --platform linux/arm64 при exec format error.

Podman (пример rootless)

export CONTAINER_SOCKET="$XDG_RUNTIME_DIR/podman/podman.sock"
COMPOSE='podman compose' make create

Файлы

Путь	Назначение
Dockerfile	Alpine, kind, kubectl, docker-cli; каталог app/ копируется в /opt/kind-k8s/app
docker-compose.yml	Том ./clusters, сокет Docker/Podman
scripts/setup_env_interactive.py	Интерактивное заполнение .env (цель make setup)
app/	Все Python-модули и скрипты (PYTHONPATH=/opt/kind-k8s/app в образе)
app/kind_k8s_paths.py	Корень данных: KIND_K8S_WORKDIR (в образе /work) или корень этого репозитория
app/create_cluster.py	Диалог создания кластера
app/delete_cluster.py	Удаление
app/cluster_status.py	Узлы и meta
app/kubeconfig_patch.py	Патч server в kubeconfig для доступа с хоста
app/kindest_node_tags.py	Теги kindest/node (1.19+) с Docker Hub для выбора версии

При make create скрипт запрашивает версию Kubernetes: по умолчанию подгружается список тегов с Docker Hub (нужен интернет). Без сети или в air-gapped: KIND_K8S_SKIP_VERSION_LIST=1 в .env — ввод версии только вручную.

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

• clusters/<имя>/kind-config.yaml
• clusters/<имя>/kubeconfig
• clusters/<имя>/meta.json (в т.ч. kubeconfig_patched_for_host, created_via_container)

Содержимое clusters/*/ не коммитится (см. .gitignore), каталог clusters/ держит .gitkeep.

Документация AppsTemplate (модуль Kubernetes)

Файл docs/k8s_runbook.md в этом репозитории — runbook эксплуатации модуля Kubernetes веб-приложения (кластеры в БД, health, RBAC, observability и т.д.). Раздел §6.1 связывает локальный kind из этого каталога с импортом kubeconfig в приложение.

Ограничения

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