kubectl explain и dry-run

Зачем нужен dry-run

Манифест это YAML-файл, который описывает объект Kubernetes. Писать его с нуля руками медленно, и в отступах легко ошибиться.

Обычный порядок другой. Сначала генерируешь заготовку, открываешь её в редакторе, дописываешь нужные поля, применяешь. Заготовку даёт kubectl - это команда для управления кластером.

--dry-run - флаг, который просит kubectl собрать объект, но не создавать его.

kubectl run skeleton --image=nginx:1.25 --dry-run=client -o yaml

nginx:1.25 здесь для примера и краткости. В проде берут nginxinc/nginx-unprivileged:1.25: он запускается без root, что требуют большинство кластерных политик безопасности.

--dry-run=client означает: kubectl собирает объект на твоей машине, проверяет его и печатает в терминал. API-сервер (центр управления кластером) при этом ничего не получает. Pod не создаётся.

-o yaml задаёт формат вывода: YAML. Без этого флага kubectl напечатает короткую строку, а не полный манифест.

Вывод можно сразу записать в файл:

kubectl run skeleton --image=nginx:1.25 --dry-run=client -o yaml > /tmp/skeleton.yaml

Файл получается валидный, его можно применить через kubectl apply -f. Обычно в него ещё дописывают руками то, чего kubectl run сам не умеет: probes, resources, volumes, command.

client и server dry-run

У флага два значения.

--dry-run=client работает локально. kubectl сам собирает объект и проверяет схему. Это быстро и работает без доступа к кластеру.

--dry-run=server отправляет объект на API-сервер. Тот прогоняет полную проверку (admission, квоты, политики безопасности), но не сохраняет объект в хранилище кластера. В ответ приходит объект таким, каким он стал бы после сохранения.

Server-вариант медленнее, но проверяет строже. Для генерации заготовок обычно хватает client.

kubectl explain

kubectl explain - встроенная документация по полям объектов. Работает без интернета.

kubectl explain pod

Команда покажет, какие поля есть у объекта Pod. Глубже можно пройти через точку:

kubectl explain pod.spec
kubectl explain pod.spec.containers
kubectl explain pod.spec.containers.resources

Флаг --recursive печатает все вложенные поля сразу, без описаний:

kubectl explain pod.spec.containers --recursive | head -30

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

Что kubectl run пишет в заготовку

kubectl run skeleton --image=nginx:1.25 соберёт примерно такое:

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: skeleton
  name: skeleton
spec:
  containers:
    - image: nginx:1.25
      name: skeleton
      resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

В этом выводе есть лишние поля. creationTimestamp: null, status: {}, пустое resources: {} - это шум. API-сервер их игнорирует, удалять необязательно. Но в git хочется чистый файл, поэтому их обычно вычищают руками.

Label run: skeleton добавляется автоматически. Label - это пара ключ-значение, по которой объекты находят друг друга.

restartPolicy: Always - значение по умолчанию для Pod, kubectl прописал его явно.

Частые ошибки

kubectl create работает не для всех ресурсов. Для CronJob, Service, ConfigMap есть отдельные подкоманды: kubectl create cronjob, kubectl create service clusterip, kubectl create configmap.

Набор команд для повтора

# Скелет Pod в файл
kubectl run skeleton --image=nginx:1.25 --dry-run=client -o yaml > /tmp/skeleton.yaml
cat /tmp/skeleton.yaml

# Что есть в spec.containers
kubectl explain pod.spec.containers | head -30

# То же дерево, но плоско
kubectl explain pod.spec.containers --recursive | head -30

# Заготовка Deployment
kubectl create deployment web --image=nginx:1.25 --replicas=3 --dry-run=client -o yaml

Домашка

Теорию закрепляет задание на своём кластере: 3 шага с проверкой. Кластер поднимается по треку Kubernetes локально, задания лежат в репозитории k8s-practice.

./run.sh start k8s-kubectl-explain-dryrun     # развернуть стартовое состояние
./run.sh verify k8s-kubectl-explain-dryrun    # проверить текущий шаг

Коротко

• --dry-run=client -o yaml печатает готовый манифест, ничего не создавая в кластере.
• client проверяет только схему локально, server гоняет объект через admission и квоты, но не сохраняет.
• Вывод пишут в файл и дописывают то, чего генератор не умеет: probes, resources, volumes, command.
• В заготовке остаётся шум: creationTimestamp: null, status: {}, пустое resources: {}.
• kubectl explain pod.spec.containers показывает поля объекта офлайн, флаг --recursive разворачивает всё дерево.