Troubleshooting Kubernetes

Ви навчитеся локалізувати відмову за шарами Kubernetes, зберігати evidence до зміни системи та обирати мінімальне оборотне виправлення.

• scope та identity
• controller, Pod і container states
• scheduling, image і runtime
• Service, EndpointSlice і DNS
• ephemeral containers та Node debug

Troubleshooting — це перевірка гіпотез, а не перебір команд. Спочатку сформулюйте спостережуваний симптом і час початку, визначте blast radius та recent changes, потім рухайтеся від зовнішнього ефекту до найближчого зламаного шару.

До виправлення збережіть object YAML, Conditions, Events, logs, revision і timestamps. Після зміни повторіть початкову перевірку: зелений rollout сам собою не доводить відновлення користувацького запиту.

• Context, cluster, namespace і permissions
• Workload controller: generation, observedGeneration, Conditions та revision
• Pod: phase, Conditions, init/containerStatuses і nodeName
• Container: waiting/terminated reason, exitCode, restartCount та previous logs
• Scheduling і storage: Events, constraints, PVC/PV та Node allocatable
• Network: Service selector, EndpointSlice readiness, DNS і NetworkPolicy
• Application: health endpoint, dependencies, configuration та telemetry

Pending зазвичай указує на scheduling, unbound storage або admission. ImagePullBackOff означає повторні спроби отримати image: перевіряйте ім’я, tag, registry, credentials та Events. CrashLoopBackOff — backoff між рестартами, а причина міститься в lastState, exitCode та previous logs.

Running не означає Ready, а Service без ready EndpointSlice не отримує backend. OOMKilled потребує зіставити memory limit, usage і поведінку процесу; Evicted — тиск Node, а не збій container runtime.

kubectl exec запускає процес у робочому контейнері й не допоможе для distroless image без shell або вже завершеного процесу. Ephemeral container додає інструменти до наявного Pod без restart, але потребує права update на pods/ephemeralcontainers і не видаляється окремо до видалення Pod.

kubectl debug може створити копію Pod або Node debug Pod. Для Node його filesystem доступний через /host, а host namespaces розширюють область впливу. Profile sysadmin створює привілейований контекст; використовуйте його лише за затвердженою процедурою та видаляйте debug Pod після роботи.

• Одна ітерація — одна перевірювана гіпотеза
• Спочатку read-only команди, потім мінімальна зміна
• Не видаляйте проблемний Pod до збереження logs --previous та Events
• Не використовуйте force delete як діагностику
• Перевіряйте точний container, namespace і час події
• Не встановлюйте пакети у production container
• Фіксуйте команди, UTC timestamps і результат для incident timeline
• Після відновлення усуньте системну причину й оновіть runbook

Збережіть manifest як troubleshooting-lab.yaml. Він навмисно створює робочий застосунок із помилковим Service selector, bad image, crashing process та workload із неможливим nodeSelector.

apiVersion: v1
kind: Namespace
metadata: {name: lab-troubleshooting}
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: api, namespace: lab-troubleshooting}
spec:
  replicas: 1
  selector:
    matchLabels: {app: api}
  template:
    metadata:
      labels: {app: api}
    spec:
      containers:
        - name: api
          image: busybox:1.37.0
          command: ["sh", "-c", "mkdir -p /www; echo ok > /www/index.html; exec httpd -f -p 8080 -h /www"]
          ports: [{name: http, containerPort: 8080}]
          readinessProbe:
            httpGet: {path: /, port: http}
---
apiVersion: v1
kind: Service
metadata: {name: api, namespace: lab-troubleshooting}
spec:
  selector: {app: api-typo}
  ports: [{name: http, port: 80, targetPort: http}]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: bad-image, namespace: lab-troubleshooting}
spec:
  replicas: 1
  selector:
    matchLabels: {app: bad-image}
  template:
    metadata:
      labels: {app: bad-image}
    spec:
      containers: [{name: web, image: "nginx:does-not-exist"}]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: crash, namespace: lab-troubleshooting}
spec:
  replicas: 1
  selector:
    matchLabels: {app: crash}
  template:
    metadata:
      labels: {app: crash}
    spec:
      containers:
        - name: worker
          image: busybox:1.37.0
          command: ["sh", "-c", "echo fatal: configuration missing >&2; exit 42"]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: unschedulable, namespace: lab-troubleshooting}
spec:
  replicas: 1
  selector:
    matchLabels: {app: unschedulable}
  template:
    metadata:
      labels: {app: unschedulable}
    spec:
      nodeSelector: {course.example.com/pool: absent}
      containers: [{name: sleeper, image: "busybox:1.37.0", command: ["sleep", "3600"]}]

Не виправляйте об’єкти під час першого перегляду. Для кожного workload запишіть симптом, evidence і лише одну припущену причину.

kubectl apply -f troubleshooting-lab.yaml
kubectl get deployment,pod,service,endpointslice -n lab-troubleshooting -o wide
kubectl events -n lab-troubleshooting --types=Warning
kubectl describe pod -n lab-troubleshooting -l app=bad-image
kubectl logs -n lab-troubleshooting -l app=crash -c worker --previous --tail=20
kubectl describe pod -n lab-troubleshooting -l app=unschedulable
kubectl get service api -n lab-troubleshooting -o jsonpath='{.spec.selector}{"\n"}'
kubectl get pod -n lab-troubleshooting -l app=api --show-labels
kubectl get endpointslice -n lab-troubleshooting -l kubernetes.io/service-name=api -o yaml

Очікується: ImagePullBackOff у bad-image, exitCode 42 і previous log у crash, FailedScheduling у unschedulable, порожні ready endpoints у Service api.

Виправте кожен незалежний дефект і повторно перевірте rollout та traffic endpoints.

kubectl set image deployment/bad-image web=nginx:1.29-alpine -n lab-troubleshooting
kubectl patch deployment crash -n lab-troubleshooting --type=json -p='[{"op":"replace","path":"/spec/template/spec/containers/0/command","value":["sleep","3600"]}]'
kubectl patch deployment unschedulable -n lab-troubleshooting --type=json -p='[{"op":"remove","path":"/spec/template/spec/nodeSelector"}]'
kubectl patch service api -n lab-troubleshooting --type=merge -p='{"spec":{"selector":{"app":"api"}}}'
kubectl rollout status deployment/bad-image -n lab-troubleshooting --timeout=120s
kubectl rollout status deployment/crash -n lab-troubleshooting --timeout=120s
kubectl rollout status deployment/unschedulable -n lab-troubleshooting --timeout=120s
kubectl get pod,endpointslice -n lab-troubleshooting -o wide

Критерій: чотири Deployments Available, Pods Ready, api EndpointSlice містить ready address, нові Warning Events не з’являються.

Для робочого api додайте ephemeral container. Інтерактивна команда блокує термінал; вийдіть через exit. Видимість процесів через --target залежить від runtime.

POD="$(kubectl get pod -n lab-troubleshooting -l app=api -o jsonpath='{.items[0].metadata.name}')"
kubectl auth can-i update pods/ephemeralcontainers -n lab-troubleshooting
kubectl debug -n lab-troubleshooting -it "$POD" --image=busybox:1.37.0 --target=api --profile=general
kubectl describe pod "$POD" -n lab-troubleshooting
kubectl delete namespace lab-troubleshooting

Наступні команди наведено лише для контрольованої адміністративної діагностики Node. general profile не є privileged, але Pod отримує host namespaces і /host. Не використовуйте sysadmin без окремого погодження.

NODE="$(kubectl get node -o jsonpath='{.items[0].metadata.name}')"
kubectl create namespace node-debug
kubectl debug node/"$NODE" -n node-debug -it --image=busybox:1.37.0 --profile=general
kubectl get pod -n node-debug -o wide
kubectl delete namespace node-debug

• Чому CrashLoopBackOff не є першопричиною?
• Коли потрібен logs --previous?
• Чому Running не доводить доступність Service?
• Чим ephemeral container відрізняється від копії Pod?
• Які ризики створює kubectl debug node?
• Що треба перевірити після технічного відновлення?

Модуль засвоєно, якщо ви класифікуєте чотири відмови без випадкових змін, підтверджуєте кожну причину evidence та перевіряєте користувацький результат після виправлення.