Kubernetes Deprecated APIs Checker
Check Kubernetes manifests for API versions removed by a target release, with blocker counts, migration queues, and replacement cues.| {{ header }} | Copy |
|---|---|
| {{ cell }} | |
|
No rows for this tab
The current manifest and scan horizon did not produce this artifact.
|
{{ result.patchText }}Kubernetes upgrades often fail for a reason that is easy to miss in a large manifest set: an object can still look like valid YAML while naming an API version the upgraded API server no longer serves. The resource name, labels, selectors, and fields may all be familiar, but the apiVersion and kind pair decides whether the control plane will accept the object at all.
Deprecation and removal are different upgrade concerns. A deprecated API is still accepted for a period of time, usually with a newer stable version available. A removed API has crossed the point where the target Kubernetes version stops serving it. That distinction matters because a deprecated resource can be scheduled for cleanup, while a removed resource can block an apply, Helm upgrade, GitOps sync, or recovery run during the maintenance window.
The risky material is often spread across more places than one repository. Helm templates can render different manifests for different values files, old release metadata can keep previous API versions alive, cluster exports can show server-converted objects, and generated YAML can drift from the source chart. API migration review works best when teams treat the rendered manifest, the source manifest, and the target control plane version as separate facts that must agree before the upgrade is attempted.
| Situation | Why it matters | Common mistake |
|---|---|---|
| Control plane upgrade | Removed APIs stop being served at the target version. | Checking the current cluster only, not the version being reached. |
| Helm or GitOps rollout | Rendered output can differ by values, branches, and chart dependencies. | Scanning a template path that is not the manifest the cluster will receive. |
| Cluster export review | The API server may return a newer served version for stored objects. | Treating an export as proof that the original source manifests are migrated. |
| Future cleanup planning | Later removals can be fixed while the team is already touching the chart. | Mixing future cleanup with blockers that must be resolved before the next upgrade. |
How to Use This Tool:
Use the checker against the manifest text that will actually be applied for the upgrade. Render charts or Kustomize overlays first when templates or environment values change the final resource list.
- Enter a Review label that names the repository, chart, pull request, release, or cluster export being checked.
- Choose the Target Kubernetes version for the control plane you intend to reach, such as v1.22, v1.25, v1.29, or v1.32.
- Select the Scan horizon. Use Target gate only for upgrade go/no-go review, Target plus next known removal for near-term cleanup, or All known removals for a broader backlog.
- Set Source context so the migration queue matches the evidence source, such as Git or Kustomize manifests, rendered Helm output, live Helm release metadata, or a cluster export.
- Paste multi-document YAML or JSON into Manifest YAML or JSON, or browse for a manifest file. Use the beta API hint only when unlisted alpha or beta versions should appear as advisory rows.
If Manifest review notes reports a parse problem or no resources, fix the pasted YAML or provide a rendered manifest before treating the scan as complete.
- Read Upgrade Snapshot first, then inspect API Findings and Migration Queue for the resources that must be changed before the target version.
- Use Removal Version Map and Migration Snippets as planning aids, then verify the changed manifests with a Kubernetes dry run or staging apply before the upgrade window.
Interpreting Results:
Start with the summary state and blocker count. Upgrade blocked means at least one submitted resource uses an API removed at or before the selected target version. Migration warning means the API is already deprecated but still served for that target. Future cleanup appears only when the chosen scan horizon includes removals after the target gate. Advisory only is a hint for unlisted pre-GA APIs, not an official removal match.
- API Findings gives the resource, API version, removal version, replacement, and action for each matched rule.
- Migration Queue is the handoff view for source changes because it pairs the API change with a review note and source-context action.
- Manifest Inventory is the sanity check that the scan saw the expected resources, including objects with no known removal match.
- Migration Snippets provide replacement starting points. They are not a guarantee that field-level migrations are complete.
A clean result only covers the submitted text and the built-in removal table. It does not prove that every Helm values path, generated runtime object, operator-created resource, custom resource, or provider-specific API is safe for the target cluster.
Technical Details:
Kubernetes resource acceptance starts with the API group, version, and kind. The same object name can move through several API versions over its lifetime, and some moves change required fields or default behavior. A useful migration check therefore compares the submitted apiVersion and kind with a removal table before looking at replacement notes.
The built-in rules cover official Kubernetes deprecation-guide removals through v1.32. Target gates v1.33 through v1.36 are selectable for planning, but the current rule set adds no extra removal-release rows beyond the v1.32 coverage note. That keeps the output honest: later targets can still catch older removed APIs, but they do not invent removals not present in the built-in table.
Rule Core
| Finding class | Condition | Meaning |
|---|---|---|
| Upgrade blocker | Target version is greater than or equal to the API removal version. | The API is no longer served at the target gate and must be migrated or removed. |
| Critical blocker | Same as blocker, with no in-place replacement API recorded. | The resource needs a workflow migration, not only a version-string edit. |
| Deprecated warning | Target version is greater than or equal to the deprecation version but less than the removal version. | The API still works for the target but should be scheduled before its removal release. |
| Future removal | The API is known to be removed after the target and is included by the selected horizon. | The row is cleanup planning, not a blocker for the selected target. |
| Advisory | An alpha or beta API is not in the known table and the beta hint is enabled. | The owner, operator, or vendor lifecycle needs manual confirmation. |
Removal Examples
| Removed in | Representative API | Replacement or migration concern |
|---|---|---|
| v1.22 | networking.k8s.io/v1beta1 Ingress |
Use networking.k8s.io/v1 and review backend service fields plus pathType. |
| v1.25 | policy/v1beta1 PodDisruptionBudget |
Use policy/v1 and check empty selector behavior. |
| v1.25 | policy/v1beta1 PodSecurityPolicy |
No policy/v1 successor exists; migrate to Pod Security Admission or another admission policy path. |
| v1.32 | flowcontrol.apiserver.k8s.io/v1beta3 FlowSchema or PriorityLevelConfiguration |
Use flowcontrol.apiserver.k8s.io/v1 and review flow-control field defaults. |
Parsing supports YAML, JSON, Kubernetes List objects, and multi-document streams. When the normal YAML parser is unavailable, JSON parsing is attempted, and a limited line scan can still detect obvious apiVersion and kind pairs. Fallback detection is useful for finding blockers in damaged input, but it should not replace a valid rendered manifest for the final upgrade decision.
Limitations and Privacy:
The manifest text is reviewed in the browser. The checker does not contact a Kubernetes API server, inspect a live cluster, discover CRDs, or verify whether a cloud provider, operator, or admission webhook will accept the migrated object.
- Rule coverage is fixed to the built-in official removal table through v1.32.
- Field-level migration snippets are starting points. Apply-server validation and human review are still needed for schema changes.
- Cluster exports can hide old source API versions because persisted objects may be returned in a served version.
- Custom resources and vendor APIs may use alpha or beta versions with their own lifecycle outside core Kubernetes rules.
- Pasted manifests can include internal names, namespaces, labels, image references, and topology clues, so handle copied output as operationally sensitive.
Advanced Tips:
- Keep Scan horizon on Target gate only for release approval so future cleanup does not distract from blockers.
- Switch to Target plus next known removal after blockers are cleared to decide which nearby deprecations should be fixed in the same pull request.
- Use Source context deliberately. A Helm release metadata finding points to a different remediation path than a Git manifest finding.
- Lower Visible row limit for screenshots and raise it for handoff reviews that need more table rows visible before export.
- Compare Manifest Inventory with the expected release object count. A small inventory often means the wrong values file, overlay, or file type was pasted.
Worked Examples:
Ingress before a v1.22 upgrade
A repository still using networking.k8s.io/v1beta1 for Ingress should show an upgrade blocker when the target is v1.22 or newer. The replacement cue points to networking.k8s.io/v1, but the manifest also needs field review because the stable Ingress shape changes backend service fields and requires pathType.
No-successor policy removal
A policy/v1beta1 PodSecurityPolicy is not fixed by changing the version string. For v1.25 and later, the finding should be treated as a critical blocker because the policy model must move to Pod Security Admission or another admission policy approach.
Clean export, stale chart
A cluster export may show only served API versions after the API server has converted stored objects. If the source Helm chart still renders a removed API, the next install or rollback can fail. Scan the rendered chart output as well as the export before marking the upgrade ready.
FAQ:
Can every finding be fixed by changing apiVersion?
No. Some migrations require required fields, renamed fields, changed defaults, or an entirely different policy path. Read the migration queue note before applying any snippet.
Should I scan Helm source or rendered manifests?
Scan rendered manifests for each important values set. Source templates can contain branches that do not appear until the chart is rendered for the target environment.
Why do later target versions show no new removal rows?
The selectable later gates still catch earlier removed APIs, but the built-in official removal table currently covers removals through v1.32. Confirm newer release-specific removals separately when planning beyond that coverage.
What should I do when no resources are found?
Paste Kubernetes resource YAML or JSON with apiVersion and kind, or render the chart or overlay first. Values files and partial snippets may not contain enough resource identity to scan.
What should unknown beta API advisories mean?
Treat them as review prompts. They may be CRDs or vendor APIs with their own lifecycle, so check the owning project before changing or approving them for the target cluster.
Glossary:
- API removal
- The release point where a Kubernetes API version is no longer served by the API server.
- Deprecated API
- An API version that still works for now but has a documented replacement or removal path.
- Target gate
- The Kubernetes version being used as the upgrade decision point.
- Rendered manifest
- The final YAML or JSON generated by Helm, Kustomize, or another templating path before it is applied.
- CRD
- A CustomResourceDefinition, which can define API versions outside the core Kubernetes removal table.
- Dry run
- An API-server validation mode that checks a manifest without saving the object.
References:
- Deprecated API Migration Guide, Kubernetes Documentation.
- The Kubernetes API, Kubernetes Documentation.
- Declarative Management of Kubernetes Objects Using Configuration Files, Kubernetes Documentation.