kubectl: справочник команд

kubectl — CLI для Kubernetes: отправляет HTTP-запросы к API Server, читает ~/.kube/config. Эта глава — справочник по командам, которые используются ежедневно.

[source: kubernetes.io/docs/reference/kubectl/]

Информация о кластере

# Версия клиента и сервера
kubectl version

# Информация о кластере
kubectl cluster-info

# Список узлов
kubectl get nodes
kubectl get nodes -o wide          # IP, OS, версия container runtime

# Все доступные типы ресурсов
kubectl api-resources
kubectl api-resources --namespaced=true   # только namespaced
kubectl api-resources --namespaced=false  # только cluster-scoped

# Доступные API-версии
kubectl api-versions

Pod

# Создание
kubectl run nginx --image=nginx:1.27
kubectl run nginx --image=nginx:1.27 --dry-run=client -o yaml > pod.yaml
kubectl apply -f pod.yaml

# Просмотр
kubectl get pods
kubectl get pods -o wide              # IP, узел, статус
kubectl get pods -o yaml              # полный манифест
kubectl get pods --show-labels
kubectl get pods -w                   # watch — следить за изменениями в реальном времени
kubectl get pods -A                   # во всех namespace

# Детали и события
kubectl describe pod nginx

# Логи
kubectl logs nginx
kubectl logs nginx -c sidecar         # конкретный контейнер в multi-container Pod
kubectl logs nginx -f                 # follow (потоковый вывод)
kubectl logs nginx --previous         # логи предыдущего контейнера (после OOMKilled/CrashLoop)
kubectl logs nginx --tail=100         # последние 100 строк
kubectl logs nginx --since=1h         # за последний час

# Выполнение команд
kubectl exec nginx -- ls /etc
kubectl exec -ti nginx -- /bin/sh
kubectl exec -ti nginx -c sidecar -- /bin/bash  # конкретный контейнер

# Проброс порта
kubectl port-forward nginx 8080:80
kubectl port-forward svc/my-service 8080:80

# Удаление
kubectl delete pod nginx
kubectl delete pod nginx --grace-period=0 --force   # немедленное удаление
kubectl delete -f pod.yaml

Deployment

# Создание
kubectl create deployment nginx --image=nginx:1.27 --replicas=3
kubectl apply -f deployment.yaml

# Просмотр
kubectl get deployments
kubectl get deploy
kubectl describe deployment nginx

# Масштабирование
kubectl scale deployment nginx --replicas=5
kubectl autoscale deployment nginx --min=2 --max=10 --cpu-percent=70

# Обновление образа
kubectl set image deployment/nginx nginx=nginx:1.28

# Rollout управление
kubectl rollout status deployment/nginx
kubectl rollout history deployment/nginx
kubectl rollout history deployment/nginx --revision=2
kubectl rollout undo deployment/nginx
kubectl rollout undo deployment/nginx --to-revision=1
kubectl rollout pause deployment/nginx
kubectl rollout resume deployment/nginx
kubectl rollout restart deployment/nginx      # rolling restart без изменения образа

# Аннотация ревизии (вместо устаревшего --record)
kubectl annotate deployment nginx kubernetes.io/change-cause="update image to 1.28"

Service

# Создание
kubectl expose deployment nginx --port=80 --target-port=8080 --type=ClusterIP
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl apply -f service.yaml

# Просмотр
kubectl get services
kubectl get svc
kubectl get svc -o wide
kubectl describe svc my-service

# EndpointSlice (stable с 1.21; Endpoints deprecated с 1.33, но всё ещё доступен)
kubectl get endpointslices -l kubernetes.io/service-name=my-service
kubectl get endpoints my-service        # legacy Endpoints
kubectl get ep my-service

ConfigMap

# Создание
kubectl create configmap app-config --from-literal=KEY=value
kubectl create configmap app-config --from-file=config.properties
kubectl create configmap app-config --from-env-file=.env
kubectl apply -f configmap.yaml

# Просмотр
kubectl get configmaps
kubectl get cm
kubectl describe configmap app-config
kubectl get configmap app-config -o yaml

Secret

# Создание
kubectl create secret generic db-creds \
  --from-literal=user=admin \
  --from-literal=pass=secret

kubectl create secret tls my-tls --cert=tls.crt --key=tls.key

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass

# Просмотр
kubectl get secrets
kubectl describe secret db-creds
kubectl get secret db-creds -o yaml

# Декодирование значения
kubectl get secret db-creds -o jsonpath='{.data.user}' | base64 -d

Namespace

kubectl get namespaces
kubectl get ns
kubectl create namespace dev
kubectl delete namespace dev

# Ресурсы в namespace
kubectl get pods -n kube-system
kubectl get all -n dev
kubectl get pods -A                    # все namespace

Labels и Selectors

# Фильтрация
kubectl get pods -l app=nginx
kubectl get pods -l "app=nginx,environment=production"
kubectl get pods -l "environment in (production,staging)"
kubectl get pods -l "app!=test"
kubectl get pods -l "release"          # label существует
kubectl get pods -l "!canary"          # label не существует

# Управление labels
kubectl label pod nginx tier=frontend
kubectl label pod nginx tier=backend --overwrite
kubectl label pod nginx tier-          # удалить label

# Отображение
kubectl get pods --show-labels
kubectl get pods -L app,environment    # конкретные labels как столбцы

StatefulSet, DaemonSet, Job, CronJob

# StatefulSet
kubectl get statefulsets
kubectl get sts
kubectl describe sts postgres
kubectl scale sts postgres --replicas=5

# DaemonSet
kubectl get daemonsets
kubectl get ds
kubectl describe ds fluentd

# Job
kubectl get jobs
kubectl describe job migration
kubectl logs job/migration

# CronJob
kubectl get cronjobs
kubectl get cj
kubectl describe cronjob db-backup
kubectl create job manual-run --from=cronjob/backup
kubectl patch cronjob db-backup -p '{"spec":{"suspend":true}}'

PersistentVolume и PVC

kubectl get pv
kubectl get pvc
kubectl get pvc -n dev
kubectl describe pvc my-claim
kubectl describe pv my-volume

Форматирование вывода

# Форматы
kubectl get pods -o wide               # расширенный (IP, узел)
kubectl get pods -o yaml               # полный YAML
kubectl get pods -o json               # полный JSON
kubectl get pods -o name               # только имена (resource/name)

# JSONPath — извлечь конкретные поля
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
kubectl get nodes -o jsonpath='{.items[*].status.addresses[0].address}'
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

# Custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName

# Сортировка
kubectl get pods --sort-by=.metadata.creationTimestamp
kubectl get pods --sort-by=.status.startTime
kubectl get events --sort-by=.metadata.creationTimestamp

Контекст и конфигурация

# Текущая конфигурация
kubectl config view
kubectl config view --minify           # только текущий контекст

# Контексты
kubectl config current-context
kubectl config get-contexts
kubectl config use-context my-context

# Установка namespace по умолчанию
kubectl config set-context --current --namespace=dev

# Создание нового контекста
kubectl config set-context dev-context \
  --cluster=my-cluster \
  --user=my-user \
  --namespace=dev

Отладка

# Детали объекта (Events в конце — ключевая информация)
kubectl describe pod nginx
kubectl describe node node1
kubectl describe deployment nginx

# Логи предыдущего контейнера
kubectl logs nginx --previous

# Интерактивный шелл
kubectl exec -ti nginx -- /bin/sh

# События кластера
kubectl get events
kubectl get events --sort-by=.metadata.creationTimestamp
kubectl get events -n kube-system
kubectl get events --field-selector reason=BackOff

# Отладочные Pod
kubectl run debug --image=busybox:1.36 -ti --rm -- /bin/sh
kubectl run debug --image=nicolaka/netshoot -ti --rm -- /bin/bash

# Ephemeral debug container (K8s 1.23+, GA в 1.25)
kubectl debug -it nginx --image=busybox:1.36 --target=nginx

# Ресурсы узлов и Pod
kubectl top nodes
kubectl top pods
kubectl top pods --containers          # потребление по контейнерам
kubectl top pods -n production

# Проверка манифеста без применения
kubectl apply -f manifest.yaml --dry-run=client   # валидация на клиенте
kubectl apply -f manifest.yaml --dry-run=server   # валидация на API Server
kubectl diff -f manifest.yaml                      # diff с текущим состоянием

Применение и управление ресурсами

# Применить манифест
kubectl apply -f manifest.yaml
kubectl apply -f ./directory/            # все файлы в директории
kubectl apply -f https://example.com/manifest.yaml

# Создать из манифеста (ошибка если уже существует)
kubectl create -f manifest.yaml

# Удалить
kubectl delete -f manifest.yaml
kubectl delete pod nginx
kubectl delete pods --all -n dev         # все Pod в namespace

# Редактировать в редакторе
kubectl edit deployment nginx

# Патч (JSON Merge Patch)
kubectl patch deployment nginx -p '{"spec":{"replicas":5}}'

# Аннотации
kubectl annotate pod nginx description="my pod" --overwrite

# Taint узла
kubectl taint nodes node1 key=value:NoSchedule
kubectl taint nodes node1 key=value:NoSchedule-   # удалить taint

Полезные флаги

Алиасы и продуктивность

# Короткие имена ресурсов (built-in)
kubectl get po          # pods
kubectl get deploy      # deployments
kubectl get svc         # services
kubectl get ns          # namespaces
kubectl get cm          # configmaps
kubectl get sts         # statefulsets
kubectl get ds          # daemonsets
kubectl get cj          # cronjobs
kubectl get rs          # replicasets
kubectl get ep          # endpoints
kubectl get pv          # persistentvolumes
kubectl get pvc         # persistentvolumeclaims
kubectl get sa          # serviceaccounts
kubectl get ing         # ingresses

# Полезные bash алиасы
alias k='kubectl'
alias kgp='kubectl get pods'
alias kgs='kubectl get svc'
alias kgd='kubectl get deploy'
alias kdp='kubectl describe pod'
alias kl='kubectl logs'
alias ke='kubectl exec -ti'

# kubectx / kubens (отдельные утилиты)
kubectx                 # список контекстов
kubectx my-cluster      # переключить контекст
kubens dev              # переключить namespace

Когда использовать

apply vs create — apply идемпотентен, create падает если объект существует. В GitOps/CI всегда apply.

--dry-run=server vs --dry-run=client — client только синтаксис YAML; server учитывает admission webhooks. Для CI — --dry-run=server.

kubectl diff — смотри изменения перед применением, особенно для StatefulSet и PVC.

Типичные ошибки

kubectl edit в production. edit меняет кластер минуя GitOps; следующий apply перезатрёт. Все изменения — через git.

kubectl delete namespace без проверки. Удаляет ВСЕ объекты, включая PVC с данными. Проверь содержимое перед удалением.

Игнорировать Events в describe. OOMKilled, ImagePullBackOff, FailedScheduling — всё там. Смотри Events при любых проблемах.

Не использовать --previous для логов. После CrashLoopBackOff текущий контейнер только запустился. --previous покажет логи упавшего.

Port-forward к Pod напрямую. kubectl port-forward svc/nginx 8080:80 — через Service, независимо от имени Pod.

Альтернативы kubectl

k9s — TUI для Kubernetes: навигация, логи, edit без команд.

Lens (OpenLens) — GUI-клиент с визуализацией ресурсов, логами, метриками, встроенным terminal.

kubectx + kubens — переключение контекстов и namespace одной командой.

Helm — пакетный менеджер: charts с versioning и parametrization.

← 13: Resource Management

15: RBAC →