126 lines
9.1 KiB
Markdown
126 lines
9.1 KiB
Markdown
# 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).
|