Отладка неудачных развертываний: выявление распространенных ошибок YAML и конфигурации

Неудачи развертывания Kubernetes обычно проявляются в виде подов, застрявших в состояниях Pending, ImagePullBackOff, CrashLoopBackOff или с нулевым количеством доступных реплик. Причина часто видна в событиях, но вам нужно проверить развертывание, ReplicaSet и поды в правильном порядке.

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

Первые шаги: проверка статуса развертывания и событий

Когда развертывание терпит неудачу, ваши первые диагностические шаги всегда должны включать проверку самого основного ресурса и событий, связанных с управляемыми им ReplicaSet и подами. Это дает представление на самом высоком уровне о том, что Kubernetes пытается сделать и почему это не удается.

1. Проверка работоспособности развертывания

Используйте kubectl get deployments, чтобы увидеть общий статус. Обратите особое внимание на столбцы READY, UP-TO-DATE и AVAILABLE. Несоответствие здесь указывает на проблему с базовыми подами.

kubectl get deployments <имя-развертывания>

Если статус развертывания показывает мало или ноль готовых реплик, переходите к проверке ReplicaSet.

2. Просмотр событий ReplicaSet и подов

ReplicaSet управляют желаемым количеством подов. Если развертывание не удается, ReplicaSet обычно является источником каскада ошибок. Используйте команду describe для ReplicaSet, который обычно называется <имя-развертывания>-<хэш>:

kubectl describe rs <имя-replicaset>

Крайне важно изучить раздел Events внизу вывода. В этом разделе подробно описаны недавние действия, включая попытки планирования, сбои извлечения образов и проблемы с монтированием томов. Эти события часто являются неопровержимой уликой.

Наконец, проверьте сами поды, так как они сообщают о непосредственном сбое:

kubectl get pods -l app=<метка-вашего-приложения>
kubectl describe pod <имя-пода>

Найдите поля State и Reason в описании пода. Распространенные причины включают ImagePullBackOff, ErrImagePull, CrashLoopBackOff и Pending.

Распространенные ошибки конфигурации в манифестах YAML

Неправильные конфигурации в ваших YAML-файлах являются наиболее частой причиной сбоев развертывания. Эти ошибки могут варьироваться от простых ошибок отступа до сложных структурных проблем.

1. Ошибки синтаксиса и структуры YAML

API Kubernetes чрезвычайно чувствительны к правильному синтаксису YAML (отступы, пробелы и типы данных). Если YAML недействителен, kubectl apply часто сразу же завершится ошибкой, сообщая, что не может разобрать файл.

Лучшая практика: используйте линтер Всегда проверяйте синтаксис YAML перед применением. Инструменты, такие как yamllint или встроенная поддержка IDE, могут сразу выявить основные синтаксические ошибки.

Пример распространенной структурной ошибки: Неправильное сопоставление или отступ.

# НЕПРАВИЛЬНО: containers принадлежит spec.template.spec, а не непосредственно spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      labels:
        app: my-app
    containers:
      - name: my-app
        image: myregistry/myapp:v1

Правильное размещение:

spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:v1
          ports:
            - containerPort: 8080

2. Ошибки ссылок на образы и их извлечения

Если поды переходят в состояние ImagePullBackOff или ErrImagePull, проблема связана с доступом к образу контейнера.

Опечатка в имени/теге образа: Перепроверьте написание репозитория образа, имени и тега.
Аутентификация в частном реестре: Если вы извлекаете образ из частного реестра, убедитесь, что вы создали секрет для извлечения образа и указали его как imagePullSecrets в спецификации пода.

# Фрагмент, показывающий использование ImagePullSecret
spec:
  imagePullSecrets:
    - name: my-registry-secret
  containers:
    - name: my-app
      image: private.example.com/my-app:v1

3. Нарушения запросов и лимитов ресурсов

Если под остается в статусе Pending и в событиях упоминается нехватка ресурсов, узлы кластера не могут удовлетворить требования к ЦП или памяти, определенные в YAML.

Проверьте лимиты, указанные в манифесте развертывания:

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

Шаги по устранению неполадок:

Используйте kubectl describe nodes, чтобы увидеть доступную емкость.
Если вы видите события типа 0/3 nodes are available: 3 Insufficient cpu, вы должны либо уменьшить requests в вашем YAML, либо добавить больше узлов в кластер.

Продвинутые проблемы конфигурации

Помимо базового синтаксиса и извлечения образов, сложные конфигурации, связанные с сетью, хранилищем и планированием, могут привести к трудно диагностируемым сбоям.

1. Неправильно настроенные пробы (Liveness и Readiness)

Если под переходит в состояние CrashLoopBackOff, это часто означает, что контейнер запускается, но немедленно не проходит проверку, или он запускается, но многократно не проходит свою readiness-пробу.

Liveness-пробы: Если эта проверка многократно не удается, Kubernetes перезапускает контейнер. Проверьте kubectl describe pod <имя-пода> на наличие событий сбоя пробы и kubectl logs <имя-пода> --previous после перезапуска.
Readiness-пробы: Если эта проверка не удается, под продолжает работать, но исключается из конечных точек Сервиса. Убедитесь, что путь, порт и ожидаемый код ответа соответствуют тому, что на самом деле обслуживает ваше приложение.

Пример распространенной ошибки Readiness Probe: Нацеливание на неправильный порт или ожидание HTTP, когда приложение предоставляет только TCP.

2. Сбои томов и PersistentVolumeClaim (PVC)

Если поды ожидают из-за проблем с томами, проверьте статус PVC:

kubectl get pvc <имя-pvc>

Если статус PVC Pending, это означает, что кластер не смог найти соответствующий StorageClass или подходящий PersistentVolume для привязки. Проверьте события PVC на наличие конкретных ошибок привязки.

3. Правила Affinity и Anti-Affinity

Сложные правила планирования, такие как nodeAffinity или podAntiAffinity, могут непреднамеренно помешать планированию пода, если ни один узел не удовлетворяет всем критериям. Если поды остаются в состоянии Pending и в событиях упоминаются ограничения планирования, проверьте эти правила.

Например, если вы требуете, чтобы под работал на узле с определенной меткой (nodeSelector), которой нет ни у одного существующего узла, под никогда не будет запланирован.

# Пример: ограничение развертывания узлами с меткой 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Совет по устранению неполадок: Временно закомментируйте ограничивающие правила nodeSelector или affinity. Если под запланируется успешно, вы узнаете, что проблема в критериях выбора.

Рабочий процесс отладки

Столкнувшись с неудачным развертыванием, следуйте этому структурированному пути:

Статус развертывания: kubectl get deployments -> Сообщают ли реплики о готовности?
События подов: kubectl describe pod <сбойный-под> -> Проверьте раздел Events на наличие немедленных ошибок (ImagePull, OOMKilled, проблемы с томами).
Журналы контейнеров: kubectl logs <сбойный-под> -> Если контейнер запускается, но падает (CrashLoopBackOff), подозрение падает на логику приложения или liveness-пробы.
Проверка ресурсов: Если под в состоянии Pending, проверьте ограничения ресурсов (Insufficient cpu/memory) или неудачные привязки томов (статус PVC).
Проверка конфигурации: Проверьте YAML на наличие отступов, правильных имен полей и допустимых значений ресурсов (requests/limits).

Работайте на основе доказательств, полученных от кластера, а не гадайте. Проверяйте статус, события, журналы, ресурсы и структуру манифеста в таком порядке, затем вносите наименьшее изменение в YAML, которое соответствует найденной ошибке.