kubectl

kubectl управляет кластером Kubernetes: отправляет манифесты (YAML-описания объектов) в API-сервер и показывает, что в кластере происходит. Часть команд работает без кластера — например, генерация заготовок манифестов.

В песочнице кластера нет. Работают только клиентские операции: kubectl create … --dry-run=client -o yaml (кроме create role/clusterrole), kubectl label/annotate/set с --local, kubectl kustomize, kubectl config, kubectl version --client. Команды apply, get, describe, run, expose, autoscale, explain, diff обращаются к серверу и завершатся ошибкой connection refused.

Синтаксис

kubectl <действие> <тип> [имя] [флаги]

Типы пишут полностью или сокращённо: pods/po, deployments/deploy, services/svc, configmaps/cm, namespaces/ns, nodes/no.

Генераторы kubectl create

С --dry-run=client -o yaml каждый из них печатает готовый манифест.

Команда	Что создаёт
create deployment имя --image=образ	Deployment; --replicas=3, --port=80, --image можно повторять (несколько контейнеров)
create service clusterip имя --tcp=80:8080	Service внутри кластера: порт сервиса 80 → порт контейнера 8080
create service nodeport имя --tcp=80:8080 --node-port=30080	Service с портом на каждом узле
create service loadbalancer имя --tcp=80:8080	Service с внешним балансировщиком
create service externalname имя --external-name=host	DNS-псевдоним на внешний хост
create configmap имя --from-literal=K=V	ConfigMap; --from-file=[ключ=]путь, --from-env-file=файл
create secret generic имя --from-literal=K=V	Secret; те же --from-file, --from-env-file
create secret tls имя --cert=crt --key=key	Secret с TLS-сертификатом
create secret docker-registry имя --docker-server=… --docker-username=… --docker-password=…	доступ к приватному реестру образов
create namespace имя	Namespace
create job имя --image=образ -- команда	Job (одноразовая задача)
create cronjob имя --image=образ --schedule='0 3 * * *' -- команда	CronJob (задача по расписанию)
create serviceaccount имя	ServiceAccount
create rolebinding имя --role=роль --serviceaccount=ns:имя	привязка роли (также --user, --group)
create clusterrolebinding имя --clusterrole=роль --user=имя	привязка роли на весь кластер
create ingress имя --rule='host/путь*=сервис:порт'	Ingress (HTTP-маршрутизация)
create poddisruptionbudget имя --selector=app=web --min-available=1	PodDisruptionBudget
create quota имя --hard=pods=10,requests.cpu=2	ResourceQuota
create priorityclass имя --value=1000	PriorityClass

Правка манифестов без кластера

Команда	Что делает
label -f файл ключ=значение --local -o yaml	добавить метку
annotate -f файл ключ=значение --local -o yaml	добавить аннотацию
set image -f файл контейнер=образ --local -o yaml	сменить образ
set env -f файл KEY=value --local -o yaml	добавить переменную окружения
set resources -f файл --limits=cpu=200m,memory=128Mi --local -o yaml	задать ресурсы
kustomize каталог	собрать манифесты по kustomization.yaml

Работа с кластером

Команда	Что делает
apply -f файл.yaml / -f каталог/ / -k каталог/	создать или обновить объекты по манифестам
delete -f файл.yaml / delete pod имя	удалить
get pods / get all / get deploy,svc	список объектов
get pod имя -o yaml / -o wide / -o jsonpath='{…}'	полное описание / с узлом и IP / одно поле
describe pod имя	подробности и события — первое, куда смотреть при проблемах
logs pod [-c контейнер] [-f] [--previous]	логи контейнера (предыдущего запуска — --previous)
exec -it pod -- sh	оболочка внутри контейнера
port-forward svc/имя 8080:80	проброс порта на свою машину
rollout status/history/undo deploy/имя	ход выкатки / история / откат
scale deploy/имя --replicas=3	изменить число реплик
explain deployment.spec	документация по полям объекта
config get-contexts / use-context имя	список кластеров-контекстов / переключение

Общие флаги

Флаг	Что делает
--dry-run=client	ничего не отправлять в кластер
-o yaml / -o json / -o name	формат вывода
-n имя / -A	неймспейс / все неймспейсы
-l app=web / -l 'tier in (front,back)' / -l '!canary'	отбор по меткам (label selector)
-f файл	работать с объектами из манифеста
-w	следить за изменениями (get -w)

Примеры

# заготовка Deployment в файл
kubectl create deployment web --image=nginx:1.27 --replicas=2 \
  --dry-run=client -o yaml > deployment.yaml

# Service к нему: селектор app=web совпадает с меткой подов
kubectl create service clusterip web --tcp=80:8080 --dry-run=client -o yaml

# объект сразу в нужном неймспейсе — в манифесте появится metadata.namespace
kubectl create deployment web --image=nginx -n staging --dry-run=client -o yaml

# ConfigMap и Secret
kubectl create configmap app-cfg --from-literal=MODE=prod --from-file=app.conf \
  --dry-run=client -o yaml
kubectl create secret generic db --from-literal=password=changeme --dry-run=client -o yaml

# Job и CronJob: команда контейнера — после --
kubectl create cronjob nightly --image=busybox --schedule='0 3 * * *' \
  --dry-run=client -o yaml -- date

# несколько объектов в одном файле: документы YAML разделяются строкой ---
{
  kubectl create deployment web --image=nginx --dry-run=client -o yaml
  echo '---'
  kubectl create service clusterip web --tcp=80:80 --dry-run=client -o yaml
} > app.yaml

# добавить метку и переменную окружения в готовый манифест без кластера
kubectl label -f deployment.yaml tier=frontend --local -o yaml
kubectl set env -f deployment.yaml MODE=prod --local -o yaml

# одно поле из сгенерированного объекта
kubectl create deployment web --image=nginx --dry-run=client \
  -o jsonpath='{.spec.selector.matchLabels}'

# прочитать значение из Secret
kubectl create secret generic db --from-literal=password=changeme --dry-run=client \
  -o jsonpath='{.data.password}' | base64 -d

# в реальном кластере (здесь не сработают):
# kubectl apply -f deployment.yaml
# kubectl get pods -n staging -l app=web
# kubectl describe deployment web
# kubectl logs deploy/web --tail=50

Как связаны Deployment и Service — через метки:

# Deployment: поды получают метку app: web
spec:
  selector:
    matchLabels:
      app: web          # какими подами управляет Deployment
  template:
    metadata:
      labels:
        app: web        # должна совпадать с matchLabels
---
# Service: трафик идёт на поды с той же меткой
spec:
  selector:
    app: web

Подводные камни

• --dry-run=client без -o yaml печатает только deployment.apps/web created (dry run). Манифест виден только с -o yaml.
• apply --dry-run=client всё равно ходит в кластер: ему нужна схема API. Без кластера сгенерированный манифест не «проверить через apply».
• kubectl run и create role тоже обращаются к серверу даже с --dry-run=client. Под и Role придётся описывать вручную или взять за основу другой генератор.
• Метки и селекторы должны совпадать. Service находит поды по spec.selector, Deployment — по spec.selector.matchLabels. Опечатка в метке не даёт ошибки: сервис просто останется без подов.
• selector у Deployment нельзя поменять после создания — только пересоздать объект.
• Secret — это не шифрование. Значения в data лишь закодированы base64 и читаются через base64 -d.
• В сгенерированном YAML есть шум: creationTimestamp: null, status: {}, resources: {}. Это нормально, при желании удаляй.
• Неймспейс по умолчанию — default. Без -n команды в кластере смотрят туда, и «пропавшие» объекты часто лежат в другом неймспейсе.
• Всё после -- уходит в контейнер как команда. Флаги kubectl пиши до --.

См. также

yq · base64 · docker-compose · ansible