# kubectl

> Официальная утилита командной строки Kubernetes — отправляет запросы к API-серверу кластера, создаёт и изменяет объекты, показывает их состояние, логи и события.

Источник: https://llmdocs.ru/wiki/kubectl/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Тип**: CLI-клиент Kubernetes API
- **Язык**: Go
- **Лицензия**: Apache 2.0
- **Конфигурация**: ~/.kube/config (переменная KUBECONFIG)
- **Совместимость версий**: ± одна минорная версия относительно API-сервера
- **Расширения**: плагины kubectl-*, менеджер krew
- **Альтернативы и дополнения**: k9s, Lens, kubectx/kubens, stern
**kubectl** (произносят «кьюб-контрол», «кьюб-си-ти-эл» или «кубкатл») — официальная утилита командной строки [Kubernetes](https://llmdocs.ru/wiki/kubernetes.md). Всё, что она делает, — отправляет HTTP-запросы к API-серверу кластера: создаёт, читает, изменяет и удаляет объекты, а также открывает потоки логов, выполняет команды в контейнерах и пробрасывает порты.[1] Это основной инструмент администратора и разработчика: им пользуются и вручную, и в скриптах [CI/CD](https://llmdocs.ru/wiki/ci-cd.md).

## Подключение к кластеру

Куда и с какими правами ходить, kubectl узнаёт из файла **kubeconfig** — по умолчанию `~/.kube/config` или файлы из переменной `KUBECONFIG`.[3] В нём три списка:

- **clusters** — адреса API-серверов и сертификаты их центров сертификации;
- **users** — учётные данные: клиентский сертификат, токен или внешняя программа входа (например, облачный CLI);
- **contexts** — сочетания «кластер + пользователь + пространство имён по умолчанию».

```bash
kubectl config get-contexts
kubectl config use-context prod
kubectl config set-context --current --namespace=web
```

Ошибиться контекстом и выполнить команду в боевом кластере вместо тестового — классическая авария; поэтому текущий контекст выводят в приглашение оболочки, а для быстрого переключения используют утилиты kubectx и kubens.

Версия kubectl должна отличаться от версии API-сервера не больше чем на одну минорную в любую сторону.[4]

## Основные команды

Общий вид: `kubectl <глагол> <тип> [имя] [флаги]`.[2]

| Команда | Что делает |
|---|---|
| `get` | список объектов: `kubectl get pods -A -o wide` |
| `describe` | подробности и **события** — первое, что смотрят при проблемах |
| `apply -f` | создать или обновить объекты по манифестам |
| `delete` | удалить объекты |
| `logs` | логи контейнера (`-f` — следить, `--previous` — прошлый запуск) |
| `exec -it` | выполнить команду внутри контейнера |
| `port-forward` | пробросить порт пода или сервиса на локальную машину |
| `rollout` | статус, история и откат выкаток [Deployment](https://llmdocs.ru/wiki/deployment-replicaset.md) |
| `scale` | изменить число реплик |
| `top` | потребление CPU и памяти (нужен metrics-server) |
| `explain` | документация по полям объекта: `kubectl explain pod.spec.containers` |
| `debug` | временный отладочный контейнер рядом с приложением или на узле |

Флаг `-n` задаёт пространство имён, `-A` — все сразу, `-l app=web` — фильтр по меткам.

## Декларативный и императивный стиль

Объекты можно создавать командами (`kubectl create deployment web --image=nginx`, `kubectl expose`), но в рабочих проектах применяют **декларативный** подход: манифесты в YAML хранятся в Git, а `kubectl apply` приводит кластер к описанному состоянию.

```bash
kubectl apply -f k8s/                       # все манифесты каталога
kubectl diff -f k8s/                        # что изменится, до применения
kubectl apply -k overlays/prod              # с наложениями Kustomize
kubectl apply --server-side -f big-crd.yaml
```

Клиентский `apply` хранит последнюю применённую конфигурацию в аннотации объекта и вычисляет изменения у себя. **Server-side apply** (стабилен с версии 1.22) переносит слияние на сервер и отслеживает, какой «менеджер» владеет каждым полем, — это снимает конфликты, когда один объект правят несколько инструментов.[5]

Генерация заготовки без создания объекта — удобный способ не писать YAML с нуля:

```bash
kubectl create deployment web --image=nginx:1.27 --dry-run=client -o yaml > web.yaml
```

## Вывод и отладка

```bash
kubectl get pods -o yaml                               # объект целиком
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
kubectl get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName
kubectl get events --sort-by=.lastTimestamp
kubectl get pods -w                                    # следить за изменениями
kubectl auth can-i delete pods --as=system:serviceaccount:web:deployer
```

Флаг `-v=6` (до `-v=9`) показывает HTTP-запросы, которые kubectl отправляет к API, — полезно, чтобы понять, что на самом деле происходит. Типичный порядок разбора проблемного [пода](https://llmdocs.ru/wiki/pod.md): `get` → `describe` (события: нехватка ресурсов, ошибка скачивания образа) → `logs --previous` → `exec` или `debug`.

## Расширения

Любой исполняемый файл с именем `kubectl-<имя>` в `PATH` становится подкомандой `kubectl <имя>`.[6] Менеджер плагинов **krew** устанавливает их из общего каталога: `ctx`, `ns`, `neat` (очищает вывод от служебных полей), `tree` (показывает владельцев объектов). Рядом с kubectl обычно используют k9s — терминальный интерфейс для навигации по кластеру, stern — для логов сразу нескольких подов, и [Helm](https://llmdocs.ru/wiki/helm.md) — для установки готовых пакетов.

Для удобства включают автодополнение (`source <(kubectl completion zsh)`) и короткий псевдоним `alias k=kubectl`. Сокращения типов тоже работают: `po`, `svc`, `deploy`, `ns`, `cm`.

## См. также

- [Kubernetes](https://llmdocs.ru/wiki/kubernetes.md)
- [Shell и Bash](https://llmdocs.ru/wiki/shell-bash.md)
- [ConfigMap и Secret](https://llmdocs.ru/wiki/configmap-secret.md)
- [Service и Ingress](https://llmdocs.ru/wiki/service-ingress.md)

## Источники

1. [Kubernetes Docs — Command line tool (kubectl)](https://kubernetes.io/docs/reference/kubectl/)
2. [Kubernetes Docs — kubectl Quick Reference](https://kubernetes.io/docs/reference/kubectl/quick-reference/)
3. [Kubernetes Docs — Organizing Cluster Access Using kubeconfig Files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
4. [Kubernetes Docs — Version Skew Policy](https://kubernetes.io/releases/version-skew-policy/)
5. [Kubernetes Docs — Server-Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/)
6. [Kubernetes Docs — Extend kubectl with plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/)