Skip to content

Add v1beta3 preflight guidance for Embedded Cluster v3 #4186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
AmberAlston wants to merge 2 commits into
base: main
Choose a base branch
from
+94 −4
Draft

Add v1beta3 preflight guidance for Embedded Cluster v3 #4186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
849b57f
Add v1beta3 preflight guidance for EC v3
AmberAlston Jun 18, 2026
1db4dd4
Add dual-spec guidance for KOTS/EC v3 transition period
AmberAlston Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions embedded-cluster/embedded-using.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,70 @@ 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. Preflight specs are packaged 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 specs work in v3

Unlike v1beta2, where preflight specs were either wrapped in a Secret inside a Helm chart or rendered separately with limited context, v1beta3 specs are rendered through Helm with the full chart context. This means your preflight spec can:

- Reference chart values and defaults (for example, `{{ .Values.postgresql.enabled }}`)
- Use Helm helper functions defined in your chart (for example, `{{ include "mychart.fullname" . }}`)
- Use `.Chart.Name` conditionals to target collectors and analyzers to specific charts in a multi-chart release

### 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, no additional gating is needed. The spec renders in that chart's context.

For releases with multiple Helm charts, gate each collector and analyzer to the chart it belongs to using `{{ if eq .Chart.Name "chart-name" }}`:

```yaml
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 }}
```

Because the spec is rendered per chart, a helper like `postgresql.v1.image` is only evaluated in the context of the `postgresql` chart where it is defined.

### 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.
Expand Down
34 changes: 30 additions & 4 deletions embedded-cluster/embedded-v3-migrate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 require `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, preflight specs are packaged outside your Helm charts as a release-level YAML file and rendered through the Helm template engine at install time. This means your preflight spec has access to the full Helm rendering context, including chart values, defaults, and helper functions. Because the spec is rendered through Helm, it uses Helm template syntax (not `repl{{ }}` Replicated template syntax).

This is why v1beta3 is required: the spec must be valid Helm template YAML, not 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. The spec is rendered once per chart in the release, each time in that chart's context.

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

Expand Down Expand Up @@ -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 your spec was wrapped 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" }}`.
- Support bundle specs do not need to be updated. 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).

Expand Down