kubectl и kubeconfig: подключаемся к кластеру

kubectl — это клиент к Kubernetes API. Он умеет ровно одно: собрать HTTP-запрос к apiserver, отправить его и показать ответ. Кластер он не создаёт и не поднимает.

Разница видна сразу: kind create cluster создаёт кластер, kubectl get nodes только спрашивает у уже существующего кластера, какие у него ноды. Если кластера нет, kubectl честно скажет, что не смог соединиться.

Некоторые инструменты приносят клиент с собой. minikube умеет minikube kubectl -- get po -A, MicroK8s вызывается как microk8s kubectl get nodes, k0s как sudo k0s kubectl get nodes. Отдельный kubectl всё равно удобнее: он один на все кластеры и не зависит от того, чем ты сегодня поднял песочницу.

Установка

macOS:

brew install kubectl

Или бинарём напрямую:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

Linux, бинарь с проверкой контрольной суммы. Второй curl качает sha256-файл рядом с бинарём, sha256sum --check сверяет:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Проверку суммы пропускать не стоит. Бинарь ставится в системный путь и запускается с правами, которые дают доступ к кластеру, так что убедиться в целостности файла дешевле, чем потом разбираться.

Linux через apt. Обрати внимание на v1.37 в обоих URL: репозиторий разбит по минорным веткам, и для другой версии строку правят руками.

sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.37/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.37/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update && sudo apt-get install -y kubectl

Windows:

winget install Kubernetes.kubectl
choco install kubernetes-cli

Какую версию ставить

Последняя стабильная версия Kubernetes на сентябрь 2026 — v1.37.0, релиз 2026-08-26. Узнать её всегда можно у самого проекта:

curl -L https://dl.k8s.io/release/stable.txt

Одновременно в поддержке три минорные ветки:

Ветка 1.34 уже вышла из поддержки, последний патч v1.34.11 датирован 2026-08-20. Окно патчей примерно 12 месяцев на ветку.

Уводить клиент далеко от кластера нельзя. Политика version skew разрешает kubectl отличаться от apiserver не больше чем на одну минорную версию в любую сторону: при кластере 1.37 подходят клиенты 1.36, 1.37 и 1.38. За пределами этого окна поведение не гарантируется, потому что клиент строит запросы по схеме API, которую он знает, а кластер за несколько релизов успевает поля добавить и убрать.

Проблема становится реальной, когда кластеров несколько. Локальный kind даёт 1.37.0, рабочий кластер может быть на 1.35. Один клиент 1.36 попадает в окно обоих. Клиент 1.38 в окно 1.35 уже не попадёт.

Две команды, с которых начинается любая проверка:

kubectl version        # версия клиента и версия кластера
kubectl cluster-info   # адреса control plane текущего контекста

kubectl version показывает обе версии сразу, так что расхождение видно без арифметики. kubectl cluster-info заодно отвечает на вопрос «а к какому кластеру я вообще подключён».

kubeconfig

Адреса кластеров, сертификаты и токены kubectl берёт из файла kubeconfig. По умолчанию это ~/.kube/config.

Путь переопределяется переменной $KUBECONFIG. Так, например, поступают с k3s, который кладёт свой конфиг в системный каталог:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

В переменную можно положить несколько файлов через двоеточие, и kubectl склеит их в одну картину. Это удобно, когда учебный кластер и рабочий живут в разных файлах.

Внутри kubeconfig лежат три вида записей: кластеры (адрес и CA), пользователи (сертификат или токен) и контексты. Контекст — это именованная связка «кластер + пользователь + namespace по умолчанию». В любой момент активен ровно один контекст, и именно он определяет, куда уйдёт следующая команда.

kubeconfig
 ├─ clusters   адрес apiserver + CA
 ├─ users      сертификат или токен
 └─ contexts   кластер + пользователь + ns

Имена контекстов обычно назначает инструмент. kind даёт kind-<имя>, Docker Desktop — docker-desktop.

kubectl config get-contexts        # список, звёздочка у активного
kubectl config current-context     # только имя активного
kubectl config use-context kind-lab

У контекста есть namespace по умолчанию. Если его не задать, каждая команда будет ходить в default, и -n demo придётся дописывать вручную. Прибить namespace к контексту можно один раз:

kubectl config set-context --current --namespace=demo

Локальные инструменты правят твой kubeconfig

Почти каждый локальный кластер при создании дописывает себя в kubeconfig и переключает активный контекст на себя. Обычно это удобно. Иногда это стреляет.

Живой пример: colima мержит свой контекст в первый файл из списка $KUBECONFIG (issue #1627). Если первым в списке стоит рабочий конфиг с продовым кластером, colima запишет учебный контекст прямо туда и заодно сделает его активным.

Отсюда простое правило. Учебный kubeconfig держат отдельным файлом и подсовывают его явно:

export KUBECONFIG=~/.kube/lab.yaml

Прод в такой сессии просто недоступен, и опечатка в имени namespace максимум сломает песочницу. Перед любой командой, которая что-то меняет, привычка одна: сначала kubectl config current-context, потом всё остальное.

Чем смотреть кластер

Голого kubectl хватает надолго, но пара инструментов экономит время.

k9s v0.51.0 (2026-06-06) — терминальный интерфейс к кластеру: списки объектов обновляются сами, логи и describe открываются одной клавишей. Ставится через brew install derailed/k9s/k9s, scoop install k9s, choco install k9s или pacman -S k9s. Полезно заранее выставить TERM=xterm-256color и KUBE_EDITOR.

kubectx и kubens v0.11.0 (2026-03-27) из репозитория ahmetb/kubectx сокращают возню с контекстами: kubectx переключает контекст, kubens меняет namespace. Ставятся через brew install kubectx, sudo apt install kubectx или как плагины kubectl krew install ctx ns.

С графическими дашбордами ситуация мутнее, чем принято думать:

• Lens Desktop — закрытый исходник и freemium. Бесплатный Personal требует регистрации Lens ID и персонального ключа.
• OpenLens мёртв. Последний релиз v6.5.2 вышел в июне 2023, репозиторий свёрнут в январе 2024. Советы «поставь OpenLens» из старых статей уже неактуальны.
• FreeLens v1.10.3 (2026-07-07) — живой форк под Linux, Windows и macOS. Проект описывает себя как MIT, файл лицензии здесь не проверялся.
• Из альтернатив живы Headlamp под крылом CNCF и YAKD.

Коротко

• kubectl только разговаривает с apiserver. Кластер поднимает kind, k3d, minikube или k3s, а не клиент.
• Ставь через пакетный менеджер или бинарём с dl.k8s.io; для бинаря на Linux сверяй sha256 перед установкой.
• Текущая стабильная версия v1.37.0, в поддержке ветки 1.37, 1.36 и 1.35. kubectl держат в пределах одной минорной версии от apiserver.
• kubeconfig лежит в ~/.kube/config и переопределяется $KUBECONFIG. Контекст — это связка кластера, пользователя и namespace; активный смотрят через kubectl config current-context.
• Локальные инструменты пишут в твой kubeconfig сами (colima пишет в первый файл из $KUBECONFIG), поэтому учебный конфиг держат отдельным файлом.
• k9s и kubectx/kubens экономят время; из дашбордов OpenLens мёртв, а живы FreeLens, Headlamp и Lens с обязательным Lens ID.