What is KubePug?
KubePug (Kubernetes PreUpGrade Checker) is an open-source kubectl plugin and CLI tool designed to identify deprecated or deleted APIs in your Kubernetes cluster or manifest files before you perform an upgrade.
Key Features
- Deprecation Detection: Scans your live cluster or static YAML manifests to find resources using APIs that are slated for removal in future Kubernetes versions.
- Replacement Guidance: Not only flags outdated APIs but also suggests the recommended replacement API and specifies the exact version where the deprecation or deletion occurs.
- Version Targeting: Allows you to specify a target Kubernetes version (e.g., v1.31) to validate your current resources against that specific future release.
- Flexible Data Source: It automatically downloads a frequently updated API definition file (every 30 minutes) to stay current with the latest Kubernetes releases.
Why Use It?
As Kubernetes evolves, APIs are moved from alpha/beta to stable (GA), and older versions are eventually removed. If you upgrade your cluster without updating your manifests, those resources will fail to deploy or operate. KubePug provides a "pre-flight" check to prevent these breaking changes from reaching production.
Installation & Usage
You can install KubePug via Krew (where it is listed under the name deprecations) or as a standalone binary.
Method Command
--------- -------------
Install via Krew kubectl krew install deprecations
Scan Live Cluster kubectl deprecations --k8s-version=v1.30
Scan Manifest File kubepug --input-file=./my-manifest.yaml
Installation via Krew
% kubectl krew install deprecations
Updated the local copy of plugin index.
Installing plugin: deprecations
Installed plugin: deprecations
\
| Use this plugin:
| kubectl deprecations
| Documentation:
| https://github.com/rikatz/kubepug
| Caveats:
| \
| | * By default, deprecations finds deprecated object relative to the current kubernetes
| | master branch. To target a different kubernetes release, use the --k8s-version
| | argument.
| |
| | * Deprecations needs permission to GET all objects in the Cluster
| /
/
WARNING: You installed plugin "deprecations" from the krew-index plugin repository.
These plugins are not audited for security by the Krew maintainers.
Run them at your own risk.
Execution
Once installed, the plugin is invoked using kubectl deprecations.
Scan Current Cluster
Check your live cluster for deprecated APIs against a specific target Kubernetes version:
% kubectl deprecations --k8s-version=v1.33
Error: failed to get apiservices: apiservices.apiregistration.k8s.io is forbidden: User "sso:user" cannot list resource "apiservices" in API group "apiregistration.k8s.io" at the cluster scope
time="2026-02-26T14:20:19Z" level=error msg="An error has occurred: failed to get apiservices: apiservices.apiregistration.k8s.io is forbidden: User \"sso:user\" cannot list resource \"apiservices\" in API group \"apiregistration.k8s.io\" at the cluster scope"
KubePug requires running user to have "list" permissions on resource "apiservices" in API group "apiregistration.k8s.io" at the cluster scope as otherwise the above error will appear.
If required permissions are in place:
% kubectl deprecations --k8s-version=v1.33
No deprecated or deleted APIs found
Kubepug validates the APIs using Kubernetes markers. To know what are the deprecated and deleted APIS it checks, please go to https://kubepug.xyz/status/
Scan Local Manifest Files
Validate static YAML files before applying them to a cluster:
kubectl deprecations --input-file=./my-manifests/
View Results in Different Formats
Output the findings in json or yaml for automated processing:
kubectl deprecations --format=json
Check for Help and Flags
See all available configuration options, such as using a custom database file or setting error codes:
kubectl deprecations --help
Key Parameters
--k8s-version: The Kubernetes release you intend to upgrade to (defaults to the latest stable).
--error-on-deprecated: Forces the command to exit with an error code if deprecated APIs are found, which is useful for CI/CD pipelines.
---
No comments:
Post a Comment