Kubernetes Spec Compare: Spot Breaking API Changes

Kubernetes upgrades are where silent API changes show up. Fields move, defaults shift, and deprecations become removals. Compare OpenAPI specs before you roll the control plane forward, not after workloads fail to apply.

Use the Kubernetes Spec Compare tool to diff API objects between versions.

Quick steps

1. Pick two Kubernetes versions (source and target).
2. Choose a resource type: Deployment, Pod, Service, Ingress, etc.
3. Review added, removed, and modified fields in the spec diff.
4. Update manifests and CI checks based on what changed.

What to look for

Example workflow

Compare Deployment between v1.28 and v1.30:

1. Note fields only present in the newer spec (new knobs you might want).
2. Note fields marked deprecated or absent in the newer spec.
3. Open a known-good Deployment manifest and patch it, or convert JSON/YAML with JSON to YAML / YAML to JSON while editing.
4. Validate edited YAML with YAML Validator before apply.

Repeat for every resource type you actually deploy, not just Deployments.

Common mistakes

• Assuming patch upgrades are always safe. Minor versions can deprecate beta APIs you still use.
• Ignoring deprecation warnings. They appear in release notes and often in kubectl warnings before hard failure.
• Checking one resource only. Ingress, HPAs, PDBs, and CRDs (outside this tool’s core scope) all matter. CRDs need separate vendor docs.

Verification checklist

• Review all core resources your cluster templates use.
• Compare a production-like manifest against the target version spec.
• Document field changes in your upgrade runbook.
• Run dry-run applies (kubectl apply --dry-run=server) in a staging cluster when possible.