first commit

2026-04-04 05:15:54 +03:00
commit ae961ef5fe
25 changed files with 2022 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,125 @@
+# 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).