/
View on GitHub

Getting Started

Get started with Preflight Checks and Support Bundles


Welcome. The easiest way to get started with the Troubleshoot project is to see it in action through a couple examples.

Installation

Executing Preflight Checks and Support Bundles relies on a client-side utility, packages as a kubectl plugin and distributed through the krew package manager. If you don't already have krew installed, head over to the krew installation guide, follow the steps there and then come back here.

Install the Preflight and Support Bundle plugin using:

kubectl krew install preflight
kubectl krew install support-bundle

Note: This will not install anything to your cluster, it only places a single binary per plugin in your path.

Examples

Now that you have the plugins installed lets look at a simple example of a Preflight Check and a Support Bundle to get a sense for how they are structured and how to run them.

Example Preflight check

Preflight Checks can be executed by your customer before installing your application into their Kubernetes cluster. The checks are defined in a YAML file. Here is an example of a simple Preflight Check that could be used to enforce a minimum Kubernetes version on your cluster.

apiVersion: troubleshoot.replicated.com/v1beta1
kind: Preflight
metadata:
  name: example-preflight-checks
spec:
  analyzers:
    - clusterVersion:
        outcomes:
          - fail:
              when: "< 1.13.0"
              message: The application requires at Kubernetes 1.13.0 or later, and recommends 1.15.0.
              uri: https://www.kubernetes.io
          - warn:
              when: "< 1.15.0"
              message: Your cluster meets the minimum version of Kubernetes, but we recommend you update to 1.15.0 or later.
              uri: https://kubernetes.io
          - pass:
              message: Your cluster meets the recommended and required versions of Kubernetes.
    - containerRuntime:
        outcomes:
          - pass:
              when: "== docker"
              message: Docker container runtime was found.
          - fail:
              message: Did not find Docker container runtime.
    - distribution:
        checkName: Check Kubernetes environment.
        outcomes:
          - fail:
              when: "== docker-desktop"
              message: The application does not support Docker Desktop Clusters
          - fail:
              when: "== microk8s"
              message: The application does not support Microk8s Clusters
          - fail:
              when: "== minikube"
              message: The application does not support Minikube Clusters
          - pass:
              when: "== eks"
              message: EKS is a supported distribution
          - pass:
              when: "== gke"
              message: GKE is a supported distribution
          - pass:
              when: "== aks"
              message: AKS is a supported distribution
          # Will be supported in the future
          - pass:
              when: "== kurl"
              message: KURL is a supported distribution
          - pass:
              when: "== digitalocean"
              message: DigitalOcean is a supported distribution
          - warn:
              message: Unable to determine the distribution of Kubernetes
    - nodeResources:
        checkName: Total CPU Cores in the cluster is 2 or greater
        outcomes:
          - fail:
              when: "sum(cpuCapacity) < 2"
              message: The cluster must contain at least 2 cores
          - fail:
              when: "sum(cpuCapacity) < 4"
              message: The cluster must contain at least 4 cores
          - pass:
              message: There are at least 2 cores in the cluster

Ready to try it out? Copy that YAML into a local file named preflight.yaml and run the following command to see the results of this Kubernetes version check Preflight Check.

kubectl preflight preflight.yaml

Example Support Bundle

Now lets use similar YAML to define a Support Bundle.

A Support Bundle needs to know what to collect and optionally, what to analyze. This is defined in a YAML file. There's a lot already included in the default collectors. Here is an example of a Support Bundle that collects the version of Kubernetes using similar YAML we wrote for the Preflight Check.

apiVersion: troubleshoot.replicated.com/v1beta1
kind: SupportBundle
metadata:
  name: kubernetes-version
spec:
  collectors: []
  analyzers:
    - clusterVersion:
        outcomes:
          - fail:
              when: < 1.16.0
              message: >-
                The application requires at Kubernetes 1.16.0 or later, and
                recommends 1.18.0.
              uri: 'https://kubernetes.io'
          - warn:
              when: < 1.18.0
              message: >-
                Your cluster meets the minimum version of Kubernetes, but we
                recommend you update to 1.18.0 or later.
              uri: 'https://kubernetes.io'
          - pass:
              message: >-
                Your cluster meets the recommended and required versions of
                Kubernetes.

Lets try it out and see what is collected by our Support Bundle. Save the YAML into a local file named bundle.yaml and execute the following command.

kubectl support-bundle bundle.yaml

What's next?

Create your own

Learn how to add custom preflight checks and support bundles to your application.

Browse examples

Looking for something specific or a place to start? Browse through some examples.

Read the docs

Ready to dig to the reference docs?