Local Kubernetes Dev — Part 4: Setting up your workstation
Устанавливаем Docker, kubectl, k3d, helm и Tilt на macOS, Linux или Windows, проверяем всё smoke-тестом и обходим классические грабли установки.
В прошлой главе мы разобрались, кто за что отвечает: Docker собирает образы, k3d поднимает кластер, kubectl и helm управляют ресурсами, Tilt крутит быстрый цикл разработки. Теперь установим весь этот набор и убедимся, что он работает. Цель главы — чтобы к концу у вас на машине была рабочая связка, и команда kubectl get pods -A в локальном кластере отвечала без ошибок.
Дальше по тексту я буду исходить из нашего сквозного примера: сервис myapp — это HTTP API на Python 3.12 + FastAPI, слушает порт 8080, зависит от PostgreSQL. Сам сервис мы будем контейнеризировать и деплоить в следующих главах, а пока просто готовим инструменты.
Системные требования: что нужно от ноутбука
Хорошая новость: локальный кластер k3d очень лёгкий по сравнению с «настоящим» Kubernetes. Это всё-таки k3s (облегчённый дистрибутив Kubernetes), упакованный в Docker-контейнеры. Тем не менее запас по ресурсам нужен, потому что параллельно крутятся Docker, сам кластер, ваш сервис myapp и его зависимости (PostgreSQL), а сверху ещё Tilt с file-watch.
Базовое жёсткое требование одно, и оно про Docker: k3d работает поверх Docker версии 20.10.5 и новее (с runc не ниже v1.0.0-rc93). Это прямо указано в документации k3d. Всё остальное — про ресурсы хоста.
По «железу» ориентируйтесь так:
- CPU: x86-64 или Apple Silicon (M-серия) с поддержкой аппаратной виртуализации. Виртуализация (VT-x у Intel, AMD-V у AMD, нативная у Apple Silicon) обязательна — без неё Docker Desktop просто не стартует.
- RAM: 8 ГБ — комфортный минимум, 16 ГБ — чтобы вообще не думать об этом. Можно ужаться и в 4 ГБ, но это будет впритык, особенно когда вы поднимете myapp + PostgreSQL + Tilt одновременно. Кстати, Docker Desktop для Windows официально требует минимум 8 ГБ RAM, так что 8 ГБ — это не моя прихоть, а нижняя планка вендора.
- Диск: заложите 10–20 ГБ свободного места под образы Docker, слои сборки и данные кластера. Образы имеют свойство накапливаться, так что лучше с запасом.
Если вы на Windows, то ещё пара пунктов из требований Docker Desktop: нужен 64-битный процессор с поддержкой SLAT, установленный WSL 2.1.5+, и достаточно свежая ОС — Windows 10 22H2 или Windows 11 23H2 и новее.
Установка: Docker, kubectl, k3d, helm, tilt
Нам нужно пять инструментов. Логичный порядок установки — снизу вверх по стеку: сначала Docker (без него ничего не поедет), потом kubectl, k3d, helm и Tilt. Команды ниже разбиты по операционным системам.
macOS
На маке проще всего поставить почти всё через Homebrew. Docker Desktop удобнее скачать с сайта (он ставит и демон, и GUI), а остальное — одной командой:
1# Docker Desktop ставим отдельно с docker.com (или: brew install --cask docker)
2# Остальное одной командой:
3brew install kubectl helm k3d tiltTilt у Homebrew также доступен как tilt-dev/tap/tilt, но обычная формула tilt тоже работает — см. инструкцию по установке Tilt.
Linux
На Linux вместо Docker Desktop обычно ставят Docker Engine (это сам демон без GUI) — по официальной инструкции для вашего дистрибутива. После установки обязательно добавьте себя в группу docker, иначе каждая команда будет требовать sudo (об этой грабле — в разделе 4.5):
1sudo usermod -aG docker $USER
2# затем перелогиньтесь, чтобы группа примениласьkubectl на Linux ставится скачиванием бинарника с официального зеркала Kubernetes (пример для amd64; для arm64 замените путь на linux/arm64):
1# kubectl Linux (amd64)
2curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
3sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectlЭто ровно та команда, что приведена в документации kubectl для Linux. Дальше — k3d, helm и Tilt через официальные скрипты:
1# k3d
2curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
3
4# helm (актуальный установщик ведёт на Helm 4)
5curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
6chmod 700 get_helm.sh && ./get_helm.sh
7
8# tilt
9curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bashЕсли на Linux у вас есть Homebrew, всё перечисленное (кроме самого Docker Engine) ставится так же одной командой brew install kubectl helm k3d tilt.
Совет про скрипты вида curl ... | bash
Это удобно, но вы выполняете чужой код из интернета. Если хочется перестраховаться — сначала скачайте скрипт в файл, прочитайте глазами, потом запустите. Для kubectl и helm официальные доки также предлагают пакетные менеджеры (apt, dnf, snap), что чище для долгой поддержки.
Windows + WSL2
Тут принципиальный момент, который экономит часы нервов. Всю dev-работу делайте внутри WSL2 (например, в дистрибутиве Ubuntu): там же держите репозиторий с myapp, оттуда запускайте k3d, kubectl, helm и Tilt. Файловая система внутри WSL2 работает почти с нативной скоростью, а вот исходники, лежащие в Windows-файловой системе (C:\...) и читаемые из WSL2, тормозят и ломают file-sync у Tilt. Подробнее об этой грабле — в 4.5.
Схема такая:
- Поставьте Docker Desktop для Windows с включённым WSL2-бэкендом. Демон Docker будет жить внутри WSL2, а CLI
dockerдоступен и из PowerShell, и из дистрибутива WSL2. - Дальше заходите в свой WSL2-дистрибутив (Ubuntu) и ставите там kubectl, k3d, helm, tilt ровно как на Linux (см. команды выше). Это рекомендуемый путь.
Альтернатива — ставить инструменты в сам Windows через пакетные менеджеры Chocolatey или Scoop, но к этому стоит прибегать, только если вы осознанно работаете не из WSL2:
1# Chocolatey
2choco install k3d kubernetes-helm k9s
3
4# Scoop (для Tilt сначала добавьте bucket)
5scoop bucket add tilt-dev https://github.com/tilt-dev/scoop-bucket
6scoop install k3d helm k9s tiltTilt на Windows также ставится PowerShell-скриптом:
1iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.ps1'))Помните, что Tilt по своей документации требует уже установленных Docker, kubectl и работающего локального кластера — то есть Tilt ставим последним.
Опционально, но удобно: k9s
k9s — это терминальный UI для Kubernetes. Вместо того чтобы постоянно набирать kubectl get pods, kubectl describe, kubectl logs, вы открываете k9s и навигируете по кластеру стрелками: видите поды, заходите в логи, перезапускаете, удаляете — всё в одном интерактивном экране. Для новичка это отличная визуальная замена десяткам однообразных kubectl-команд, поэтому я очень рекомендую поставить.
1# macOS / Linux (Homebrew)
2brew install derailed/k9s/k9s
3
4# Windows
5winget install k9s # либо scoop install k9s / choco install k9sЕсть и другие способы — MacPorts, snap, pacman, dnf (Fedora 42+), webi, go install, расширение для Docker Desktop — все они перечислены в репозитории k9s. По части совместимости: k9s предпочитает Kubernetes 1.28+, читает ваш kubeconfig и требует прав на чтение (read-RBAC) в кластере — для нашего локального k3d это не проблема, прав там у вас будет с избытком. Если хотите 256 цветов в терминале, выставьте TERM=xterm-256color.
Проверка установки
После установки прогоните version-команды — это убедит, что бинарники на месте и в PATH:
1docker version # клиент И демон; если демон не отвечает — Docker не запущен
2kubectl version --client
3k3d version
4helm version
5tilt version
6k9s versiondocker version показывает версии и клиента, и демона. Если в выводе про демон ошибка соединения — значит Docker не запущен (как это лечить, см. 4.5). kubectl version --client — это команда прямо из документации kubectl; флаг --client нужен, чтобы kubectl не пытался достучаться до кластера, которого пока нет. Для helm, помимо helm version, официальные доки предлагают helm help как простую проверку, что клиент доступен.
А теперь главное — smoke-тест, то есть проверка, что вся связка реально работает вместе. Создадим временный кластер, переключимся на него, посмотрим поды и удалим:
1# Создаём кластер с именем dev
2k3d cluster create dev
3
4# Прописываем его в kubeconfig и делаем текущим контекстом
5k3d kubeconfig merge dev --kubeconfig-switch-context
6
7# Должны увидеть системные поды k3s (coredns, traefik, metrics-server и т.п.)
8kubectl get pods -A
9
10# Убираем за собой
11k3d cluster delete devЕсли kubectl get pods -A показал список системных подов в статусе Running — поздравляю, рабочее место готово. Имя кластера dev мы используем не случайно: в следующей главе мы поднимем уже «настоящий» dev-кластер для myapp (с registry и пробросом портов) под тем же именем. Эта же последовательность команд взята из quick-start k3d.
Типичные проблемы установки и как их обойти
Почти все грабли на этом этапе сводятся к нескольким классическим ситуациям. Пробегитесь по списку — скорее всего, ваша проблема здесь.
Docker-демон не запущен. Самая частая. k3d и Tilt не умеют работать без Docker и падают с connection refused или похожим. Лечится просто: запустите Docker Desktop (на маке/Windows) или sudo systemctl start docker (на Linux) и дождитесь, пока демон полностью поднимется. Иногда после перезагрузки бывает port already in use — тогда пересоздайте кластер (k3d cluster delete dev && k3d cluster create dev).
too many open files. Это, пожалуй, самый коварный класс проблем, и связан он с file-watch: поды и сам Tilt следят за изменениями файлов, упираясь в системные лимиты на дескрипторы и inotify. Симптом — ошибки too many open files в логах подов или kubelet. Решение на Linux/Docker-хосте — поднять лимиты inotify и перезапустить Docker:
1sudo sysctl fs.inotify.max_user_watches=1048576
2sudo sysctl fs.inotify.max_user_instances=8192
3# и при необходимости поднять лимит дескрипторов: ulimit -nЧтобы изменения пережили перезагрузку, пропишите их в /etc/sysctl.conf (или файл в /etc/sysctl.d/). Эта проблема и её обходы подробно разобраны в k3d issue #803; как запасной вариант там же советуют создавать k3d-кластер без agent-нод (только server-нода), что снижает суммарное число открытых файлов.
Устаревший Docker Desktop на macOS. Исторически некоторые старые версии Docker Desktop (в районе 4.3–4.4) ломали k3d, и лечилось это обновлением. Мораль простая: держите Docker Desktop свежим, особенно если k3d вдруг перестал создавать кластеры после, казалось бы, ничего не менявшего обновления системы.
Linux: permission denied к docker.sock. Если каждая docker-команда требует sudo или ругается на доступ к сокету — вы не в группе docker. Добавьтесь (sudo usermod -aG docker $USER) и перелогиньтесь. Это безопасно для локальной разработки.
Windows: исходники в Windows-FS вместо WSL2. Если репозиторий с myapp лежит в C:\..., а инструменты вы запускаете из WSL2 — будет медленная файловая система и битый file-sync у Tilt (горячая перезагрузка uvicorn --reload может просто не срабатывать). Перенесите репозиторий внутрь WSL2-дистрибутива (в его домашнюю директорию) и работайте оттуда.
Выключенная виртуализация в BIOS/UEFI. Если Docker Desktop отказывается стартовать с жалобой на виртуализацию — зайдите в BIOS/UEFI и включите аппаратную виртуализацию (VT-x / AMD-V; для WSL2 на некоторых машинах ещё и SLAT). Без неё ни Docker Desktop, ни, соответственно, k3d работать не будут.
Слишком мало RAM. 4 ГБ — это впритык, и при добавлении PostgreSQL и нескольких подов к myapp вы начнёте упираться в OOM. Если есть возможность, выделяйте Docker 8 ГБ и больше (в Docker Desktop это настраивается в Settings → Resources).
На этом подготовка закончена: инструменты установлены, версии проверены, smoke-тест прошёл. В следующей главе мы поднимем настоящий локальный кластер на k3d — уже с встроенным registry k3d-registry.localhost:5000 и пробросом портов, чтобы было куда деплоить наш myapp.