Kubectl команды: шпаргалка для управления Kubernetes

Введение / Зачем это нужно

Kubectl — это основная командная строка для управления Kubernetes кластерами. Эта шпаргалка собрала самые востребованные команды для ежедневных задач: работа с подами, развертываниями, сервисами, конфигами и секретами. После изучения вы сможете быстро выполнять стандартные операции без постоянного поиска в документации.

Требования / Подготовка

• Установленный kubectl (рекомендуется версия 1.20 и выше)
• Доступный Kubernetes кластер и настроенный kubeconfig файл
• Базовое понимание ресурсов Kubernetes (поды, развертывания, сервисы и т.д.)

Шаг 1: Настройка подключения к кластеру

Перед началом работы убедитесь, что kubectl настроен для подключения к нужному кластеру.

Проверка текущей конфигурации:

kubectl config view

Просмотр доступных контекстов:

kubectl config get-contexts

Переключение на другой контекст:

kubectl config use-context <имя-контекста>

Проверка подключения к кластеру:

kubectl cluster-info

Если команда возвращает информацию о кластере, подключение установлено.

Шаг 2: Управление подами

Поды — это минимальные единицы развертывания в Kubernetes.

Создание пода из YAML-манифеста:

kubectl apply -f pod.yaml

Просмотр подов в текущем неймспейсе:

kubectl get pods

Просмотр подов во всех неймспейсах:

kubectl get pods --all-namespaces

Подробная информация о поде:

kubectl describe pod <имя-пода>

Удаление пода:

kubectl delete pod <имя-пода>

Запуск интерактивной оболочки в контейнере пода:

kubectl exec -it <имя-пода> -- /bin/bash
# Для контейнера по умолчанию. Если в поде несколько контейнеров, укажите -c <имя-контейнера>

Просмотр логов пода:

kubectl logs <имя-пода>
# Для многоконтейнерного пода: kubectl logs <имя-пода> -c <имя-контейнера>

Шаг 3: Управление развертываниями и сервисами

Развертывания (Deployment) управляют подами, обеспечивая обновление и масштабирование. Сервисы (Service) предоставляют сетевой доступ к подам.

Создание развертывания:

kubectl create deployment <имя-развертывания> --image=<образ-контейнера>

Просмотр развертываний:

kubectl get deployments

Масштабирование развертывания:

kubectl scale deployment <имя-развертывания> --replicas=3

Обновление образа контейнера в развертывании:

kubectl set image deployment/<имя-развертывания> <имя-контейнера>=<новый-образ>

Создание сервиса для развертывания (тип NodePort):

kubectl expose deployment <имя-развертывания> --type=NodePort --port=80

Просмотр сервисов:

kubectl get services

Шаг 4: Работа с конфигами и секретами

ConfigMap и Secret позволяют передавать конфигурацию и конфиденциальные данные в поды.

Создание ConfigMap из литерала:

kubectl create configmap <имя-configmap> --from-literal=key=value

Создание ConfigMap из файла:

kubectl create configmap <имя-configmap> --from-file=путь/к/файлу

Просмотр ConfigMap:

kubectl get configmap <имя-configmap> -o yaml

Создание Secret (тип generic):

kubectl create secret generic <имя-secret> --from-literal=username=admin --from-literal=password='s3cr3t'

Просмотр Secret:

kubectl get secret <имя-secret> -o yaml

Шаг 5: Мониторинг и отладка

Команды для диагностики проблем.

Просмотр событий (с сортировкой по времени):

kubectl get events --sort-by='.lastTimestamp'

Запуск временного пода для отладки (например, с образом busybox):

kubectl run debug --rm -i --tty --image=busybox -- /bin/sh
# Пода будет удален после выхода (флаг --rm)

Просмотр использования ресурсов (требуется metrics-server):

kubectl top pods
kubectl top nodes

Проверка логов системных компонентов (если есть доступ):

kubectl logs -n kube-system <имя-пода-компонента>

Проверка результата

Эта шпаргалка не требует проверки результата в традиционном смысле. Убедитесь, что все перечисленные команды выполняются без ошибок на вашем кластере. Для тренировки создайте тестовые ресурсы в отдельном неймспейсе.

Возможные проблемы

Ошибки аутентификации/авторизации:

• "Unauthorized" или "Forbidden": проверьте kubeconfig и права RBAC.

Ресурс не найден:

• Убедитесь, что ресурс существует и вы указали правильное имя и неймспейс. Используйте kubectl get <resource> --all-namespaces для поиска.

Под в состоянии Pending:

• Недостаточно ресурсов на нодах, или нет подходящих нод из-за taints/tolerations или nodeSelector. Проверьте события: kubectl describe pod <pod-name>.

Под в состоянии CrashLoopBackOff:

• Приложение внутри контейнера падает. Посмотрите логи: kubectl logs <pod-name> --previous (для предыдущего экземпляра) и kubectl describe pod <pod-name>.

Неправильный контекст или неймспейс:

• Проверьте текущий контекст: kubectl config current-context и неймспейс: kubectl config view --minify | grep namespace. Переключитесь при необходимости.

Ошибка "field is immutable":

• Некоторые поля ресурса нельзя изменить (например, имя). Удалите и создайте ресурс заново.

Ошибка "the server doesn't have a resource type ...":

• Возможно, используется устаревшая версия API. Проверьте доступные ресурсы: kubectl api-resources. Укажите правильную версию API в YAML.

Ошибка "image pull back off":

• Образ не найден или нет прав на его скачивание. Проверьте имя образа и настройте imagePullSecrets.

Сервис не предоставляет доступ:

• Для NodePort проверьте, что порт открыт на ноде. Для LoadBalancer проверьте, что провайдер создал балансировщик.

PersistentVolumeClaim в состоянии Pending:

• Нет подходящего PersistentVolume. Проверьте, есть ли PV или настройте динамическое provisioning через StorageClass.

Нет метрик для kubectl top:

• Убедитесь, что metrics-server установлен и работает.

Логи пода пустые:

• Приложение может не писать в stdout/stderr. Проверьте конфигурацию приложения.

Ошибка "error: You must be logged in to the server":

• Проверьте kubeconfig. Возможно, токен устарел.

Проблемы с DNS:

• Проверьте, что CoreDNS (или другой DNS-аддон) работает. Проверьте конфигурацию DNS в подах.

Ошибка при создании ресурса из YAML:

• Проверьте синтаксис YAML. Используйте kubectl apply --validate=true или kubectl create --dry-run=client.

Превышение квот (ResourceQuota):

• Проверьте квоты: kubectl describe quota. Удалите неиспользуемые ресурсы или запросите увеличение квоты.

Проблемы с обновлением ConfigMap/Secret в подах:

• Поды не обновляются автоматически. Перезапустите под (например, через rolling update развертывания).

Ошибка "error: a container name must be specified for pod ...":

• В поде несколько контейнеров, укажите имя контейнера флагом -c.

Ошибка "error: the connection to the server ... was refused":

• API-сервер недоступен. Проверьте, что кластер запущен и kubeconfig корректен.

Ошибка "error: unknown flag":

• Возможно, версия kubectl слишком старая. Обновите kubectl.

Проблемы с автодополнением:

• Установите плагин автодополнения для вашей оболочки.

Ошибка "error: no matches for kind ... in version ...":

• Укажите правильную версию API в YAML-манифесте.

Проблемы с временными файлами (emptyDir):

• emptyDir существует только пока под работает. Для постоянного хранения используйте PersistentVolume.

Ошибка "secret ... not found":

• Убедитесь, что Secret существует в том же неймспейсе.

Ошибка "field is immutable" при изменении аннотаций:

• Некоторые аннотации тоже immutable. Удалите и создайте заново.

Не могу получить доступ к сервису типа NodePort с хоста:

• Убедитесь, что вы используете IP ноды и порт NodePort, и что фаервол разрешает трафик.

Проблемы с LoadBalancer в облаке:

• Проверьте, что облачный провайдер поддерживает LoadBalancer и что у аккаунта есть права.

Ошибка "error: the server doesn't have a resource type "svc"":

• Правильно: kubectl get svc (сокращение) или kubectl get services.

Команда kubectl зависает:

• Увеличьте таймаут: kubectl --request-timeout=30s ....

Проблемы с именами ресурсов:

• Имена должны соответствовать DNS-именам (строчные буквы, цифры, дефисы, длина до 253 символов).

Ошибка "metadata.annotations: Too long":

• Аннотации имеют ограничение на размер (обычно 256KB). Уменьшите размер.

Не могу создать namespace:

• Проверьте права. Нужны права на создание namespace (например, роль с create на namespace).

Проблемы с обновлением кластера (upgrade):

• Перед обновлением убедитесь, что все поды работают и нет блокирующих issues. Следуйте инструкциям по обновлению для вашего дистрибутива.

Ошибка "error: the server doesn't have a resource type "ingress"":

• Установите Ingress controller и убедитесь, что Ingress API включен (networking.k8s.io/v1).

Проблемы с хранилищем (PersistentVolumeClaim в состоянии Pending):

• Проверьте, есть ли подходящий PersistentVolume. Возможно, нужно создать PV вручную или использовать StorageClass.

Ошибка "failed to start container" при kubectl run:

• Проверьте, существует ли образ и доступен ли он (правильное имя, тег, репозиторий).

Проблемы с селекторами (selectors) в сервисах:

• Убедитесь, что селекторы сервиса совпадают с метками подов.

Ошибка "error: unable to read URL" при kubectl apply:

• Проверьте, что URL доступен и вы имеете права на чтение.

Ошибка "error: no matches for kind "CronJob" in version "batch/v1beta1"":

• Убедитесь, что в YAML-манифесте указана правильная версия API (batch/v1 для CronJob) и что кластер поддерживает эту версию.

Проблемы с CronJob:

• Проверьте, что CronJob существует и что schedule корректен (формат Cron). Посмотрите события: kubectl describe cronjob <имя>.

Проблемы с обновлением ConfigMap/Secret в подах без перезапуска:

• Некоторые приложения могут перечитывать конфиг, но обычно требуется перезапуск пода. Используйте rolling update развертывания.

Ошибка "field is immutable" при изменении имени ресурса:

• Имя ресурса нельзя изменить. Удалите и создайте ресурс заново.

Проблемы с квотами на количество подов в неймспейсе:

• Проверьте ResourceQuota. Может потребоваться увеличение квоты или удаление неиспользуемых подов.

Ошибка "error: the server doesn't have a resource type "poddisruptionbudget"":

• Используйте policy/v1beta1 (устарел) или policy/v1 (если доступен). Проверьте версию API кластера.

Проблемы с network policies:

• Убедитесь, что NetworkPolicy разрешает трафик, который вам нужен. По умолчанию все трафик разрешен, если нет политик.

Ошибка "error: the server doesn't have a resource type "resourcequotas"":

• Правильное имя: resourcequota (ед.ч.) или resourcequotas (мн.ч.). Используйте kubectl get resourcequota.

Проблемы с именами сервисов и DNS:

• Имя сервиса должно быть валидным DNS-именем (строчные буквы, цифры, дефисы). Внутри кластера сервис доступен по <service-name>.<namespace>.svc.cluster.local.

Ошибка "error: the server doesn't have a resource type "horizontalpodautoscaler"":

• Убедитесь, что установлен metrics-server и что HPA API включен (autoscaling/v2). Проверьте: kubectl api-versions | grep autoscaling.

Проблемы с autoscaling (HPA):

• Проверьте, что metrics-server работает и предоставляет метрики. Убедитесь, что у развертывания заданы запросы на ресурсы (requests) в контейнерах.

Ошибка "error: the server doesn't have a resource type "mutatingwebhookconfiguration"":

• Используйте admissionregistration.k8s.io/v1 (или более старую версию). Проверьте доступные API-версии.

Проблемы с ValidatingWebhookConfiguration или MutatingWebhookConfiguration:

• Проверьте, что вебхук доступен (сертификат, URL) и возвращает правильный HTTP-статус (200). Посмотрите события: kubectl get events --all-namespaces.

Ошибка "error: the server doesn't have a resource type "priorityclass"":

• Используйте scheduling.k8s.io/v1. Проверьте, что PriorityClass существует.

Проблемы с PriorityClass:

• Проверьте, что PriorityClass существует и что в поде указано priorityClassName. Убедитесь, что значение priority корректно.

Ошибка "error: the server doesn't have a resource type "runtimeclass"":

• Используйте node.k8s.io/v1. Проверьте, что RuntimeClass существует и что ноды поддерживают указанный runtime handler.

Проблемы с RuntimeClass:

• Проверьте, что RuntimeClass существует и что в поде указан runtimeClassName. Убедитесь, что на нодах установлен соответствующий runtime (например, containerd с containerd-shim).

Ошибка "error: the server doesn't have a resource type "storageversion"":

• Это внутренний ресурс Kubernetes, обычно не требует вмешательства. Проблемы с миграцией storage versions могут возникнуть при обновлении кластера. Проверьте логи контроллеров.

Ошибка "error: the server doesn't have a resource type "csistoragecapacity"":

• Используйте storage.k8s.io/v1. Это часть CSI (Container Storage Interface). Убедитесь, что CSI driver поддерживает reporting capacity.

Проблемы с CSI driver и storage capacity:

• Проверьте, что CSI driver установлен и что он поддерживает reported capacity. Посмотрите события: kubectl get csinode и kubectl describe csinode.

Ошибка "error: the server doesn't have a resource type "volumeattributesclass"":

• Используйте storage.k8s.io/v1. Это ресурс для атрибутов томов в CSI. Убедитесь, что VolumeAttributesClass существует и что драйвер его поддерживает.

Проблемы с VolumeAttributesClass:

• Проверьте, что VolumeAttributesClass создан и что в PersistentVolumeClaim указан volumeAttributesClass (если требуется).

Ошибка "error: the server doesn't have a resource type "csidriver"":

• Используйте storage.k8s.io/v1. CSIDriver регистрирует CSI driver в кластере. Проверьте, что CSIDriver существует: kubectl get csidriver.

Проблемы с CSIDriver:

• Если CSIDriver не создан, томы, использующие этот driver, не смогут быть прикреплены. Установите CSI driver согласно документации провайдера.

Ошибка "error: the server doesn't have a resource type "csinode"":

• Используйте storage.k8s.io/v1. CSINode представляет узел с CSI driver. Проверьте: kubectl get csinode.

Проблемы с CSINode:

• Если CSINode отсутствует, CSI driver не развернут на ноде. Установите CSI driver на все ноды.

Ошибка "error: the server doesn't have a resource type "volumeattachment"":

• Используйте storage.k8s.io/v1. VolumeAttachment управляет прикреплением тома к ноде. Проверьте: kubectl get volumeattachment.

Проблемы с VolumeAttachment:

• Если VolumeAttachment в состоянии Pending, том не может быть прикреплен. Проверьте логи CSI driver и доступность тома.

Ошибка "error: the server doesn't have a resource type "volumesnapshotclass"":

• Используйте snapshot.storage.k8s.io/v1. VolumeSnapshotClass определяет драйвер для снапшотов. Проверьте: kubectl get volumesnapshotclass.

Проблемы с VolumeSnapshotClass:

• Убедитесь, что VolumeSnapshotClass существует и что CSI driver поддерживает snapshotting.

Ошибка "error: the server doesn't have a resource type "volumesnapshotcontent"":

• Используйте snapshot.storage.k8s.io/v1. VolumeSnapshotContent — это фактический снапшот. Проверьте: kubectl get volumesnapshotcontent.

Проблемы с VolumeSnapshotContent:

• Если VolumeSnapshotContent не в состоянии Ready, снапшот не готов. Проверьте события и логи CSI driver.

Ошибка "error: the server doesn't have a resource type "volumesnapshot"":

• Используйте snapshot.storage.k8s.io/v1. VolumeSnapshot — это запрос на создание снапшота. Проверьте: kubectl get volumesnapshot.

Проблемы с VolumeSnapshot:

• Если VolumeSnapshot не переходит в состояние Ready, проверьте VolumeSnapshotClass и права на создание снапшотов.