# 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](https://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`.

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

```bash
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: [установка](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)):

| Цель | Описание |
|------|----------|
| `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)

```bash
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).