kubectl apply: Usage, Options & Common CI Errors

The declarative deploy command - apply a manifest, get the desired state.

kubectl apply is the workhorse of GitOps-style CI: it reconciles cluster state to the manifests you pass, creating what is missing and patching what changed. Understanding its merge behaviour prevents the surprising errors it throws.

What it does

kubectl apply -f computes a three-way merge between the last-applied config, the live object, and your new manifest, then patches only the differences. With --server-side the API server owns the merge and tracks field managers, which is the modern default for CI. -k applies a kustomize directory; --prune deletes objects no longer in the manifest set.

Common usage

kubectl apply -f manifests/                      # a directory of YAML
kubectl apply -k overlays/prod                   # a kustomize overlay
kubectl apply -f deploy.yaml --server-side
kubectl apply -f deploy.yaml --dry-run=server    # validate, no write
kubectl diff -f deploy.yaml                       # preview the change

Common errors in CI

Two failures dominate pipelines. "error validating data: ValidationError(...): unknown field" means your manifest has a typo or targets an API version the cluster does not support - run kubectl apply --dry-run=server -f to validate against the live schema before committing. "Apply failed with N conflicts: conflict with \"<manager>\"" appears with server-side apply when another controller (or a prior client-side apply) owns a field; resolve it deliberately with --force-conflicts rather than blindly, since it transfers ownership.

Options

Related guides