Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/replicatedhq/troubleshoot
Preflight Checks and Support Bundles Framework for Kubernetes Applications
https://github.com/replicatedhq/troubleshoot
go golang kubernetes modern-on-prem preflight troubleshooting
Last synced: 3 days ago
JSON representation
Preflight Checks and Support Bundles Framework for Kubernetes Applications
- Host: GitHub
- URL: https://github.com/replicatedhq/troubleshoot
- Owner: replicatedhq
- License: apache-2.0
- Created: 2019-07-08T22:27:40.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-14T00:22:51.000Z (12 days ago)
- Last Synced: 2025-01-15T12:52:07.203Z (10 days ago)
- Topics: go, golang, kubernetes, modern-on-prem, preflight, troubleshooting
- Language: Go
- Homepage: https://troubleshoot.sh
- Size: 8.94 MB
- Stars: 548
- Watchers: 23
- Forks: 94
- Open Issues: 53
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Support: docs/support-bundle.md
Awesome Lists containing this project
- awesome-cloud-native - troubleshoot - Preflight Checks and Support Bundles Framework for Kubernetes Applications. (OPS)
- awesome-kubectl-plugins - kubectl support-bundle
- awesome-starred - replicatedhq/troubleshoot - Preflight Checks and Support Bundles Framework for Kubernetes Applications (kubernetes)
README
# Replicated Troubleshoot
Replicated Troubleshoot is a framework for collecting, redacting, and analyzing highly customizable diagnostic information about a Kubernetes cluster. Troubleshoot specs are created by 3rd-party application developers/maintainers and run by cluster operators in the initial and ongoing operation of those applications.
Troubleshoot provides two CLI tools as kubectl plugins (using [Krew](https://krew.dev)): `kubectl preflight` and `kubectl support-bundle`. Preflight provides pre-installation cluster conformance testing and validation (preflight checks) and support-bundle provides post-installation troubleshooting and diagnostics (support bundles).
To know more about troubleshoot, please visit: https://troubleshoot.sh/
## Preflight Checks
Preflight checks are an easy-to-run set of conformance tests that can be written to verify that specific requirements in a cluster are met.
To run a sample preflight check from a sample application, install the preflight kubectl plugin:
```
curl https://krew.sh/preflight | bash
```
and run, where https://preflight.replicated.com provides an **example** preflight spec:
```
kubectl preflight https://preflight.replicated.com
```
**NOTE** this is an example. Do **not** use to validate real scenarios.
For more details on creating the custom resource files that drive preflight checks, visit [creating preflight checks](https://troubleshoot.sh/docs/preflight/introduction/).
## Support Bundle
A support bundle is an archive that's created in-cluster, by collecting logs and cluster information, and executing specified commands (including redaction of sensitive information). After creating a support bundle, the cluster operator will normally deliver it to the 3rd-party application vendor for analysis and disconnected debugging. Another Replicated project, [KOTS](https://github.com/replicatedhq/kots), provides k8s apps an in-cluster UI for processing support bundles and viewing analyzers (as well as support bundle collection).
To collect a sample support bundle, install the troubleshoot kubectl plugin:
```
curl https://krew.sh/support-bundle | bash
```
and run, where https://support-bundle.replicated.com provides an **example** support bundle spec:
```
kubectl support-bundle https://support-bundle.replicated.com
```
**NOTE** this is an example. Do **not** use to validate real scenarios.
For more details on creating the custom resource files that drive support-bundle collection, visit [creating collectors](https://troubleshoot.sh/docs/collect/) and [creating analyzers](https://troubleshoot.sh/docs/analyze/).
And see our other tool [sbctl](https://github.com/replicatedhq/sbctl) that makes it easier to interact with support bundles using `kubectl` commands you already know
# Community
For questions about using Troubleshoot, how to contribute and engaging with the project in any other way, please refer to the following resources and channels.
- [Replicated Community](https://help.replicated.com/community) forum
- [#app-troubleshoot channel in Kubernetes Slack](https://kubernetes.slack.com/channels/app-troubleshoot)
- [#Community meetings calendar](https://calendar.google.com/calendar/u/0?cid=Y19mMGx1aGhiZGtscGllOGo5dWpicXMwNnN1a0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t). This happen monthly but dates may change and would be kept upto date in the calendar.
# Software Bill of Materials
A signed SBOM that includes Troubleshoot dependencies is included in each release.
- **troubleshoot-sbom.tgz** contains a software bill of materials for Troubleshoot.
- **troubleshoot-sbom.tgz.sig** is the digital signature for troubleshoot-sbom.tgz
- **key.pub** is the public key from the key pair used to sign troubleshoot-sbom.tgz
The following example illustrates using [cosign](https://github.com/sigstore/cosign) to verify that **troubleshoot-sbom.tgz** has
not been tampered with.
```sh
$ cosign verify-blob --key key.pub --signature troubleshoot-sbom.tgz.sig troubleshoot-sbom.tgz
Verified OK
```
If you were to get an error similar to the one below, it means you are verifying an SBOM signed using cosign `v1` using a newer `v2` of the binary. This version introduced [breaking changes](https://github.com/sigstore/cosign/blob/main/CHANGELOG.md#breaking-changes) which require an additional flag `--insecure-ignore-tlog=true` to successfully verify SBOMs like so.
```sh
$ cosign verify-blob --key key.pub --signature troubleshoot-sbom.tgz.sig troubleshoot-sbom.tgz --insecure-ignore-tlog=true
WARNING: Skipping tlog verification is an insecure practice that lacks of transparency and auditability verification for the blob.
Verified OK
```