Troubleshoot

Greetings and welcome to part two of the Replicated Runthrough series. We’ll will be covering Troubleshoot.sh, a Kubernetes plugin for – you guessed it – troubleshooting host and cluster-level issues. Part of a suite of Kubernetes cluster maintenance tools by Replicated including (but not limited to) Outdated, Unfork, and KOTS, Troubleshoot is a highly customizable, powerful, yet lightweight framework for collecting, and analyzing cluster information that is also intelligent enough to automatically redact sensitive cluster information like passwords, secrets, and keys. 

Comprised of two separate CLI components – preflight and support-bundle – troubleshoot is incredibly useful for streamlining the application delivery process via preflight checks by identifying host incompatibilities early. 

The second component, support-bundle, helps to eliminate “language barriers” between clients and support teams by quickly and securely extracting as little or as much cluster info as needed and compressing said info into a lightweight and portable .tar archive. As an added benefit, both preflight and support-bundle checks are written in yaml format which is already familiar to Kubernetes users, meaning there’s basically no learning curve. All you need is kubectl connected to a Kubernetes cluster.

preflight



apiVersion: troubleshoot.sh/v1beta2 

kind: preflight 

metadata: 

  name: my-application-name 

spec: 

  analyzers: []

As mentioned earlier, preflight is run when you want to make sure that your client isn’t running K8s v0.7 when your application requires >v1.15 or something else equally terrible. preflight provides access to checks (called analyzers) for host information like storage availability, cloud provider, available RAM, CPU, and can also check overall cluster details like node count, eliminating the headache of trying to debug an environment incompatibility by identifying it before your app is even launched. 

You (or your team) will write out a yaml definition for your check declaring what analyzers you want to be run on the host which is then shared with your client to run on their own host using the kubectl preflight plugin. After a few seconds, preflight will tell them whether or not their environment is compatible with your software. 

support-bundle



apiVersion: troubleshoot.sh/v1beta2

kind: SupportBundle

metadata:

  name: my-application-name

spec:

  analyzers: []

The second component to troubleshoot, support-bundle is what you pull out when your client calls and tells you that something is on fire. Same as with preflight, you or your team will write out a yaml file specifying collectors that can pull system info or even inject data depending on which collectors are used. Using the kubectl support-bundle plugin, the client runs it on their end and is supplied with an archive which can then be sent to you (or your team) for quick diagnosis support-bundle collectors can pull everything from basic Kubernetes cluster info and logs to database information and tons of other crucial data, while automatically redacting sensitive customer info from a client without the need for installing additional software. The collected data is automatically compressed into an easy-to-share tar.gz archive that can quickly be passed over to support teams to make it easier to get your client back up and running.

Both preflight and support-bundle begin with a collect phase that will scrape default data like cluster version, node status, pod status, along with any other collectors specified in your customized check. To make the troubleshooting process even more streamlined, preflight and support-bundle checks can be doubled up in the same check, as shown in the example below. 



apiVersion: troubleshoot.sh/v1beta2

kind: SupportBundle

metadata:

  name: supportbundle-tutorial

spec:

  collectors: []

  analyzers: []

There are a million different options available for Kubernetes troubleshooting tools, but I doubt you’ll find one as versatile, yet lightweight, as Troubleshoot. 

But you don’t have to take my word for it. If you’d like to see it in action, head on over to troubleshoot.sh for more examples, install instructions, documentation, and more. Check out our previous edition, kURL 101, in the meantime, and be sure to stay tuned to the Replicated blog for the next edition in the Replicated Runthrough series. See you then!