Add v1beta3 preflight guidance for Embedded Cluster v3

embedded-cluster/embedded-using.mdx

@@ -53,6 +53,138 @@ To create an application release that supports installation with Embedded Cluste
 
 1. Install with Embedded Cluster in a development environment to test. See [Online installation with Embedded Cluster](installing-embedded) or [Air gap installation with Embedded Cluster](installing-embedded-air-gap).
 
+## Add preflight checks {#preflights}
+
+Embedded Cluster v3 uses Troubleshoot `v1beta3` for application preflight checks. You package preflight specs as a release-level YAML file outside your Helm charts. During installation and upgrades, Embedded Cluster renders the spec through the Helm template engine and runs the checks automatically.
+
+### How preflight rendering works in v3 {#preflight-rendering}
+
+Embedded Cluster renders your preflight spec through the same Helm engine it uses to install your charts. The rendering pipeline works as follows:
+
+1. Embedded Cluster takes the external preflight spec from your release.
+1. For each Helm chart in the release, Embedded Cluster injects the spec into the chart as a template and renders it with `helm template` using the same values that Helm uses during installation (SDK values, chart defaults from `values.yaml`, and user overrides from the HelmChart custom resource).
+1. Embedded Cluster merges the per-chart rendered outputs into a single resolved spec.
+1. Embedded Cluster runs the Troubleshoot preflight binary against the fully resolved spec. No additional flags or values are necessary because all Helm expressions are already evaluated.
+
+This per-chart rendering means your preflight spec has access to the full Helm context for each chart:
+
+- **Chart values and defaults**: `.Values.*` resolves against each chart's `values.yaml` defaults merged with any overrides from the HelmChart custom resource `values` key.
+- **Helm helpers**: `{{ include "mychart.fullname" . }}` resolves using the `_helpers.tpl` from the chart being rendered.
+- **Chart metadata**: `.Chart.Name`, `.Chart.Version`, `.Release.Name`, and `.Release.Namespace` are all available.
+
+If a conditional in your spec evaluates to false for a given chart (for example, `{{- if .Values.featureNotEnabled }}`), Embedded Cluster excludes those checks from that chart's rendered output. No error occurs.
+
+### Create a preflight spec
+
+Add a `troubleshoot.sh/v1beta3 Preflight` YAML file to your release at the top level (not inside any Helm chart):
+
+```yaml
+apiVersion: troubleshoot.sh/v1beta3
+kind: Preflight
+metadata:
+  name: my-app-preflights
+spec:
+  collectors:
+    - clusterResources: {}
+  analyzers:
+    - clusterVersion:
+        outcomes:
+          - fail:
+              when: "< 1.28.0"
+              message: "Kubernetes 1.28.0 or later is required."
+          - pass:
+              when: ">= 1.28.0"
+              message: "Kubernetes version is sufficient."
+```
+
+For releases with a single Helm chart, you do not need additional gating. The spec renders in that chart's context.
+
+### Multi-chart releases {#multi-chart-preflights}
+
+For releases with multiple Helm charts, gate each collector and analyzer to the chart it belongs to using `.Chart.Name` conditionals. Because Embedded Cluster renders the spec one time per chart, a `{{ if eq .Chart.Name "postgresql" }}` block only produces output when Embedded Cluster renders it in the context of the `postgresql` chart:
+
+```yaml
+apiVersion: troubleshoot.sh/v1beta3
+kind: Preflight
+metadata:
+  name: my-app-preflights
+spec:
+  collectors:
+  {{- if eq .Chart.Name "my-app" }}
+    - clusterResources: {}
+  {{- end }}
+  {{- if eq .Chart.Name "postgresql" }}
+    - run:
+        name: pg-version
+        image: '{{ include "postgresql.v1.image" . }}'
+        command: ["psql", "--version"]
+  {{- end }}
+  analyzers:
+  {{- if eq .Chart.Name "my-app" }}
+    - clusterVersion:
+        outcomes:
+          - fail:
+              when: "< 1.28.0"
+              message: "Kubernetes 1.28.0 or later is required."
+          - pass:
+              when: ">= 1.28.0"
+              message: "Kubernetes version is sufficient."
+  {{- end }}
+  {{- if eq .Chart.Name "postgresql" }}
+    - textAnalyze:
+        checkName: PostgreSQL Version
+        fileName: pg-version
+        outcomes:
+          - fail:
+              when: "< 14"
+              message: "PostgreSQL 14 or later is required."
+          - pass:
+              message: "PostgreSQL version is compatible."
+  {{- end }}
+```
+
+A helper like `postgresql.v1.image` is only evaluated in the context of the `postgresql` chart where it is defined, so it resolves correctly even though other charts in the release do not define that helper.
+
+### Conditional checks with chart values {#conditional-preflights}
+
+You can use chart values to conditionally include or exclude preflight checks. For example, if your chart has an optional component that can be enabled or disabled through values, you can gate the related preflight checks on that value:
+
+```yaml
+spec:
+  analyzers:
+    - clusterVersion:
+        outcomes:
+          - fail:
+              when: "< 1.28.0"
+              message: "Kubernetes 1.28.0 or later is required."
+          - pass:
+              message: "Kubernetes version is sufficient."
+    {{- if .Values.gpu.enabled }}
+    - nodeResources:
+        checkName: GPU Nodes Available
+        filters:
+          allocatable:
+            nvidia.com/gpu: "1"
+        outcomes:
+          - fail:
+              when: "count() < 1"
+              message: "At least one node with an NVIDIA GPU is required when GPU support is enabled."
+          - pass:
+              message: "GPU node available."
+    {{- end }}
+```
+
+If the chart's `values.yaml` has `gpu.enabled: false` and the customer has not overridden it, the GPU node check is excluded from the rendered spec.
+
+### Limitations
+
+- A release may contain at most one external preflight spec.
+- The preflight spec uses Helm template syntax, not `repl{{ }}` Replicated template syntax.
+- The spec is not valid YAML before rendering. Standard YAML linters will not validate it directly.
+- Support bundle specs are separate from preflight specs. Support bundles continue to use `v1beta2` and are not affected by this requirement.
+
+For more information about host preflight checks that Embedded Cluster runs automatically, see [Embedded Cluster host preflight checks](embedded-overview#about-host-preflight-checks).
+
 ## Set up the wizard's Configure screen {#configure-screen}
 
 During installation and upgrades, the Embedded Cluster wizard includes a **Configure** step where end customers provide configuration values for your application. This screen is defined by the [Config custom resource](/reference/custom-resource-config) in your release.

embedded-cluster/embedded-v3-migrate.mdx

@@ -23,10 +23,26 @@ Embedded Cluster v3 still requires the Replicated HelmChart v2 custom resource t
 
 Because Embedded Cluster v3 removes KOTS, you must include the [Replicated SDK](/vendor/replicated-sdk-overview) in your application to get instance reporting in the Vendor Portal from application status informers.
 
-### Troubleshoot Preflight `v1beta3` required
+### Preflight specs must use v1beta3
 
-Application preflight checks must use Troubleshoot `v1beta3`. `v1beta2` preflight specs are not supported.
-For more information, see [v1beta3 overview](https://troubleshoot.sh/docs/preflight/v1beta3-overview) in the Troubleshoot documentation.
+Application preflight checks must use API version `troubleshoot.sh/v1beta3`. Embedded Cluster v3 does not support `v1beta2` preflight specs.
+
+In v3, you package preflight specs outside your Helm charts as a release-level YAML file. Embedded Cluster renders the spec through the Helm template engine at install time, giving your preflight spec access to the full Helm rendering context, including chart values, defaults, and helper functions. Because Embedded Cluster renders the spec through Helm, the spec uses Helm template syntax (not `repl{{ }}` Replicated template syntax).
+
+v1beta3 supports this model because it treats the spec as Helm template YAML rather than a static Kubernetes resource.
+
+:::note
+**Support bundles are not affected.** Support bundle specs continue to work with `v1beta2` in Embedded Cluster v3. The v1beta3 requirement applies only to preflight specs.
+:::
+
+**Key differences from v1beta2 for preflight specs:**
+
+- The spec lives outside your Helm chart, at the release level. You do not need to wrap it in a Secret or include it in your chart's `templates/` directory.
+- The spec uses Helm template syntax (`{{ .Values.something }}`, `{{ include "helper" . }}`) instead of `repl{{ }}` Replicated template syntax.
+- The spec is not valid YAML before rendering. Standard YAML linters will not work on it directly.
+- For releases with multiple Helm charts, you can use `{{ if eq .Chart.Name "my-chart" }}` conditionals to gate specific collectors or analyzers to the chart they belong to. Embedded Cluster renders the spec one time per chart in the release, each time in that chart's context.
+
+For details about the rendering pipeline and multi-chart examples, see [Add preflight checks](embedded-using#preflights). For more information about the v1beta3 spec format, see [v1beta3 overview](https://troubleshoot.sh/docs/preflight/v1beta3-overview) in the Troubleshoot documentation.
 
 ### Package your application with Helm
 
@@ -96,7 +112,17 @@ To update a release from Embedded Cluster v2 to v3:
     In Embedded Cluster v3, these template functions replace the [LocalImageName](/reference/template-functions-config-context#localimagename), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions.
     :::
 
-1. Update your application Preflight specs to API version `troubleshoot.sh/v1beta3`. For more information, see [Migrate from v1beta2 to v1beta3](https://troubleshoot.sh/docs/preflight/v1beta3-migration) in the Troubleshoot documentation.
+1. Update your application preflight specs to API version `troubleshoot.sh/v1beta3`:
+
+   - Change `apiVersion` from `troubleshoot.sh/v1beta2` to `troubleshoot.sh/v1beta3`.
+   - Move the spec file out of your Helm chart's `templates/` directory. In v3, the preflight spec is a release-level file, not part of any chart.
+   - If you wrapped your spec in a Kubernetes Secret (the v1beta2 workaround for chart packaging), remove the Secret wrapper. The spec should be a plain `troubleshoot.sh/v1beta3 Preflight` resource.
+   - Replace any `repl{{ }}` Replicated template syntax with Helm template syntax. For example, use `{{ .Values.image.tag }}` instead of `repl{{ ConfigOption "image_tag" }}`.
+   - You do not need to update support bundle specs. They continue to work with `v1beta2` in Embedded Cluster v3.
+
+   If your release needs to support both KOTS and Embedded Cluster v3 installations during the transition period, include two preflight specs: a `v1beta2` spec for KOTS and a `v1beta3` spec for Embedded Cluster v3. KOTS ignores the `v1beta3` spec, and Embedded Cluster v3 ignores the `v1beta2` spec. Once you no longer need to support KOTS installations, you can remove the `v1beta2` spec.
+
+   For more information about the v1beta3 migration, see [Migrate from v1beta2 to v1beta3](https://troubleshoot.sh/docs/preflight/v1beta3-migration) in the Troubleshoot documentation.
 
 1. Ensure that your release has a corresponding HelmChart v2 custom resource for each of your Helm charts. See [HelmChart v2](/reference/custom-resource-helmchart-v2).