kubectl apply: Применить манифест: dry-run, kustomize, server-side apply

Базовый синтаксис

Команда kubectl apply — основной способ декларативного управления ресурсами в кластере. Она сравнивает поданную конфигурацию с текущим состоянием и вносит необходимые изменения для приведения объекта к желаемому виду.

Самый простой пример — создать или обновить ресурс из файла-манифеста:

kubectl apply -f deployment.yaml

Здесь -f указывает на файл с конфигурацией. Команда прочитает deployment.yaml, определит тип ресурса (например, Deployment) и его имя, а затем отправит запрос в API Kubernetes. Если такого ресурса ещё нет — он будет создан. Если существует — его конфигурация будет обновлена в соответствии с файлом.

Полезные флаги

-f или --filename — базовый флаг для указания файлов или директорий. Можно применять сразу несколько манифестов.

kubectl apply -f ./manifests/

-k или --kustomize — применяет ресурсы, описанные в kustomization.yaml. Идеально для управления окружениями (dev, staging, prod).

kubectl apply -k overlays/production/

--dry-run=client — симуляция применения. Команда проверит синтаксис, валидность манифеста и выведет результат в stdout, но не отправит ничего в API сервера. Отличный способ предварительной проверки.

kubectl apply -f deployment.yaml --dry-run=client

--server-side — включает режим Server-Side Apply (SSA). Полезен для точного управления полями и разрешения конфликтов в автоматизированных пайплайнах, особенно при работе с Helm или несколькими операторами.

kubectl apply -f configmap.yaml --server-side

Типичные сценарии

1. Предварительная проверка сложного манифеста перед реальным применением. Это предотвращает случайное создание некорректных ресурсов.

kubectl apply -f complex-setup.yaml --dry-run=client -o yaml

Флаг -o yaml выведет итоговый манифест, который был бы отправлен на сервер, что позволяет увидеть результат после всех мерджей и преобразований.

2. Деплой приложения в определённое окружение с помощью Kustomize. У вас есть базовая конфигурация и оверлеи для разных окружений.

kubectl apply -k overlays/staging/

В директории overlays/staging/ лежит kustomization.yaml, который может патчить образы, реплики, метки из базовой конфигурации.

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

Игнорирование вывода --dry-run=client. Dry-run проверяет только синтаксис и схему, но не семантику. Он не поймёт, что указанный образ Docker не существует или ConfigMap ссылается на несуществующий ключ. Всегда тестируйте манифесты в изолированном неймспейсе.

Путаница между kubectl apply и kubectl create/replace. apply использует аннотации для отслеживания изменений. Если вы сначала создали ресурс через kubectl create, а потом пытаетесь изменить его через apply, это работает. Но если кто-то вручную удалит аннотацию kubectl.kubernetes.io/last-applied-configuration, механизм трехстороннего слияния в apply сломается, что может привести к неожиданным результатам. В таких случаях помогает переход на --server-side.