Skip to content

Commit 722b1a1

Browse files
paigecalvertpaigecalvert
committed
Update preflight and sb spec guidance
1 parent 5c7827a commit 722b1a1

4 files changed

Lines changed: 176 additions & 394 deletions

File tree

‎docs/vendor/preflight-defining.mdx‎

Lines changed: 56 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,80 @@
11
# Define preflight checks
22

3-
This topic describes how to define preflight checks in Helm and Kubernetes manifest-based applications. For more information about preflight checks, see [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about).
3+
This topic describes how to define custom preflight checks for your application. For more information about preflight checks, see [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about).
44

5-
The information in this topic applies to applications that are installed with Helm or with Replicated KOTS.
5+
## Add a preflight spec to a release
66

7-
## Step 1: Create the manifest file
7+
You can define custom preflight checks for your application by adding a preflight spec to your Helm chart templates.
88

9-
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 Kubernetes manifest-based) and the installation methods that your application supports (Helm, KOTS v1.101.0 or later, or KOTS v1.100.3 or earlier).
9+
To add a preflight spec to a release for your application:
1010

11-
* **Helm Applications**: For Helm applications, see the following guidance:
11+
1. In your Helm chart `templates` directory, create a YAML file. Name the file `preflights.yaml` or similar.
1212

13-
* **(Recommended) Helm or KOTS v1.101.0 or Later**: For Helm applications installed with Helm or KOTS v1.101.0 or later, define the preflight checks in a Kubernetes Secret in your Helm chart `templates`. See [Kubernetes Secret](#secret).
13+
1. In the YAML file, add the following to create a Kubernetes Secret with the label `troubleshoot.sh/kind: preflight`:
1414

15-
* **KOTS v1.100.3 or Earlier**: For Helm applications installed with KOTS v1.100.3 or earlier, define the preflight checks in a Preflight custom resource. See [Preflight Custom Resource](#preflight-cr).
16-
17-
* **Kubernetes Manifest-Based Applications**: For Kubernetes manifest-based applications, define the preflight checks in a Preflight custom resource. See [Preflight Custom Resource](#preflight-cr).
18-
19-
### Kubernetes secret {#secret}
20-
21-
For Helm applications installed with Helm 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 and KOTS installations.
22-
23-
Add the following YAML to a Kubernetes Secret in your Helm chart `templates` directory:
24-
25-
```yaml
26-
apiVersion: v1
27-
kind: Secret
28-
metadata:
29-
labels:
30-
troubleshoot.sh/kind: preflight
31-
name: "{{ .Release.Name }}-preflight-config"
32-
stringData:
33-
preflight.yaml: |
34-
apiVersion: troubleshoot.sh/v1beta2
35-
kind: Preflight
15+
```yaml
16+
# templates/preflight.yaml
17+
apiVersion: v1
18+
kind: Secret
3619
metadata:
37-
name: preflight-sample
38-
spec:
39-
collectors: []
40-
analyzers: []
41-
```
42-
43-
As shown above, the Secret must include the following:
44-
45-
* The label `troubleshoot.sh/kind: preflight`
46-
* A `stringData` field with a key named `preflight.yaml` so that the preflight binary can use this Secret when it runs from the CLI
47-
48-
### Preflight custom resource {#preflight-cr}
20+
# the troubleshoot.sh/kind: preflight label is required
21+
labels:
22+
troubleshoot.sh/kind: preflight
23+
name: "{{ .Release.Name }}-preflight-config"
24+
```
25+
26+
1. In the Secret, add a `stringData` field with a key named `preflight.yaml`. This ensures the `preflight` binary can use this Secret when it runs from the CLI.
27+
28+
```yaml
29+
# templates/preflight.yaml
30+
apiVersion: v1
31+
kind: Secret
32+
metadata:
33+
labels:
34+
troubleshoot.sh/kind: preflight
35+
name: "{{ .Release.Name }}-preflight-config"
36+
stringData:
37+
# add a preflight.yaml key under stringData
38+
preflight.yaml: |
39+
apiVersion: troubleshoot.sh/v1beta2
40+
kind: Preflight
41+
metadata:
42+
name: preflights
43+
spec:
44+
collectors: []
45+
analyzers: []
46+
```
47+
48+
1. Update `spec.collectors` and `spec.analyzers` with any collectors and analyzers that you want to use in the preflight checks for your application. For common examples, see [Examples of preflight specs](/vendor/preflight-examples).
49+
50+
For the complete list of available collectors and analyzers, see the [Collect](https://troubleshoot.sh/docs/collect/all/) and [Analyze](https://troubleshoot.sh/docs/analyze/) sections in the Troubleshoot documentation.
4951

50-
Define preflight checks in a Preflight custom resource for the following installation types:
51-
* Kubernetes manifest-based applications installed with any version of KOTS
52-
* Helm applications installed with KOTS v1.100.3 and earlier
5352
:::note
54-
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](#secret) above.
55-
56-
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.
53+
The [clusterInfo](https://troubleshoot.sh/docs/collect/cluster-info/) and [clusterResources](https://troubleshoot.sh/docs/collect/cluster-resources/) 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.
54+
55+
To use only the `clusterInfo` and `clusterResources` collectors, delete the `spec.collectors` key from the preflight spec.
5756
:::
5857

59-
Add the following YAML to a new file in a release:
60-
61-
```yaml
62-
apiVersion: troubleshoot.sh/v1beta2
63-
kind: Preflight
64-
metadata:
65-
name: preflights
66-
spec:
67-
collectors: []
68-
analyzers: []
69-
```
58+
1. Test the preflight checks by running them in a cluster using the preflight plugin and Helm CLI. For information about how to install the preflight plugin and run preflight checks, see [Run preflight checks for Helm installations](/vendor/preflight-running).
7059

71-
For more information about the Preflight custom resource, see [Preflight and Support Bundle](/reference/custom-resource-preflight).
60+
1. From the root directory of your Helm chart, package the chart into a `.tgz` archive:
7261

73-
## Step 2: Define collectors and analyzers
62+
```bash
63+
helm package --dependency-update .
64+
```
7465

75-
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.
66+
1. Add the chart archive to a new release. Promote the release to an internal development channel, and install the release in a development environment to test your changes.
7667

77-
### Collectors
68+
## (Optional) Block installation with required (strict) preflights {#strict}
7869

79-
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.
80-
81-
The following default collectors are included automatically to gather information about the cluster and cluster resources:
82-
* [clusterInfo](https://troubleshoot.sh/docs/collect/cluster-info/)
83-
* [clusterResources](https://troubleshoot.sh/docs/collect/cluster-resources/)
84-
85-
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.
86-
87-
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](https://troubleshoot.sh/docs/collect/all/) in the Troubleshoot documentation.
88-
89-
### Analyzers
90-
91-
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.
92-
93-
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`.
94-
95-
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:
96-
* [clusterPodStatuses](https://troubleshoot.sh/docs/analyze/cluster-pod-statuses/)
97-
* [clusterVersion](https://troubleshoot.sh/docs/analyze/cluster-version/)
98-
* [deploymentStatus](https://troubleshoot.sh/docs/analyze/deployment-status/)
99-
* [distribution](https://troubleshoot.sh/docs/analyze/distribution/)
100-
* [nodeResources](https://troubleshoot.sh/docs/analyze/node-resources/)
101-
* [statefulsetStatus](https://troubleshoot.sh/docs/analyze/stateful-set-status/)
102-
* [storageClass](https://troubleshoot.sh/docs/analyze/storage-class/)
103-
104-
To view all the available analyzers, see the [Analyze](https://troubleshoot.sh/docs/analyze/) section of the Troubleshoot documentation.
105-
106-
### Block installation with required (strict) preflights {#strict}
107-
108-
For applications installed with KOTS or Embedded Cluster, 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.
70+
For applications installed with a Replicated installer (Embedded Cluster, KOTS, kURL), 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.
10971

11072
:::note
11173
Strict preflight analyzers are ignored if the `exclude` property is also included and evaluates to `true`. See [exclude](https://troubleshoot.sh/docs/analyze/#exclude) in the Troubleshoot documentation.
11274
:::
11375

114-
### Examples
76+
The following image shows how a `fail` outcome is displayed when `strict: true` is set on an analyzer, which prevents installation from continuing if the preflight check fails:
77+
78+
![Preflight checks in Admin Console showing fail message with strict mode](/images/preflight-mysql-fail-strict.png)
11579

116-
For common examples of collectors and analyzers used in preflight checks, see [Examples of Preflight Specs](/vendor/preflight-examples).
80+
[View a larger version of this image](/images/preflight-mysql-fail-strict.png)

0 commit comments

Comments
 (0)