Pluto Documentation

Pluto is a utility designed to identify deprecated Kubernetes apiVersions within your infrastructure. It helps prevent upgrade failures by detecting deprecated versions before they are removed by the Kubernetes API server.

Pluto can scan two primary types of targets:

1. Infrastructure-as-Code (IaC) Repositories: It checks static Kubernetes manifests and Helm charts for deprecated apiVersions.
2. Live Helm Releases: It checks active Helm 2 and Helm 3 releases currently running in your Kubernetes cluster.

Pluto distinguishes between two states of an API version:

• DEPRECATED: The version is still functional but slated for removal.
• REMOVED: The version is no longer supported by the Kubernetes API server.

When using --detect-api-resources or --detect-all-in-cluster, Pluto may rely on the kubectl.kubernetes.io/last-applied-configuration annotation. Be aware of the following reliability issues:

• Annotation Removal: Using kubectl patch to update an object can remove the kubectl.kubernetes.io/last-applied-configuration annotation entirely, making it an unreliable source for detecting deprecated APIs in a live cluster.
• False Positives: You may encounter false positives immediately following the first change made to fix an apiVersion.

By default, Pluto targets Kubernetes v1.22.0. You can specify a different target version using the --target-versions or -t flag.

Requirements:

• You must pass the format component=version (e.g., k8s=v1.15.0).
• The version string must begin with a v (e.g., v1.15.0).

Example:

$ pluto detect-helm --target-versions k8s=v1.15.0

On Windows, you can install Pluto using the Scoop package manager. Note that this specific bucket is not maintained by Fairwinds, though it is intended to stay up to date with releases.

scoop install pluto

As of version v5.24.0, Pluto has migrated to a new container registry. The old registry quay.io/fairwinds/pluto is deprecated and should no longer be used.

Required Action: Update your image references from the old registry to the new Google Artifact Registry location:

- quay.io/fairwinds/pluto:<tag>
+ us-docker.pkg.dev/fairwinds-ops/oss/pluto:<tag>

Pluto uses specific exit codes to signal the status of Kubernetes API version detection, making it suitable for CI/CD pipelines:

To prevent Pluto from failing a CI build due to deprecations or removals, use these flags to bypass specific exit codes:

• --ignore-deprecations: Prevents exit code 2.
• --ignore-removals: Prevents exit code 3.
• --ignore-unavailable-replacements: Prevents exit code 4.

If you use the asdf version manager, you can install the Pluto plugin and manage versions locally. Use asdf plugin-add pluto to add the plugin, then install and set your desired version.

asdf plugin-add pluto
asdf list-all pluto
asdf install pluto <latest version>
asdf local pluto <latest version>

You can extend Pluto's knowledge of deprecations and removals by providing a custom YAML file via the --additional-versions or -f flag. This allows you to define custom components and specific API version lifecycles.

Custom File Format:

target-versions:
  custom: v1.0.0
deprecated-versions:
  - version: someother/v1beta1
    kind: AnotherCRD
    deprecated-in: v1.9.0
    removed-in: v1.16.0
    replacement-api: apps/v1
    component: custom

To verify your custom definitions, use the list-versions command:

$ pluto list-versions -f new.yaml

Fairwinds signs Pluto docker images and checksum files using cosign. To ensure the integrity of your installation, you can verify the artifacts using the Fairwinds public key located at https://artifacts.fairwinds.com/cosign.pub.

To verify a checksums file downloaded from the releases page:

cosign verify-blob checksums.txt --signature=checksums.txt.sig --key https://artifacts.fairwinds.com/cosign.pub

To verify a Docker image:

cosign verify us-docker.pkg.dev/fairwinds-ops/oss/pluto:v5 --key https://artifacts.fairwinds.com/cosign.pub