Kubernetes API, kubectl и жизненный цикл объектов

После модуля вы сможете читать Kubernetes API как контракт, выбирать поддерживаемую версию ресурса, различать spec и status, безопасно применять манифесты и диагностировать неудачный rollout по состоянию объектов.

• Discovery вместо угадывания apiVersion
• структурированное чтение объектов
• server-side validation до изменения кластера
• Server-Side Apply и владение полями

kubectl, контроллеры, scheduler, kubelet и операторы работают с API Server. Тип ресурса задают API group, version и kind; экземпляр дополнительно определяют namespace и name.

spec описывает желаемое состояние, status публикуют контроллеры. metadata.generation изменяется вместе со spec, а status.observedGeneration показывает уже обработанную контроллером ревизию.

kubectl api-resources
kubectl api-versions
kubectl explain deployment.spec.strategy
kubectl get --raw /api
kubectl get --raw /apis

Не угадывайте apiVersion по памяти: Discovery API показывает ресурсы конкретного кластера. Перед upgrade проверяйте deprecation guide и удалённые API целевой версии.

• core-группа записывается как v1
• alpha API может исчезнуть без периода совместимости
• beta API имеет ограниченные гарантии
• GA API предоставляет самые строгие гарантии совместимости

metadata идентифицирует объект, spec задаёт намерение, status отражает результат. Selector связывает Deployment с Pods, после создания неизменяем и должен совпадать с template labels.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: lab-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.28-alpine
          ports:
            - name: http
              containerPort: 80

Server-Side Apply записывает managedFields и обнаруживает конфликты владельцев. field-manager должен стабильно идентифицировать автоматизацию. В production манифест хранится в Git; kubectl edit и несистемный patch создают drift.

kubectl apply --server-side --field-manager=course-lab -f deployment.yaml
kubectl get deploy web -n lab-api -o json | jq '.metadata.managedFields[] | {manager,operation}'
kubectl diff -f deployment.yaml

• Перед изменением проверяйте context и namespace
• Сначала используйте kubectl diff и --dry-run=server
• Для скриптов выбирайте JSON, jsonpath или Go template
• get показывает объект, describe добавляет Events, logs читает контейнер
• Не применяйте --force-conflicts, пока не установили владельца поля

Определите группы и версии ресурсов своего кластера. Затем сохраните манифест как deployment.yaml и исследуйте схему полей через kubectl explain.

kubectl api-resources
kubectl api-versions
kubectl explain deployment.spec.strategy
kubectl get --raw /api
kubectl get --raw /apis

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: lab-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: web
  template:
    metadata:
      labels:
        app.kubernetes.io/name: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.28-alpine
          ports:
            - name: http
              containerPort: 80

Создайте namespace, примените Deployment через Server-Side Apply, дождитесь rollout и увеличьте desired replicas до трёх.

kubectl create namespace lab-api
kubectl apply --server-side --field-manager=course-lab -f deployment.yaml
kubectl rollout status deployment/web -n lab-api --timeout=120s
kubectl scale deployment/web -n lab-api --replicas=3
kubectl get pods -n lab-api -w

kubectl get deploy,pods -n lab-api -o wide
kubectl get deploy web -n lab-api -o yaml
kubectl describe deploy web -n lab-api
kubectl events -n lab-api --for deployment/web

Критерий: Available=True, observedGeneration равен generation, доступны три Pod, а managedFields содержит manager course-lab.

Установите несуществующий image tag. Timeout rollout ожидаем: сначала сохраните evidence, затем выполните rollback и очистку.

kubectl set image deployment/web nginx=nginx:does-not-exist -n lab-api
kubectl rollout status deployment/web -n lab-api --timeout=30s
kubectl get pods -n lab-api
kubectl events -n lab-api --types=Warning
kubectl rollout undo deployment/web -n lab-api
kubectl rollout status deployment/web -n lab-api --timeout=120s
kubectl delete namespace lab-api

Порядок: проверить context и namespace → generation → Conditions Deployment → состояния Pod → Warning Events → минимальное обратимое изменение.

• Чем ресурс отличается от объекта?
• Почему status нельзя хранить как желаемое состояние в Git?
• Что показывает observedGeneration?
• Зачем нужен server-side dry-run?
• Как managedFields помогает при конфликте?

Модуль освоен, если вы находите ресурс через Discovery, объясняете GVK и identity объекта, проверяете изменение до apply и доказываете причину неудачного rollout данными API.