Replicated Troubleshoot: preflight checks and support bundles for Kubernetes

Two tools for the two sides of an installation

Replicated Troubleshoot is a framework for collecting, redacting and analyzing highly customizable diagnostic information about a Kubernetes cluster. The key structural fact is who writes the specs and who runs them.

Troubleshoot specs are created by third-party application developers and maintainers, and run by cluster operators in the initial and ongoing operation of those applications. So this is not a tool your platform team writes for itself. It is a contract between a software vendor and the operator of the customer's cluster, and the vendor's spec is what the operator executes.

The framework provides two CLI tools as kubectl plugins, using Krew. kubectl preflight gives pre-installation cluster conformance testing and validation, and kubectl support-bundle gives post-installation troubleshooting and diagnostics.

That split maps onto the two moments in a product's life in a customer's environment. Before installation, the question is whether the cluster can support the product at all, and that is a set of assertions about things like the storage class, the ingress controller, the Kubernetes version, or the presence of a particular capability. After installation, when something is broken in a cluster the vendor cannot see, the question is what state the cluster was in, and that is a bundle of logs, resource manifests and command output.

Both tools are installed the same way, by a krew install script piped to bash, and both are run against a spec URL. The project homepage is troubleshoot.sh, and the topic tags include preflight, troubleshooting and modern-on-prem.

Running a preflight check, and the example spec caveat

To run a sample preflight check from a sample application, you install the preflight kubectl plugin:

curl https://krew.sh/preflight | bash

and then run it against the example preflight spec:

kubectl preflight https://preflight.replicated.com

The README attaches a warning to this that is worth taking seriously, twice, once for preflight and once for support-bundle. This is an example, and you should not use it to validate real scenarios.

That warning is not a formality. A preflight spec is a set of assertions, and a spec that asserts the wrong thing about your cluster produces a wrong answer with full confidence. The example is there to show the mechanism, and the URL is a demonstration, not a validation suite for your environment.

For the real work, the documentation is in the custom resource files. The README points at the creating preflight checks page in the troubleshoot.sh documentation, which is where you find the spec format.

The vocabulary in the README is worth noting. Preflight checks are described as an easy-to-run set of conformance tests that can be written to verify that specific requirements in a cluster are met. So a check is a requirement expressed as a test, and the vendor writes them against their own product's requirements. The output of a failing preflight is what tells an operator, before anything is installed, that their cluster will not work.

A support bundle is an archive built in the cluster, with redaction applied

A support bundle is an archive created in-cluster, by collecting logs and cluster information, and executing specified commands, including redaction of sensitive information.

That redaction clause is the part that makes the whole thing viable in a customer environment. The archive is going to be handed to a third party, the software vendor, and a cluster contains secrets, so the collection has to be able to strip them. The README also lists redaction as a separate capability of the framework itself, alongside collecting and analyzing, which suggests it is a first-class part of the design rather than a post-processing step.

The workflow is that after creating a support bundle, the cluster operator will normally deliver it to the third-party application vendor for analysis and disconnected debugging. Disconnected is the operative word: the vendor analyses an archive, not a live cluster.

Collecting one works the same way as the preflight tool:

curl https://krew.sh/support-bundle | bash

and then:

kubectl support-bundle https://support-bundle.replicated.com

The documentation for the real work splits into two halves, creating collectors at the docs/collect/ path and creating analyzers at the docs/analyze/ path. Collectors are what you gather, and analyzers are how the output is interpreted, and the separation matters because the two are authored by different people in practice.

The companion project is KOTS, which provides Kubernetes apps with an in-cluster UI for processing support bundles and viewing analyzers, as well as support bundle collection. And sbctl is the other tool the README points at, described as making it easier to interact with support bundles using kubectl commands you already know.

A signed SBOM and SLSA provenance in every release

The supply chain side of the project is documented carefully, which fits a tool that runs with cluster access on a customer's machine.

A signed SBOM that includes Troubleshoot dependencies is included in each release. There are three files. troubleshoot-sbom.tgz contains the SBOM for Troubleshoot. troubleshoot-sbom.tgz.bundle contains the signature and transparency log data used by Cosign. And key.pub is the public key from the key pair used to sign troubleshoot-sbom.tgz.

The verification example uses Cosign:

$ cosign verify-blob --key key.pub --bundle troubleshoot-sbom.tgz.bundle troubleshoot-sbom.tgz
Verified OK

The build provenance story is separate and stronger. SLSA build provenance attestations are generated for the preflight and support-bundle archives in each release. You download the archive and the corresponding troubleshoot_<version>_provenance.sigstore.json bundle, then use Cosign v3.1.3 or later to verify that it was built by this repository's release workflow:

cosign verify-blob-attestation \
  --bundle troubleshoot_v0.135.0_provenance.sigstore.json \
  --type https://slsa.dev/provenance/v1 \
  --certificate-identity "https://github.com/replicatedhq/troubleshoot/.github/workflows/release.yaml@refs/tags/v0.135.0" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  preflight_linux_amd64.tar.gz

The certificate identity is pinned to the release workflow of this repository at a specific tag, and the OIDC issuer is the GitHub Actions token issuer. That combination is what makes the attestation meaningful, because it binds the binary to a specific workflow run in a specific repository rather than to a key that could have been reused.

The same provenance bundle verifies both the preflight and support-bundle archives from that release, so one download covers both tools.

The Go codebase, the build flags, and the release cadence

The repository is a Go project and the module is github.com/replicatedhq/troubleshoot, targeting Go 1.26.5.

The dependency list is long and describes the scope of what the tool has to reach in a cluster. There are database drivers for MySQL through go-sql-driver/mysql and for SQL Server through microsoft/go-mssqldb, plus ClickHouse through clickhouse-go and Redis through go-redis. There is the AWS SDK v2 with the S3 service, which is where support bundles are usually uploaded. Kubernetes is reached through jackc/pgx and other client libraries, and containerd/cgroups and vishvananda/netlink and netns are for host-level inspection. There is shirou/gopsutil for system metrics, cilium/ebpf, miekg/dns for name resolution checks, and the Velero project, which makes sense for a tool that collects backup related state. The CLI itself is cobra with viper for configuration.

The Makefile shows the build shape. There is a shared version package at pkg/version, and the linker flags inject the version, the git SHA and the build time into it, with the git SHA falling back to an empty string when the build is not happening inside a git repository. The build tags are netgo, containers_image_ostree_stub, exclude_graphdriver_devicemapper, exclude_graphdriver_btrfs and containers_image_openpgp, which are the flags you need to build a static binary that does not depend on the host's container storage drivers. There is a separate ffi target that builds a shared library with buildmode=c-shared, and separate unit, integration and end-to-end test targets, with the integration tests tagged and requiring a Kubernetes instance.

The release history shows a fast cadence and a version number that matters. v0.133.0 was published on 2026-08-20, v0.134.0 on 2026-09-04 and v0.134.1 on 2026-09-14, with the last push on 2026-10-19, and the provenance example in the README refers to v0.135.0, so the 0.135 line exists beyond the tags listed. The project is Apache-2.0 licensed, and the repository also carries a .grype.yaml vulnerability scan configuration and a securebuild/ directory.

Editorial conclusion

Troubleshoot suits a software vendor whose customers install the product into clusters they do not control, because it lets the vendor define the checks and the diagnostic collection while the operator runs them with familiar kubectl commands. It does not suit you as a general cluster debugging tool, since the specs are written by the application maintainers rather than by you, and it does not suit you if you cannot run a privileged collector in the cluster, because the support bundle is created in-cluster. Before you adopt it, read docs/collect/ and docs/analyze/ to understand the collector and analyzer model, and verify the release artefacts with the Cosign commands in the README, since both the SBOM and the SLSA provenance are shipped for that purpose.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. replicatedhq/troubleshoot on GitHub