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 namedpreflight.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
noteFor 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:
- clusterPodStatuses
- clusterVersion
- deploymentStatus
- distribution
- nodeResources
- statefulsetStatus
- storageClass
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.
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.
- Kubernetes Secret
- Preflight Custom Resource
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)."
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: preflight-checks
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)."
The following shows how the pass
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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.
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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.
The following shows how the warn
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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
The following shows how the pass
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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 }}
This example uses KOTS template functions in the Config context to render the credentials and connection details for the MySQL server that were supplied by the user in the Replicated Admin Console Config page. Replicated recommends using a template function for the URI, as shown above, to avoid exposing sensitive information. For more information about template functions, see About Template Functions.
This example also uses an analyzer with strict: true
, which prevents installation from continuing if the preflight check fails.
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
spec:
collectors:
- mysql:
collectorName: mysql
uri: 'repl{{ ConfigOption "db_user" }}:repl{{ConfigOption "db_password" }}@tcp(repl{{ ConfigOption "db_host" }}:repl{{ConfigOption "db_port" }})/repl{{ ConfigOption "db_name" }}'
analyzers:
- mysql:
# `strict: true` prevents installation from continuing if the preflight check fails
strict: true
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
The following shows how a fail
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade when strict: true
is set for the analyzer:
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.
- Kubernetes Secret
- Preflight Custom Resource
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.
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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.
The following shows how a warn
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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.
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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.
The following shows how a fail
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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.
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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.
The following shows how a pass
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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
The following shows how the fail
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade:
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.
- Kubernetes Secret
- Preflight Custom Resource
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
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: my-app
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
The following shows how the pass
outcome for this preflight check is displayed in the Admin Console during KOTS installation or upgrade: