diff --git a/docs/intro.md b/docs/intro.md index c63e394b12..e4840bece8 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -196,13 +196,10 @@ pagination_next: null

Define and verify installation environment requirements.

  • - Define preflights for Helm charts + Define preflight checks
  • - Define preflights for KOTS installations -
    • -
  • - Run preflight checks for Helm installations + Run preflight checks for Helm CLI installations
  • Preflight checks lab in Instruqt diff --git a/docs/partials/preflights/_http-requests-cr.mdx b/docs/partials/preflights/_http-requests-cr.mdx new file mode 100644 index 0000000000..ab9e1a21a5 --- /dev/null +++ b/docs/partials/preflights/_http-requests-cr.mdx @@ -0,0 +1,24 @@ +```yaml +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)." +``` \ No newline at end of file diff --git a/docs/partials/preflights/_http-requests-secret.mdx b/docs/partials/preflights/_http-requests-secret.mdx new file mode 100644 index 0000000000..262501aa81 --- /dev/null +++ b/docs/partials/preflights/_http-requests-secret.mdx @@ -0,0 +1,32 @@ +```yaml +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)." +``` \ No newline at end of file diff --git a/docs/partials/preflights/_k8s-distro-cr.mdx b/docs/partials/preflights/_k8s-distro-cr.mdx new file mode 100644 index 0000000000..1783774ff0 --- /dev/null +++ b/docs/partials/preflights/_k8s-distro-cr.mdx @@ -0,0 +1,37 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_k8s-distro-secret.mdx b/docs/partials/preflights/_k8s-distro-secret.mdx new file mode 100644 index 0000000000..2442eb611b --- /dev/null +++ b/docs/partials/preflights/_k8s-distro-secret.mdx @@ -0,0 +1,45 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_k8s-version-cr.mdx b/docs/partials/preflights/_k8s-version-cr.mdx new file mode 100644 index 0000000000..cfb07a1659 --- /dev/null +++ b/docs/partials/preflights/_k8s-version-cr.mdx @@ -0,0 +1,20 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_k8s-version-secret.mdx b/docs/partials/preflights/_k8s-version-secret.mdx new file mode 100644 index 0000000000..829468c1e4 --- /dev/null +++ b/docs/partials/preflights/_k8s-version-secret.mdx @@ -0,0 +1,28 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_mysql-cr.mdx b/docs/partials/preflights/_mysql-cr.mdx new file mode 100644 index 0000000000..d94d266f94 --- /dev/null +++ b/docs/partials/preflights/_mysql-cr.mdx @@ -0,0 +1,26 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_mysql-secret.mdx b/docs/partials/preflights/_mysql-secret.mdx new file mode 100644 index 0000000000..7e21f893cf --- /dev/null +++ b/docs/partials/preflights/_mysql-secret.mdx @@ -0,0 +1,36 @@ +```yaml +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 }} +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-count-cr.mdx b/docs/partials/preflights/_node-count-cr.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/partials/preflights/_node-count-secret.mdx b/docs/partials/preflights/_node-count-secret.mdx new file mode 100644 index 0000000000..43c0e1532e --- /dev/null +++ b/docs/partials/preflights/_node-count-secret.mdx @@ -0,0 +1,24 @@ +```yaml +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 Count Check + outcomes: + - fail: + when: 'count() > {{ .Values.global.maxNodeCount }}' + message: "The cluster has more than {{ .Values.global.maxNodeCount }} nodes." + - pass: + message: You have the correct number of nodes. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-cpu-cr.mdx b/docs/partials/preflights/_node-cpu-cr.mdx new file mode 100644 index 0000000000..963f343aa7 --- /dev/null +++ b/docs/partials/preflights/_node-cpu-cr.mdx @@ -0,0 +1,17 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-cpu-secret.mdx b/docs/partials/preflights/_node-cpu-secret.mdx new file mode 100644 index 0000000000..e2fc5d6b5e --- /dev/null +++ b/docs/partials/preflights/_node-cpu-secret.mdx @@ -0,0 +1,25 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-ephem-storage-cr.mdx b/docs/partials/preflights/_node-ephem-storage-cr.mdx new file mode 100644 index 0000000000..5757a8bbe4 --- /dev/null +++ b/docs/partials/preflights/_node-ephem-storage-cr.mdx @@ -0,0 +1,21 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-ephem-storage-secret.mdx b/docs/partials/preflights/_node-ephem-storage-secret.mdx new file mode 100644 index 0000000000..e72ef0b18b --- /dev/null +++ b/docs/partials/preflights/_node-ephem-storage-secret.mdx @@ -0,0 +1,29 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-mem-cr.mdx b/docs/partials/preflights/_node-mem-cr.mdx new file mode 100644 index 0000000000..122ef6f2a1 --- /dev/null +++ b/docs/partials/preflights/_node-mem-cr.mdx @@ -0,0 +1,21 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-mem-secret.mdx b/docs/partials/preflights/_node-mem-secret.mdx new file mode 100644 index 0000000000..dff04d4e87 --- /dev/null +++ b/docs/partials/preflights/_node-mem-secret.mdx @@ -0,0 +1,29 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-req-cr.mdx b/docs/partials/preflights/_node-req-cr.mdx new file mode 100644 index 0000000000..c92be90e24 --- /dev/null +++ b/docs/partials/preflights/_node-req-cr.mdx @@ -0,0 +1,21 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-req-secret.mdx b/docs/partials/preflights/_node-req-secret.mdx new file mode 100644 index 0000000000..a91e571243 --- /dev/null +++ b/docs/partials/preflights/_node-req-secret.mdx @@ -0,0 +1,29 @@ +```yaml +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 +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-storage-cr.mdx b/docs/partials/preflights/_node-storage-cr.mdx new file mode 100644 index 0000000000..909ad15d33 --- /dev/null +++ b/docs/partials/preflights/_node-storage-cr.mdx @@ -0,0 +1,16 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_node-storage-secret.mdx b/docs/partials/preflights/_node-storage-secret.mdx new file mode 100644 index 0000000000..51324e4d33 --- /dev/null +++ b/docs/partials/preflights/_node-storage-secret.mdx @@ -0,0 +1,24 @@ +```yaml +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. +``` \ No newline at end of file diff --git a/docs/partials/preflights/_preflights-about.mdx b/docs/partials/preflights/_preflights-about.mdx deleted file mode 100644 index 131b9a53cb..0000000000 --- a/docs/partials/preflights/_preflights-about.mdx +++ /dev/null @@ -1 +0,0 @@ -You define preflight checks based on your application needs. Replicated recommends that you use preflight checks to help ensure that your customers' environments support your application before installing the application. \ No newline at end of file diff --git a/docs/partials/preflights/_preflights-add-strict.mdx b/docs/partials/preflights/_preflights-add-strict.mdx deleted file mode 100644 index 35edcb8825..0000000000 --- a/docs/partials/preflights/_preflights-add-strict.mdx +++ /dev/null @@ -1,9 +0,0 @@ -You can set any preflight analyzers to `strict: true` if you want to enforce requirements for the chosen analyzers. For more information about strict preflight checks, see [`strict`](https://troubleshoot.sh/docs/analyze/#strict) in the Troubleshoot documentation. - -Note the following considerations: - -- Any `fail` outcomes for that analyzer block the deployment of the release until your specified requirement is met. -- If a `strict` collector requires cluster scope and minimal RBAC mode is set, then the collector is skipped during the preflight check. -- Strict preflight analyzers are ignored if the `exclude` flag is also used. - - \ No newline at end of file diff --git a/docs/partials/preflights/_preflights-cr-note.mdx b/docs/partials/preflights/_preflights-cr-note.mdx deleted file mode 100644 index c8581ca6e4..0000000000 --- a/docs/partials/preflights/_preflights-cr-note.mdx +++ /dev/null @@ -1 +0,0 @@ -For more information about the Preflight custom resource, see [Preflight and Support Bundle](/reference/custom-resource-preflight). diff --git a/docs/partials/preflights/_preflights-strict.mdx b/docs/partials/preflights/_preflights-strict.mdx index 5bd8c96693..f5e5da779c 100644 --- a/docs/partials/preflights/_preflights-strict.mdx +++ b/docs/partials/preflights/_preflights-strict.mdx @@ -2,4 +2,4 @@ If any strict preflight checks are configured, the `--skip-preflights` flag are When the `--deploy` option is provided and there are strict preflight checks, the preflight checks always run. The deployment waits for up to 15 minutes for the preflight checks to complete. If the checks complete without strict preflight failures, the release deploys. If the checks do not complete within 15 minutes, the release does not deploy. If there are one or more strict preflight failures, the release does not deploy. -For more information about strict preflight checks, see [Define KOTS Preflight Checks](/vendor/preflight-kots-defining). \ No newline at end of file +For more information about strict preflight checks, see [Defining Preflight Checks](/vendor/preflight-defining). \ No newline at end of file diff --git a/docs/reference/kots-cli-install.md b/docs/reference/kots-cli-install.md index 35421b83af..70873d90c0 100644 --- a/docs/reference/kots-cli-install.md +++ b/docs/reference/kots-cli-install.md @@ -43,7 +43,7 @@ This command supports all [global flags](kots-cli-global-flags) and also: | `--set` | strings| Values to pass to Helm when running `helm template`. | | `--shared-password` | string | Shared password to use when deploying the admin console. | | `--skip-compatibility-check`| bool | Set to `true` to skip compatibility checks between the current KOTS version and the application. **Default:** `false` | -| `--skip-preflights` | bool | Set to `true` to skip preflight checks. **Default:** `false`. If any strict preflight checks are configured, the `--skip-preflights` flag is not honored because strict preflight checks must run and contain no failures before the application is deployed. For more information, see [Define KOTS Preflight Checks](/vendor/preflight-kots-defining).| +| `--skip-preflights` | bool | Set to `true` to skip preflight checks. **Default:** `false`. If any strict preflight checks are configured, the `--skip-preflights` flag is not honored because strict preflight checks must run and contain no failures before the application is deployed. For more information, see [Defining Preflight Checks](/vendor/preflight-defining).| | `--skip-rbac-check` | bool | Set to `true` to bypass RBAC check. **Default:** `false`| | `--skip-registry-check` | bool | Set to `true` to skip the connectivity test and validation of the provided registry information. **Default:** `false`| | `--strict-security-context` | bool | Set to `true` to explicitly enable explicit security contexts for all KOTS pods and containers. **Default:** `false`. **Note**: Might not work for some storage providers. | diff --git a/docs/vendor/distributing-workflow.md b/docs/vendor/distributing-workflow.md index d31fa83aab..962006e91b 100644 --- a/docs/vendor/distributing-workflow.md +++ b/docs/vendor/distributing-workflow.md @@ -48,10 +48,7 @@ For more information about creating releases, see [Managing Releases with the Ve Preflight and SupportBundle

    Define preflight checks to test for system compliance during the installation process and reduce the number of support escalations.

    Enable customers to quickly collect and analyze troubleshooting data from their clusters to help you diagnose problems with application deployments.

    Note: If you are using Helm charts, define the preflight and support bundle specifications within the Helm chart rather than creating custom resources.

    - + Define Preflight Checks @@ -60,9 +57,7 @@ For more information about creating releases, see [Managing Releases with the Ve

    Create a configuration screen in the admin console to collect required and optional configuration values from your users.

    Note: This feature does not apply to Kubernetes Operators.

    - - Creating and Editing Configuration Fields - + Creating and Editing Configuration Fields Application diff --git a/docs/vendor/licenses-referencing-fields.md b/docs/vendor/licenses-referencing-fields.md index c01cbcf409..434f5fd78a 100644 --- a/docs/vendor/licenses-referencing-fields.md +++ b/docs/vendor/licenses-referencing-fields.md @@ -49,7 +49,7 @@ In the example above, the preflight check uses the `nodeResources` analyzer and For more information about this example, see [How Can I Use License Custom Fields Value in a Pre-Flight Check?](https://help.replicated.com/community/t/how-can-i-use-license-custom-fields-value-in-a-pre-flight-check/624) in Replicated Community. -For more information about defining preflight checks for applications installed with KOTS, see [Define Preflight Checks for KOTS](preflight-kots-defining). +For more information about defining preflight checks, see [Defining Preflight Checks](preflight-defining). ## Query License Fields at Runtime {#runtime} diff --git a/docs/vendor/packaging-embedded-kubernetes.md b/docs/vendor/packaging-embedded-kubernetes.md index 75308b676f..1735830e6d 100644 --- a/docs/vendor/packaging-embedded-kubernetes.md +++ b/docs/vendor/packaging-embedded-kubernetes.md @@ -102,7 +102,7 @@ Note the following requirements and guidelines for Kubernetes installers: - (Introduced in kURL v2021.09.24-0) After you configure a Kubernetes installer, Replicated recommends that you customize host preflight checks to support the installation experience with kURL. Host preflight checks help ensure successful installation and the ongoing health of the cluster. For more information about customizing host preflight checks, see [Customizing Host Preflight Checks for Kubernetes Installers](preflight-host-preflights). -- (Introduced in Replicated KOTS v1.74.0) For Installers included in a release, Replicated recommends that you define a preflight check in the release to ensure that the target Kubernetes installer is deployed before the release is installed. For more information about how to define preflight checks, see [Define KOTS Preflight Checks](preflight-kots-defining). +- (Introduced in Replicated KOTS v1.74.0) For Installers included in a release, Replicated recommends that you define a preflight check in the release to ensure that the target Kubernetes installer is deployed before the release is installed. For more information about how to define preflight checks, see [Defining Preflight Checks](preflight-defining). For example, the following preflight check uses the `yamlCompare` analyzer with the `kots.io/installer: "true"` annotation to compare the target Kubernetes installer that is included in the release against the Kubernetes installer that is currently deployed in the customer's environment. For more information about the `yamlCompare` analyzer, see [`yamlCompare`](https://troubleshoot.sh/docs/analyze/yaml-compare/) in the open source Troubleshoot documentation. diff --git a/docs/vendor/packaging-rbac.md b/docs/vendor/packaging-rbac.md index cc56e1572c..4ed42af239 100644 --- a/docs/vendor/packaging-rbac.md +++ b/docs/vendor/packaging-rbac.md @@ -96,7 +96,7 @@ The following limitations apply when using the `requireMinimalRBACPrivileges` or * **Existing clusters only**: The `requireMinimalRBACPrivileges` and `supportMinimalRBACPrivileges` options apply only to installations in existing clusters. -* **Preflight checks**: When namespace-scoped access is enabled, preflight checks cannot read resources outside the namespace where KOTS is installed. The preflight checks continue to function, but return less data. For more information, see [Define KOTS Preflight Checks](/vendor/preflight-kots-defining). +* **Preflight checks**: When namespace-scoped access is enabled, preflight checks cannot read resources outside the namespace where KOTS is installed. The preflight checks continue to function, but return less data. For more information, see [Defining Preflight Checks](/vendor/preflight-defining). * **Velero namespace access**: Namespace-scoped RBAC does not grant access to the namespace where Velero is installed in the cluster. Velero is a requirement for configuring backup and restore with snapshots. diff --git a/docs/vendor/preflight-defining.md b/docs/vendor/preflight-defining.md new file mode 100644 index 0000000000..86b17bec60 --- /dev/null +++ b/docs/vendor/preflight-defining.md @@ -0,0 +1,323 @@ +import HttpSecret from "../partials/preflights/_http-requests-secret.mdx" +import HttpCr from "../partials/preflights/_http-requests-cr.mdx" +import MySqlSecret from "../partials/preflights/_mysql-secret.mdx" +import MySqlCr from "../partials/preflights/_mysql-cr.mdx" +import K8sVersionSecret from "../partials/preflights/_k8s-version-secret.mdx" +import K8sVersionCr from "../partials/preflights/_k8s-version-cr.mdx" +import K8sDistroSecret from "../partials/preflights/_k8s-distro-secret.mdx" +import K8sDistroCr from "../partials/preflights/_k8s-distro-cr.mdx" +import NodeReqSecret from "../partials/preflights/_node-req-secret.mdx" +import NodeReqCr from "../partials/preflights/_node-req-cr.mdx" +import NodeCountSecret from "../partials/preflights/_node-count-secret.mdx" +import NodeCountCr from "../partials/preflights/_node-count-cr.mdx" +import NodeMemSecret from "../partials/preflights/_node-mem-secret.mdx" +import NodeMemCr from "../partials/preflights/_node-mem-cr.mdx" +import NodeStorageClassSecret from "../partials/preflights/_node-storage-secret.mdx" +import NodeStorageClassCr from "../partials/preflights/_node-storage-cr.mdx" +import NodeEphemStorageSecret from "../partials/preflights/_node-ephem-storage-secret.mdx" +import NodeEphemStorageCr from "../partials/preflights/_node-ephem-storage-cr.mdx" +import NodeCpuSecret from "../partials/preflights/_node-cpu-secret.mdx" +import NodeCpuCr from "../partials/preflights/_node-cpu-cr.mdx" +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Defining Preflight Checks + +This topic describes how to define preflight checks in Helm chart- and standard Kubernetes manifest-based applications. 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 chart- or standard manifest-based) and installation method (Helm CLI or KOTS). + +Use the following table to determine which type of manifest file to use for defining preflight checks: + + + + + + + + + + + + + + + + + + + + +
    Helm CLIKOTS v1.101.0 and LaterKOTS v1.100.3 and Earlier
    Helm Chart-Based ApplicationKubernetes SecretKubernetes SecretPreflight Custom Resource
    Standard Manifest-Based ApplicationN/APreflight Custom ResourcePreflight Custom Resource
    + +### Create a Secret {#secret} + +You can define preflight check specifications in a Kubernetes Secret for the following installation types: +* Installations with the Helm CLI +* Helm chart-based applications installed with KOTS v1.101.0 and later + +Add the following YAML to a Kubernetes Secret in your Helm chart `templates` directory: + +```yaml +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 + +### (KOTS Only) Create a Preflight Custom Resource {#preflight-cr} + +You can define preflight check specifications in a Preflight custom resource for the following installation types: +* Standard manifest-based applications installed with KOTS +* Helm chart-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](#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: + +```yaml +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](/reference/custom-resource-preflight). + +## 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](#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: +* [clusterInfo](https://troubleshoot.sh/docs/collect/cluster-info/) +* [clusterResources](https://troubleshoot.sh/docs/collect/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](https://troubleshoot.sh/docs/collect/all/) 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](https://troubleshoot.sh/docs/analyze/cluster-pod-statuses/) +* [clusterVersion](https://troubleshoot.sh/docs/analyze/cluster-version/) +* [deploymentStatus](https://troubleshoot.sh/docs/analyze/deployment-status/) +* [distribution](https://troubleshoot.sh/docs/analyze/distribution/) +* [nodeResources](https://troubleshoot.sh/docs/analyze/node-resources/) +* [statefulsetStatus](https://troubleshoot.sh/docs/analyze/stateful-set-status/) +* [storageClass](https://troubleshoot.sh/docs/analyze/storage-class/) + +To view all the available analyzers, see the [Analyze](https://troubleshoot.sh/docs/analyze/) section of the Troubleshoot documentation. + +### (KOTS Only) `strict` Analyzers + +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. For more information, see [strict](https://troubleshoot.sh/docs/analyze/#strict) in the Troubleshoot documentation. + +:::note +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. +::: + +## Example Specifications + +This section includes common examples of preflight check specifications. For more examples, see the [Troubleshoot example repository](https://github.com/replicatedhq/troubleshoot/tree/main/examples/preflight) in GitHub. + +### Check HTTP or HTTPS Requests from the Cluster + +The examples below use the `http` collector and the `regex` 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](https://troubleshoot.sh/docs/collect/http/) and [Regular Expression](https://troubleshoot.sh/docs/analyze/regex/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how the pass outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing pass message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/analyze/cluster-version/) and [Cluster Info](https://troubleshoot.sh/docs/collect/cluster-info/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how the warn outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing warning message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-info/) and [Distribution](https://troubleshoot.sh/docs/analyze/distribution/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how the pass outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing pass message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/mysql/) and [Analyze > MySQL](https://troubleshoot.sh/docs/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.

    + +     + +

    This example uses Replicated 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.

    + +

    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:

    + Strict preflight checks in admin console showing fail message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how a warn outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing warn message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how a fail outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing fail message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how a pass outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing pass message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how the fail outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing fail message + View a larger version of this image +     +     + +### 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. + + + + + + + +

    The following shows how the pass outcome for this preflight check is displayed in the admin console during KOTS installation or upgrade:

    + Preflight checks in admin console showing fail message + View a larger version of this image +     +     \ No newline at end of file diff --git a/docs/vendor/preflight-helm-defining.md b/docs/vendor/preflight-helm-defining.md deleted file mode 100644 index 9e5d4a3287..0000000000 --- a/docs/vendor/preflight-helm-defining.md +++ /dev/null @@ -1,242 +0,0 @@ -import PreflightsAddAnalyzers from "../partials/preflights/_preflights-add-analyzers.mdx" -import PreflightsSpecLocations from "../partials/preflights/_preflights-spec-locations.mdx" -import PreflightsAbout from "../partials/preflights/_preflights-about.mdx" -import PreflightsDefine from "../partials/preflights/_preflights-define.mdx" -import PreflightsDefineXref from "../partials/preflights/_preflights-define-xref.mdx" -import PreflightsCrNote from "../partials/preflights/_preflights-cr-note.mdx" -import AnalyzersNote from "../partials/preflights/_analyzers-note.mdx" -import RedactorsAbout from "../partials/redactors/_redactors-about.mdx" -import PreflightSbHelmTemplates from "../partials/preflights/_preflight-sb-helm-templates.mdx" -import ConfigmapNote from "../partials/support-bundles/_configmap-note.mdx" - -# Define Preflight Checks for Helm Charts - -This topic provides a basic understanding and some key considerations about preflight checks for Helm charts with KOTS and Helm installations, and to help guide you in defining them for your application. - -:::note -A KOTS entitlement is required to create KOTS releases. -::: - -## About Preflight Checks for Helm Charts - - - -Preflight checks are not included by default, so you must enable them. - -For Helm installations, preflight checks run using a `helm template` command before running the installation to confirm the target cluster has the resources required for a successful installation. For more information about running the `helm install` command, see [Running Preflight Checks for Helm Installations](preflight-running). - -For KOTS installations with Helm charts, preflight checks run automatically. - -## Choose an Input Kind - -You run preflight checks with the open source preflight kubectl plugin. For information about the preflight plugin, see [Getting Started](https://troubleshoot.sh/docs/) in the open source Troubleshoot documentation. - -The plugin requires a preflight check specification as input. For Helm installations, you provide this specification by running `helm template` to produce a stream of stdout and pipe the result to `preflight -`. The preflight plugin automatically finds and runs preflight specifications by filtering the stream of stdout for the following input kinds: - -- Secret (`kind: Secret`) -- ConfigMap (`kind: ConfigMap`) -- Preflight custom resource (`kind: Preflight`) - -All of these input options allow customization of preflight checks based on values unique to the customer, using Helm templates with conditional statements. - -In KOTS v1.101.0 and later, a KOTS installation looks for the preflights specified in the Helm chart archive. - -### Create a Secret (Recommended) - -Replicated recommends writing your preflight checks specification in one or more Secrets. Using Secrets protects secure information in a cluster. - - - -To create a Secret for the preflight checks specification: - -1. Create a Secret as a YAML file with `kind: Secret` and `apiVersion: v1`. 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 - - **Template:** - - ```yaml - 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: [] - ``` - -1. Add the Secret to your Helm chart `templates/` directory. - -Next, define the preflight checks specification by adding collectors and analyzers. For more information, see [Define the Preflight Checks Specification](#preflights). - -### Create a Preflight Custom Resource - -The Preflight custom resource lets you provide preflight checks in a Helm template without using `stringData`. If you use this input kind, you must use conditional statements because the custom resource definition is not installed in the cluster. - - - -To define a Preflight custom resource as a template: - -1. Create a Preflight custom resource YAML file using `kind: Preflight`. Wrap the custom resource template in an `{{ if` so that it is only rendered when specified in the `values.yaml` file or on the Helm CLI. - - **Example**: - - ```yaml - {{ if .Values.renderpreflights }} - apiVersion: troubleshoot.sh/v1beta2 - kind: Preflight - metadata: - name: example-name - spec: - collectors: [] - analyzers: [] - {{ end }} - ``` - -1. Configure your `values.yaml` file to enable the Preflight custom resource. - - **Example:** - - ```yaml - renderpreflights: true - ``` - -Next, define the preflight checks specification by adding collectors and analyzers. Optionally, you can add to the default redactors. For more information, see [Define the Preflight Checks Specification](#preflights). - -## Define the Preflight Checks Specification {#preflights} - - - - - - - - -### Collectors - -Add collectors to define information to be collected for analysis during the analyze phase. For example, you can collect information about the MySQL version that is running in a cluster: - -```yaml -spec: - {{ if eq .Values.global.mariadb.enabled false }} - 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 }} -``` - -A Helm template is used for the URI field to avoid exposing sensitive information. The Helm template maps to the `values.yaml` file to populate the connection string for the MySQL database. - - - -### Analyzers - - - -The following example shows an analyzer for the MySQL collector above. This analyzer specifies a `fail` outcome if the MySQL version is less than the minimum required. Then, specify a message to display that informs your customer of the reasons for the failure and steps they can take to fix the issue. - -```yaml -spec: - 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' - analyzers: - - 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 -``` - - - - -## Example - -The following example shows a preflight specification in a Secret for a Helm installation. For more examples, see the [Troubleshoot example repository](https://github.com/replicatedhq/troubleshoot/tree/main/examples/preflight) in GitHub. - - - -```yaml -apiVersion: v1 -kind: Secret -metadata: - labels: - troubleshoot.sh/kind: preflight - name: "{{ .Release.Name }}-preflight-config" -stringData: - # This is the preflight spec that will be used to run the preflight checks - # Note: here we demonstrate using Helm's templating to conditionally run a preflight check based on a value - # plus getting some configuration from the local values.yaml file - preflight.yaml: | - apiVersion: troubleshoot.sh/v1beta2 - kind: Preflight - metadata: - name: preflight-sample - spec: - {{ if eq .Values.global.mariadb.enabled false }} - 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: - - nodeResources: - checkName: Node Count Check - outcomes: - - fail: - when: 'count() > {{ .Values.global.maxNodeCount }}' - message: "The cluster has more than {{ .Values.global.maxNodeCount }} nodes." - - pass: - message: You have the correct number of nodes. - - clusterVersion: - outcomes: - - fail: - when: "< 1.22.0" - message: The application requires at least Kubernetes 1.22.0, and recommends 1.23.0. - uri: https://kubernetes.io - - warn: - when: "< 1.23.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. - {{ if eq .Values.global.mariadb.enabled false }} - - 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 }} -``` - -## Next Step - -Test your preflight checks in a development environment. For more information, see [Running Helm Preflight Checks](preflight-running). - - diff --git a/docs/vendor/preflight-kots-defining.md b/docs/vendor/preflight-kots-defining.md deleted file mode 100644 index 1f0c6663fe..0000000000 --- a/docs/vendor/preflight-kots-defining.md +++ /dev/null @@ -1,406 +0,0 @@ -import PreflightsAddAnalyzers from "../partials/preflights/_preflights-add-analyzers.mdx" -import PreflightsAddStrict from "../partials/preflights/_preflights-add-strict.mdx" -import PreflightsSpecLocations from "../partials/preflights/_preflights-spec-locations.mdx" -import PreflightsAbout from "../partials/preflights/_preflights-about.mdx" -import PreflightsDefine from "../partials/preflights/_preflights-define.mdx" -import PreflightsDefineXref from "../partials/preflights/_preflights-define-xref.mdx" -import PreflightsCrNote from "../partials/preflights/_preflights-cr-note.mdx" -import AnalyzersNote from "../partials/preflights/_analyzers-note.mdx" - -# Define Preflight Checks for KOTS - -This topic provides information about creating preflight checks for releases that are distributed with Replicaed KOTS and that use standard Kubernetes manifests or Kubernetes Operators. For information about defining preflight checks for Helm chart-based applications, see [Define Preflight Checks for Helm Charts](preflight-helm-defining). - -For information about defining host preflight checks for Replicated kURL, see [Customizing Host Preflight Checks for kURL](preflight-host-preflights). - -## Define the Preflight Checks Specification - -Preflight checks are not included by default. For releases that use standard Kubernetes manifests or Kubernetes Operators, you can add a Preflight custom resource to your release to define preflight checks. - -The following is an empty template for the Preflight custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: Preflight`): - -```yaml -apiVersion: troubleshoot.sh/v1beta2 -kind: Preflight -metadata: - name: preflights -spec: - collectors: [] - analyzers: [] -``` - - - -:::note ->Introduced in KOTS v1.101.0 - -If you have already created a KOTS release using Helm charts and want to add support for Helm CLI installations, Replicated recommends defining preflight checks directly in the Helm charts instead of using the Preflight custom resource. This lets you maintain one set of preflight specifications for all installation types. - -Preflights specified in the Helm chart override the Preflight custom resource used by KOTS. During installation, if KOTS cannot find preflights specified in the Helm chart archive, then KOTS searches for `kind: Preflight` in the root of the release. For more information, see [Define Preflight Checks for Helm Charts](preflight-helm-defining). -::: - -### Collectors - -Add collectors to 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 default `clusterInfo` and `clusterResources` collectors are always automatically included in the specification to gather information about the cluster and cluster resources. You do not need to manually included these default collectors. For more information, see [Cluster Info](https://troubleshoot.sh/docs/collect/cluster-info/) and [Cluster Resources](https://troubleshoot.sh/docs/collect/cluster-resources/) in the Troubleshoot documentation. - -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 that you can add, see [All Collectors](https://troubleshoot.sh/docs/collect/all/) 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 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](https://troubleshoot.sh/docs/analyze/cluster-pod-statuses/) -* [clusterVersion](https://troubleshoot.sh/docs/analyze/cluster-version/) -* [deploymentStatus](https://troubleshoot.sh/docs/analyze/deployment-status/) -* [distribution](https://troubleshoot.sh/docs/analyze/distribution/) -* [nodeResources](https://troubleshoot.sh/docs/analyze/node-resources/) -* [statefulsetStatus](https://troubleshoot.sh/docs/analyze/stateful-set-status/) -* [storageClass](https://troubleshoot.sh/docs/analyze/storage-class/) - -To view all the available analyzers, see the [Analyze](https://troubleshoot.sh/docs/analyze/) section of the Troubleshoot documentation. - -### `strict` Analyzers - - - -For more information about cluster privileges, see `requireMinimalRBACPrivileges` for name-scoped access in [Configuring Role-Based Access](packaging-rbac#namespace-scoped-access). - -## Example Specifications - -This section includes common examples of preflight check specifications. For more examples, see the [Troubleshoot example repository](https://github.com/replicatedhq/troubleshoot/tree/main/examples/preflight) in GitHub. - -### Check HTTP or HTTPS Requests from the Cluster - -The following example uses the `http` collector and the `regex` 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](https://troubleshoot.sh/docs/collect/http/) and [Regular Expression](https://troubleshoot.sh/docs/analyze/regex/) in the Troubleshoot documentation. - - -```yaml -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 an example of how the `pass` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing pass message](/images/preflight-http-pass.png) - -[View a larger version of this image](/images/preflight-http-pass.png) - -### Check Kubernetes Version - -The following example uses 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](https://troubleshoot.sh/docs/analyze/cluster-version/) and [Cluster Info](https://troubleshoot.sh/docs/collect/cluster-info/) in the Troubleshoot documentation. - -```yaml -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 an example of how the `warn` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing warning message](/images/preflight-k8s-version-warn.png) - -[View a larger version of this image](/images/preflight-k8s-version-warn.png) - -### Check Kubernetes Distribution - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-info/) and [Distribution](https://troubleshoot.sh/docs/analyze/distribution/) in the Troubleshoot documentation. - -```yaml -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 an example of how the `pass` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing pass message](/images/preflight-k8s-distro.png) - -[View a larger version of this image](/images/preflight-k8s-distro.png) - -### Check Requirements Are Met By At Least One Node - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. - -```yaml -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 an example of how the `fail` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing fail message](/images/preflight-node-filters-faill.png) - -[View a larger version of this image](/images/preflight-node-filters-faill.png) - -### Check MySQL Version Using Replicated Template Functions - -The following example uses the `mysql` collector and the `mysql` analyzer to check the version of MySQL running in the cluster. - -For more information, see [Collect > MySQL](https://troubleshoot.sh/docs/collect/mysql/) and [Analyze > MySQL](https://troubleshoot.sh/docs/analyze/mysql/) in the Troubleshoot documentation. - -This example uses Replicated 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](/reference/template-functions-about). - -This example also uses an analyzer with `strict: true`, which prevents installation from continuing if the preflight check fails. - -```yaml -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 an example of how a `fail` outcome for this preflight check is displayed in the admin console when `strict: true` is set for the analyzer: - -![Strict preflight checks in admin console showing fail message](/images/preflight-mysql-fail-strict.png) - -[View a larger version of this image](/images/preflight-mysql-fail-strict.png) - - -### Check Node Memory - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. - -```yaml -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 an example of how a `warn` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing warn message](/images/preflight-node-memory-warn.png) - -[View a larger version of this image](/images/preflight-node-memory-warn.png) - -### Check Node Storage Class Availability - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. - -```yaml -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 an example of how a `fail` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing fail message](/images/preflight-storageclass-fail.png) - -[View a larger version of this image](/images/preflight-storageclass-fail.png) - -### Check Node Ephemeral Storage - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. - -```yaml -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 an example of how a `pass` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing pass message](/images/preflight-ephemeral-storage-pass.png) - -[View a larger version of this image](/images/preflight-ephemeral-storage-pass.png) - -### Check Total CPU Cores Across Nodes - -The following example uses 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](https://troubleshoot.sh/docs/collect/cluster-resources/) and [Node Resources](https://troubleshoot.sh/docs/analyze/node-resources/) in the Troubleshoot documentation. - -```yaml -apiVersion: troubleshoot.sh/v1beta2 -kind: Preflight -metadata: - name: my-app -spec: - collectors: - 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 an example of how a `pass` outcome for this preflight check is displayed in the admin console: - -![Preflight checks in admin console showing pass message](/images/preflight-cpu-pass.png) - -[View a larger version of this image](/images/preflight-cpu-pass.png) - -## Next Step - -Save and promote the release to a development environment to test your changes. For more information about installing with KOTS, see [About Installing an Application](/enterprise/installing-overview). \ No newline at end of file diff --git a/docs/vendor/preflight-running.md b/docs/vendor/preflight-running.md index 7393f3ecf2..86f4eb817f 100644 --- a/docs/vendor/preflight-running.md +++ b/docs/vendor/preflight-running.md @@ -1,52 +1,115 @@ # Running Preflight Checks for Helm Installations -You can run Helm preflight checks before running `helm install` and during the installation of an application. Additionally, your preflight checks can include one or more specification types and resources. +This topic describes how to use the preflight kubectl plugin to run preflight checks for applications installed with the Helm CLI. + +## Overview + +For applications installed with the Helm CLI, your users can optionally run preflight checks using the open source preflight kubectl plugin before they run `helm install`. + +The preflight plugin requires a preflight check specification as input. For Helm chart-based applications, the specification is defined in a Secret in the Helm chart `templates` directory. For information about how to configure preflight checks for your application, see [Defining Preflight Checks](preflight-defining). + +To run preflight checks that are defined in your application Helm chart templates, your users run `helm template` to render the Helm chart templates and then provide the result to the preflight plugin as stdin. The preflight plugin automatically filters the stream of stdout from the `helm template` command to find and run any preflight specifications. ## Prerequisite -Customers must install the preflight plug-in, which is a client-side utility that adds a single binary to their path. +The preflight kubectl plugin is required to run preflight checks for Helm CLI installations. The preflight plugin is a client-side utility that adds a single binary to the path. + +To install the preflight plugin, run the following command to install the preflight plug-in using krew: + +``` +curl https://krew.sh/preflight | bash +``` +For information about the preflight plugin, including additional installation options, see [Getting Started](https://troubleshoot.sh/docs/) in the open source Troubleshoot documentation. + +## Command + +``` +helm template HELM_CHART | kubectl preflight - +``` + +Where `HELM_CHART` is the Helm chart that contains the preflight specification. + +For all available options with this command, see [Run Preflight Checks using the CLI](https://troubleshoot.sh/docs/preflight/cli-usage/#options) in the open source Troubleshoot documentation. + +**Examples:** + +``` +helm template gitea-1.0.6.tgz | kubectl preflight - +``` +``` +helm template gitea | kubectl preflight - +``` +``` +helm template oci://myregistry.io/org/examplechart | kubectl preflight - +``` + +## Run Preflight Checks from a Release + +When you promote a release that contains one or more Helm charts, the Helm charts are automatically pushed to the Replicated registry. To run preflight checks before installing a release, your users must first log in to the Replicated registry where they can access your application Helm chart containing the preflight specification. + +To run preflights checks from a release before installation: + +1. In the [vendor portal](https://vendor.replicated.com/apps/gitea-boxer/customers), go to the **Customers** page. Click on the name of the target customer. + +1. On the landing page for the customer, click **Helm install instructions**. + + The **Helm install instructions** dialog opens: + + Helm install instructions dialog with preflight checks + + [View a larger version of this image](/images/helm-install-preflights.png) + +1. Run the commands provided in the dialog: + + 1. Run the first command to log in to the Replicated registry: -To install the preflight plug-in: + ``` + helm registry login registry.replicated.com --username USERNAME --password PASSWORD + ``` -1. Log in to the registry where the Helm chart and preflight specification were pushed to: + Where: + - `USERNAME` is the customer's email address. + - `PASSWORD` is the customer's license ID. - ``` - helm registry login REGISTRY_DOMAIN --username USERNAME --password PASSWORD - ``` + **Example:** + ``` + helm registry login registry.replicated.com --username example@companyname.com password 1234abcd + ``` - Replace: + 1. Run the second command to install the kubectl plugin with krew: - - `REGISTRY_DOMAIN` with the registry domain that contains the Helm chart. - - `USERNAME` with the username that has access to the registry. - - `PASSWORD` with the password for the registry. + ``` + curl https://krew.sh/preflight | bash + ``` + + 1. Run the third command to run preflight checks: -1. Run the following command to install the preflight plug-in using krew: - ``` - curl https://krew.sh/preflight | bash - ``` + ``` + helm template oci://registry.replicated.com/APP_SLUG/CHANNEL/CHART | kubectl preflight - + ``` -## Run Preflight Checks + Where: + - `APP_SLUG` is the name of the application. + - `CHANNEL` is the lowercased name of the release channel. + - `CHART` is the name of the Helm chart. -Before running the `helm install` command, your customers run the preflight checks to verify that their environments meet the installation requirements before they run the actual installation. + **Examples:** -The output shows the success, warning, or fail message for each preflight check, depending on how they were configured. You can ask customers to send you the results of the preflight checks if needed. + ``` + helm template oci://registry.replicated.com/gitea-app/unstable/gitea | kubectl preflight - + ``` + ``` + helm template oci://registry.replicated.com/gitea-app/unstable/gitea --values values.yaml | kubectl preflight - + ``` -- To run the basic `preflight` command: + For all available options with this command, see [Run Preflight Checks using the CLI](https://troubleshoot.sh/docs/preflight/cli-usage/#options) in the open source Troubleshoot documentation. - ``` - helm template oci://REGISTRY/APP_NAME/CHANNEL/CHART | kubectl preflight - - ``` + 1. (Optional) Run the fourth command to install the application. For more information, see [Installing with Helm](install-with-helm). -- If preflight checks are dependent on customer values, run the preflights using the values file to override chart defaults: +## (Optional) Save Preflight Check Results - ``` - helm template oci://REGISTRY/APP_NAME/CHANNEL/CHART --values FILENAME.yaml | kubectl preflight - - ``` +The output of the preflight plugin shows the success, warning, or fail message for each preflight, depending on how they were configured. You can ask your users to send you the results of the preflight checks if needed. - Replace: +To save the results of preflight checks to a `.txt` file, users can can press `s` when viewing the results from the CLI, as shown in the example below: - - `REGISTRY` with the registry domain where your Helm chart is located. This can be the Replicated registry or a custom domain. - - `APP_NAME` with the name of the application. - - `CHANNEL` with the release channel. - - `CHART` with the name of the Helm chart. - - `FILENAME` with the name of the values file. +![Save output dialog](/images/helm-preflight-save-output.png) diff --git a/docs/vendor/preflight-support-bundle-about.md b/docs/vendor/preflight-support-bundle-about.md index cbf980424c..def63250fc 100644 --- a/docs/vendor/preflight-support-bundle-about.md +++ b/docs/vendor/preflight-support-bundle-about.md @@ -66,9 +66,7 @@ Analyzer outcomes for preflight checks differ from the outcomes for support bund To use preflight checks and support bundles with your application, you define collectors and analyzers in a YAML specification. Using multiple specifications is supported. For more information about using multiple specifications for preflight or support bundles, see [About Modular Specifications](support-modular-support-bundle-specs). For information about how to write the specifications, see: - - - [Define Preflight Checks for Helm Charts](preflight-helm-defining) - - [Define Preflight Checks for KOTS](preflight-kots-defining) + - [Defining Preflight Checks](preflight-defining) - [Customize Support Bundles for Helm Installations](support-bundle-helm-customizing) - [Customize Support Bundles for KOTS](support-bundle-kots-customizing) diff --git a/docs/vendor/replicated-onboarding.md b/docs/vendor/replicated-onboarding.md index ef2ce8cdc5..cdfe6825ce 100644 --- a/docs/vendor/replicated-onboarding.md +++ b/docs/vendor/replicated-onboarding.md @@ -227,7 +227,7 @@ This section provides a checklist of key Replicated features to integrate with y diff --git a/netlify.toml b/netlify.toml index 8d74be4a6b..447fd434d2 100644 --- a/netlify.toml +++ b/netlify.toml @@ -146,7 +146,15 @@ [[redirects]] from="https://docs.replicated.com/vendor/helm-kots-using-sdk" - to="https://docs.replicated.com/vendor/helm-native-about" + to="https://docs.replicated.com/vendor/helm-native-about" + +[[redirects]] + from="https://docs.replicated.com/vendor/preflight-kots-defining" + to="https://docs.replicated.com/vendor/preflight-defining" + +[[redirects]] + from="https://docs.replicated.com/vendor/preflight-helm-defining" + to="https://docs.replicated.com/vendor/preflight-defining" ################################################### # Redirects To the Enterprise Section diff --git a/sidebars.js b/sidebars.js index 4e8fa214dc..909e75e0bd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -568,8 +568,7 @@ const sidebars = { type: 'category', label: 'Preflight Checks', items: [ - 'vendor/preflight-helm-defining', - 'vendor/preflight-kots-defining', + 'vendor/preflight-defining', 'vendor/preflight-running', ], }, diff --git a/static/images/helm-install-preflights.png b/static/images/helm-install-preflights.png new file mode 100644 index 0000000000..ff40758313 Binary files /dev/null and b/static/images/helm-install-preflights.png differ diff --git a/static/images/helm-preflight-save-output.png b/static/images/helm-preflight-save-output.png new file mode 100644 index 0000000000..c1266ad142 Binary files /dev/null and b/static/images/helm-preflight-save-output.png differ