Introduction

Older kubectl versions accepted --dry-run as a boolean flag. Newer versions changed this to a mode value: --dry-run=client, --dry-run=server, or --dry-run=none. If you keep using the old form, you will see deprecation warnings or command failures depending on your cluster and client versions.

This change matters because “dry run” now has explicit semantics. Client-side dry run validates and prints output locally without sending to the API server. Server-side dry run sends the request for admission and validation but does not persist the object. Choosing the right mode can catch configuration and policy issues earlier.

Core Sections

1. Replace deprecated syntax directly

Old pattern:

kubectl run demo --image=nginx --dry-run -o yaml

New pattern:

kubectl run demo --image=nginx --dry-run=client -o yaml

For generated manifests in scripts, --dry-run=client -o yaml is usually the right migration.

2. Understand client vs server

client mode:

• Uses local schema and command logic.
• No API server contact.
• Good for quick manifest generation.

server mode:

• Sends request to API server with dryRun option.
• Executes admission controllers and defaulting.
• Best for validating what the cluster would accept.

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

If this fails, your object would likely fail on real apply too.

3. Update CI scripts and aliases

Many teams still have shell aliases or CI steps with deprecated syntax. Search and replace consistently:

rg "--dry-run(\s|$)" .

Then update commands:

kubectl create configmap app-config \
  --from-file=./config.env \
  --dry-run=client -o yaml | kubectl apply -f -

This pattern remains useful for declarative workflows.

4. Validate cluster-level policies with server dry run

If you use OPA/Gatekeeper or Kyverno policies, client dry run may pass while server dry run fails. Include server validation in pull request checks:

kubectl apply -f k8s/ --dry-run=server

This catches policy violations before deployment windows.

5. Handle version skew intentionally

Client and server versions can differ in managed environments. If dry-run behavior is surprising, inspect versions:

kubectl version --short

Pin kubectl in CI and developer tooling to reduce inconsistent validation results.

Common Pitfalls

• Replacing deprecated flag with --dry-run=client everywhere, even when server validation is required.
• Assuming client dry run validates admission policies and mutating webhooks.
• Ignoring version skew between local kubectl and cluster API server.
• Leaving deprecated syntax in scripts that silently fail in future upgrades.
• Treating dry run as a full runtime test rather than schema and admission validation.

Summary

The deprecation of bare --dry-run is more than syntax cleanup; it clarifies validation intent. Use --dry-run=client for local generation and --dry-run=server for cluster-accurate checks with admission logic. Update scripts, aliases, and CI pipelines systematically, and monitor version skew to keep results consistent. Once migrated, dry runs become a stronger safety net in Kubernetes delivery workflows.

A practical way to keep this issue from returning is to turn the fix into a lightweight runbook. Capture the exact environment assumptions (tool versions, runtime flags, cluster or platform settings, and required dependencies), then store a short verification command sequence that any teammate can run from a clean setup. This makes troubleshooting deterministic instead of person-dependent and reduces rework during on-call incidents.

It also helps to add one automated guardrail in CI or pre-deploy checks that validates the critical assumption described above. That guardrail might be a linter rule, a smoke test, a schema check, a policy validation step, or a minimal integration test. When the same class of failure is caught before release, teams spend less time on emergency debugging and more time on controlled improvements.