Skip to main content

Defining Preflight Checks

This topic describes how to define preflight checks in Helm- and standard Kubernetes manifest-based applications. For more information about preflight checks, see About Preflight Checks and Support Bundles.

The information in this topic applies to applications that are installed with the Helm CLI or with Replicated KOTS.

Step 1: Create the Manifest File​

You can define preflight checks in a Kubernetes Secret or in a Preflight custom resource. The type of manifest file that you use depends on your application type (Helm- or standard manifest-based) and the installation methods that your application supports (Helm CLI, KOTS v1.101.0 or later, or KOTS v1.100.3 or earlier).

  • Helm-Based Applications: For Helm-based applications, see the following guidance:

    • (Recommended) Helm CLI or KOTS v1.101.0 or Later: For Helm-based applications installed with the Helm CLI or KOTS v1.101.0 or later, define the preflight checks in a Kubernetes Secret in your Helm chart templates. See Kubernetes Secret.

    • KOTS v1.100.3 or Earlier: For Helm-based applications installed with KOTS v1.100.3 or earlier, define the preflight checks in a Preflight custom resource. See Preflight Custom Resource.

  • Standard Manifest-Based Applications: For standard manifest-based applications, define the preflight checks in a Preflight custom resource. See Preflight Custom Resource.

Kubernetes Secret​

For Helm-based applications installed with the Helm CLI or KOTS v1.101.0 or later, define preflight checks in a Kubernetes Secret in your Helm chart templates. This allows you to define the preflights spec only one time to support running preflight checks in both Helm CLI and KOTS installations.

For a tutorial that demonstrates how to define preflight checks in a Secret in chart templates and then run the preflight checks in both Helm CLI and KOTS installations, see Tutorial: Add Preflight Checks to a Helm Chart.

Add the following YAML to a Kubernetes Secret in your Helm chart templates directory:

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      collectors: []
      analyzers: []

As shown above, the Secret must include the following:

  • The label troubleshoot.sh/kind: preflight
  • A stringData field with a key named preflight.yaml so that the preflight binary can use this Secret when it runs from the CLI

Preflight Custom Resource​

Define preflight checks in a Preflight custom resource for the following installation types:

  • Standard manifest-based applications installed with any version of KOTS

  • Helm-based applications installed with KOTS v1.100.3 and earlier

    note

    For Helm charts installed with KOTS v1.101.0 and later, Replicated recommends that you define preflight checks in a Secret in the Helm chart templates instead of using the Preflight custom resource. See Create a Secret above.

    In KOTS v1.101.0 and later, preflights defined in the Helm chart override the Preflight custom resource used by KOTS. During installation, if KOTS v1.101.0 and later cannot find preflights specified in the Helm chart archive, then KOTS searches for kind: Preflight in the root of the release.

Add the following YAML to a new file in a release:

apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
  name: preflights
spec:
  collectors: []
  analyzers: []

For more information about the Preflight custom resource, see Preflight and Support Bundle.

Step 2: Define Collectors and Analyzers​

This section describes how to define collectors and analyzers for preflight checks based on your application needs. You add the collectors and analyzers that you want to use in the spec.collectors and spec.analyzers keys in the manifest file that you created.

For examples of collectors and analyzers defined in Kubernetes Secrets and Preflight custom resources, see Example Specifications below.

Collectors​

Collectors gather information from the cluster, the environment, the application, or other sources. Collectors generate output that is then used by the analyzers that you define to generate results for the preflight checks.

The following default collectors are included automatically to gather information about the cluster and cluster resources:

You do not need manually include the clusterInfo or clusterResources collectors in the specification. To use only the clusterInfo and clusterResources collectors, delete the spec.collectors key from the preflight specification.

The Troubleshoot open source project includes several additional collectors that you can include in the specification to gather more information from the installation environment. To view all the available collectors, see All Collectors in the Troubleshoot documentation.

Analyzers​

Analyzers use the output from the collectors to generate results for the preflight checks, including the criteria for pass, fail, and warn outcomes and custom messages for each outcome.

For example, in a preflight check that checks the version of Kubernetes running in the target cluster, the analyzer can define a fail outcome when the cluster is running a version of Kubernetes less than 1.25 that includes the following custom message to the user: The application requires Kubernetes 1.25.0 or later, and recommends 1.27.0.

The Troubleshoot open source project includes several analyzers that you can include in your preflight check specification. The following are some of the analyzers in the Troubleshoot project that use the default clusterInfo or clusterResources collectors:

To view all the available analyzers, see the Analyze section of the Troubleshoot documentation.

Block Installation with Required (Strict) Preflights​

For applications installed with KOTS, you can set any preflight analyzer to strict: true. When strict: true is set, any fail outcomes for the analyzer block the deployment of the release.

note

Strict preflight analyzers are ignored if the exclude property is also included and evaluates to true. See exclude in the Troubleshoot documentation.

Example Specifications​

This section includes common examples of preflight check specifications. For more examples, see the Troubleshoot example repository in GitHub.

Check HTTP or HTTPS Requests from the Cluster​

The examples below use the http collector and the textAnalyze analyzer to check that an HTTP request to the Slack API at https://api.slack.com/methods/api.test made from the cluster returns a successful response of "status": 200,.

For more information, see HTTP and Regular Expression in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      collectors:
        - http:
            collectorName: slack
            get:
              url: https://api.slack.com/methods/api.test
      analyzers:
        - textAnalyze:
            checkName: Slack Accessible
            fileName: slack.json
            regex: '"status": 200,'
            outcomes:
              - pass:
                  when: "true"
                  message: "Can access the Slack API"
              - fail:
                  when: "false"
                  message: "Cannot access the Slack API. Check that the server can reach the internet and check [status.slack.com](https://status.slack.com)."

Check Kubernetes Version​

The examples below use the clusterVersion analyzer to check the version of Kubernetes running in the cluster. The clusterVersion analyzer uses data from the default clusterInfo collector. The clusterInfo collector is automatically included.

For more information, see Cluster Version and Cluster Info in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:
        - clusterVersion:
            outcomes:
              - fail:
                  when: "< 1.25.0"
                  message: The application requires Kubernetes 1.25.0 or later, and recommends 1.28.0.
                  uri: https://www.kubernetes.io
              - warn:
                  when: "< 1.28.0"
                  message: Your cluster meets the minimum version of Kubernetes, but we recommend you update to 1.28.0 or later.
                  uri: https://kubernetes.io
              - pass:
                  message: Your cluster meets the recommended and required versions of Kubernetes.

Check Kubernetes Distribution​

The examples below use the distribution analyzer to check the Kubernetes distribution of the cluster. The distribution analyzer uses data from the default clusterInfo collector. The clusterInfo collector is automatically included.

For more information, see Cluster Info and Distribution in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:              
        - distribution:
            checkName: Kubernetes distribution
            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
              - 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

Check MySQL Version Using Template Functions​

The examples below use the mysql collector and the mysql analyzer to check the version of MySQL running in the cluster.

For more information, see Collect > MySQL and Analyze > MySQL in the Troubleshoot documentation.

This example uses Helm template functions to render the credentials and connection details for the MySQL server that were supplied by the user. Additionally, it uses Helm template functions to create a conditional statement so that the MySQL collector and analyzer are included in the preflight checks only when MySQL is deployed, as indicated by a .Values.global.mysql.enabled field evaluating to true.

For more information about using Helm template functions to access values from the values file, see Values Files.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      {{ if eq .Values.global.mysql.enabled true }}
      collectors:
        - mysql:
            collectorName: mysql
            uri: '{{ .Values.global.externalDatabase.user }}:{{ .Values.global.externalDatabase.password }}@tcp({{ .Values.global.externalDatabase.host }}:{{ .Values.global.externalDatabase.port }})/{{ .Values.global.externalDatabase.database }}?tls=false'
      {{ end }}
      analyzers:
        {{ if eq .Values.global.mysql.enabled true }}
        - mysql:
            checkName: Must be MySQL 8.x or later
            collectorName: mysql
            outcomes:
              - fail:
                  when: connected == false
                  message: Cannot connect to MySQL server
              - fail:
                  when: version < 8.x
                  message: The MySQL server must be at least version 8
              - pass:
                  message: The MySQL server is ready
        {{ end }}

Check Node Memory​

The examples below use the nodeResources analyzer to check that a required storage class is available in the nodes in the cluster. The nodeResources analyzer uses data from the default clusterResources collector. The clusterResources collector is automatically included.

For more information, see Cluster Resources and Node Resources in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers: 
        - nodeResources:
            checkName: Every node in the cluster must have at least 8 GB of memory, with 32 GB recommended
            outcomes:
              - fail:
                  when: "min(memoryCapacity) < 8Gi"
                  message: All nodes must have at least 8 GB of memory.
                  uri: https://kurl.sh/docs/install-with-kurl/system-requirements
              - warn:
                  when: "min(memoryCapacity) < 32Gi"
                  message: All nodes are recommended to have at least 32 GB of memory.
                  uri: https://kurl.sh/docs/install-with-kurl/system-requirements
              - pass:
                  message: All nodes have at least 32 GB of memory.

Check Node Storage Class Availability​

The examples below use the storageClass analyzer to check that a required storage class is available in the nodes in the cluster. The storageClass analyzer uses data from the default clusterResources collector. The clusterResources collector is automatically included.

For more information, see Cluster Resources and Node Resources in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:
        - storageClass:
            checkName: Required storage classes
            storageClassName: "default"
            outcomes:
              - fail:
                  message: Could not find a storage class called "default".
              - pass:
                  message: A storage class called "default" is present.

Check Node Ephemeral Storage​

The examples below use the nodeResources analyzer to check the ephemeral storage available in the nodes in the cluster. The nodeResources analyzer uses data from the default clusterResources collector. The clusterResources collector is automatically included.

For more information, see Cluster Resources and Node Resources in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:
        - nodeResources:
            checkName: Every node in the cluster must have at least 40 GB of ephemeral storage, with 100 GB recommended
            outcomes:
              - fail:
                  when: "min(ephemeralStorageCapacity) < 40Gi"
                  message: All nodes must have at least 40 GB of ephemeral storage.
                  uri: https://kurl.sh/docs/install-with-kurl/system-requirements
              - warn:
                  when: "min(ephemeralStorageCapacity) < 100Gi"
                  message: All nodes are recommended to have at least 100 GB of ephemeral storage.
                  uri: https://kurl.sh/docs/install-with-kurl/system-requirements
              - pass:
                  message: All nodes have at least 100 GB of ephemeral storage.

Check Requirements Are Met By At Least One Node​

The examples below use the nodeResources analyzer with filters to check that the requirements for memory, CPU cores, and architecture are met by at least one node in the cluster. The nodeResources analyzer uses data from the default clusterResources collector. The clusterResources collector is automatically included.

For more information, see Cluster Resources and Node Resources in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:  
        - nodeResources:
            checkName: Node requirements
            filters:
            # Must have 1 node with 16 GB (available) memory and 5 cores (on a single node) with amd64 architecture
              allocatableMemory: 16Gi
              cpuArchitecture: amd64
              cpuCapacity: "5"
            outcomes:
              - fail:
                  when: "count() < 1"
                  message: This application requires at least 1 node with 16GB available memory and 5 cpu cores with amd64 architecture
              - pass:
                  message: This cluster has a node with enough memory and cpu cores

Check Total CPU Cores Across Nodes​

The examples below use the nodeResources analyzer to check the version of Kubernetes running in the cluster. The nodeResources analyzer uses data from the default clusterResources collector. The clusterResources collector is automatically included.

For more information, see Cluster Resources and Node Resources in the Troubleshoot documentation.

apiVersion: v1
kind: Secret
metadata:
  labels:
    troubleshoot.sh/kind: preflight
  name: "{{ .Release.Name }}-preflight-config"
stringData:
  preflight.yaml: |
    apiVersion: troubleshoot.sh/v1beta2
    kind: Preflight
    metadata:
      name: preflight-sample
    spec:
      analyzers:
        - nodeResources:
            checkName: Total CPU Cores in the cluster is 4 or greater
            outcomes:
              - fail:
                  when: "sum(cpuCapacity) < 4"
                  message: The cluster must contain at least 4 cores
                  uri: https://kurl.sh/docs/install-with-kurl/system-requirements
              - pass:
                  message: There are at least 4 cores in the cluster