From 817a757ecea74343bf57d1182978408d360eadb1 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Fri, 18 Sep 2026 14:15:53 -0600 Subject: [PATCH] fix(docs): scope the v1beta3 requirement to the Preflight kind The docs say Embedded Cluster v3 requires preflight specs to use troubleshoot.sh/v1beta3, but that requirement is scoped to the Preflight custom resource. Troubleshoot has no v1beta3 HostPreflight, so host preflight specs stay v1beta2 on every product including v3. A vendor writing a custom host preflight for v3 had no way to tell. Qualify the statement everywhere it appeared, and state the carve-out as a list of kinds rather than a concept, so a reader sees HostPreflight named explicitly instead of inferring it from silence. Also replace the hand-copied note in the Preflight reference with an import of the shared partial, so the two cannot drift again. The migration page heading keeps its original anchor, which seven pages link to. Co-Authored-By: Claude Opus 5 --- docs/partials/preflights/_ec-v3-v1beta3-note.mdx | 4 +++- docs/reference/custom-resource-about.md | 2 +- docs/reference/custom-resource-preflight.md | 6 +++--- docs/reference/custom-resource-redactor.md | 2 +- docs/vendor/licenses-referencing-fields.md | 2 +- docs/vendor/preflight-sb-helm-templates-about.md | 2 +- docs/vendor/preflight-support-bundle-about.mdx | 2 +- docs/vendor/replicated-onboarding.mdx | 2 +- embedded-cluster/embedded-using.mdx | 2 +- embedded-cluster/embedded-v3-migrate.mdx | 8 ++++---- 10 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/partials/preflights/_ec-v3-v1beta3-note.mdx b/docs/partials/preflights/_ec-v3-v1beta3-note.mdx index dcdc9d8542..fdf0f7fa41 100644 --- a/docs/partials/preflights/_ec-v3-v1beta3-note.mdx +++ b/docs/partials/preflights/_ec-v3-v1beta3-note.mdx @@ -1,3 +1,5 @@ :::note -These examples use `troubleshoot.sh/v1beta2` (supported by KOTS, kURL, and Embedded Cluster v2). Embedded Cluster v3 requires preflight specs to use `troubleshoot.sh/v1beta3`, packaged as a release-level file and rendered with Helm template syntax (not `repl{{ }}`). `troubleshoot.sh/v1beta3` is not supported by KOTS or Embedded Cluster v2. This change does not affect support bundle specs, which still use `v1beta2` on all current installer products. See [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). +These examples use `troubleshoot.sh/v1beta2` (supported by KOTS, kURL, and Embedded Cluster v2). Embedded Cluster v3 requires application preflight specs to use `troubleshoot.sh/v1beta3`, packaged as a release-level file and rendered with Helm template syntax (not `repl{{ }}`). `troubleshoot.sh/v1beta3` is not supported by KOTS or Embedded Cluster v2. + +The `v1beta3` requirement applies only to the Preflight custom resource. HostPreflight, SupportBundle, and Redactor specs continue to use `v1beta2` on all installer products, including Embedded Cluster v3. See [Application preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). ::: diff --git a/docs/reference/custom-resource-about.md b/docs/reference/custom-resource-about.md index a1ce743438..e243b44190 100644 --- a/docs/reference/custom-resource-about.md +++ b/docs/reference/custom-resource-about.md @@ -52,7 +52,7 @@ The following custom resources can be used in releases distributed with Replicat troubleshoot.sh/v1beta2
troubleshoot.sh/v1beta3 [Preflight](custom-resource-preflight) - Defines collectors and analyzers for preflight checks. KOTS, kURL, and Embedded Cluster v2 use v1beta2. Embedded Cluster v3 requires v1beta3, which is not supported by KOTS or Embedded Cluster v2. See Preflight specs must use v1beta3. + Defines collectors and analyzers for preflight checks. KOTS, kURL, and Embedded Cluster v2 use v1beta2. Embedded Cluster v3 requires v1beta3, which is not supported by KOTS or Embedded Cluster v2. See Application preflight specs must use v1beta3. troubleshoot.sh/v1beta2 diff --git a/docs/reference/custom-resource-preflight.md b/docs/reference/custom-resource-preflight.md index 43397a88b1..005233dbd4 100644 --- a/docs/reference/custom-resource-preflight.md +++ b/docs/reference/custom-resource-preflight.md @@ -1,3 +1,5 @@ +import EcV3Note from "../partials/preflights/_ec-v3-v1beta3-note.mdx" + # Preflight and SupportBundle You can define preflight checks and support bundle specifications for Replicated KOTS and Helm installations. @@ -20,9 +22,7 @@ The following sections show basic Preflight and Support Bundle custom resource d ### Preflight -:::note -This example uses `troubleshoot.sh/v1beta2` (supported by KOTS, kURL, and Embedded Cluster v2). Embedded Cluster v3 requires preflight specs to use `troubleshoot.sh/v1beta3`, packaged as a release-level file and rendered with Helm template syntax (not `repl{{ }}`). `troubleshoot.sh/v1beta3` is not supported by KOTS or Embedded Cluster v2. This change does not affect the SupportBundle custom resource, which does not support `v1beta3` on any installer. See [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). -::: + The Preflight custom resource uses `kind: Preflight`: diff --git a/docs/reference/custom-resource-redactor.md b/docs/reference/custom-resource-redactor.md index e13a92ea24..b066506251 100644 --- a/docs/reference/custom-resource-redactor.md +++ b/docs/reference/custom-resource-redactor.md @@ -40,7 +40,7 @@ How you deliver the Redactor resource depends on how customers install your appl Embedded Cluster v3 - Add the Redactor resource to the release, or package the spec in a labeled Secret in your Helm chart. Redactors continue to use `troubleshoot.sh/v1beta2`. The `v1beta3` API version applies only to preflight specs. See [Add custom redactors](/embedded-cluster/v3/embedded-using#redactors) in Configure Embedded Cluster. + Add the Redactor resource to the release, or package the spec in a labeled Secret in your Helm chart. Redactors continue to use `troubleshoot.sh/v1beta2`. The `v1beta3` API version applies only to the Preflight custom resource. See [Add custom redactors](/embedded-cluster/v3/embedded-using#redactors) in Configure Embedded Cluster. Helm diff --git a/docs/vendor/licenses-referencing-fields.md b/docs/vendor/licenses-referencing-fields.md index 21ebd9ef87..d418e55bf9 100644 --- a/docs/vendor/licenses-referencing-fields.md +++ b/docs/vendor/licenses-referencing-fields.md @@ -3,7 +3,7 @@ This topic describes how to check custom entitlements before installation or upgrade using preflight checks and Replicated template functions in the License context. The information in this topic applies to applications installed with KOTS, kURL, or Embedded Cluster v2. :::note -This example uses `troubleshoot.sh/v1beta2` with the Replicated `repl{{ LicenseFieldValue }}` template function. Embedded Cluster v3 requires preflight specs to use `troubleshoot.sh/v1beta3`, which Embedded Cluster renders with Helm rather than the Replicated template engine, so `LicenseFieldValue` is not available inside a v3 preflight spec. Instead, reference the entitlement through the Helm values that the Replicated SDK injects, for example `{{ .Values.global.replicated.licenseFields.node_count.value }}`. See [Check entitlements in Helm charts](/vendor/licenses-reference-helm) and [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). +This example uses `troubleshoot.sh/v1beta2` with the Replicated `repl{{ LicenseFieldValue }}` template function. Embedded Cluster v3 requires application preflight specs to use `troubleshoot.sh/v1beta3`, which Embedded Cluster renders with Helm rather than the Replicated template engine, so `LicenseFieldValue` is not available inside a v3 preflight spec. Instead, reference the entitlement through the Helm values that the Replicated SDK injects, for example `{{ .Values.global.replicated.licenseFields.node_count.value }}`. See [Check entitlements in Helm charts](/vendor/licenses-reference-helm) and [Application preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). ::: ## Overview diff --git a/docs/vendor/preflight-sb-helm-templates-about.md b/docs/vendor/preflight-sb-helm-templates-about.md index 5e071242c4..b5a14f6bcf 100644 --- a/docs/vendor/preflight-sb-helm-templates-about.md +++ b/docs/vendor/preflight-sb-helm-templates-about.md @@ -10,7 +10,7 @@ Helm templates can be useful when you need to: You can also use Helm templating with the Troubleshoot template functions for the `clusterPodStatuses` analyzer. For more information, see [Helm and Troubleshoot Template Example](#troubleshoot). :::note -The preflight examples on this page use a `troubleshoot.sh/v1beta2` spec wrapped in a Secret, which is the approach for KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires a `troubleshoot.sh/v1beta3` preflight spec, which Embedded Cluster renders through Helm directly, so you do not wrap it in a Secret. Support bundle specs are unaffected. See [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). +The preflight examples on this page use a `troubleshoot.sh/v1beta2` spec wrapped in a Secret, which is the approach for KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires a `troubleshoot.sh/v1beta3` application preflight spec, which Embedded Cluster renders through Helm directly, so you do not wrap it in a Secret. HostPreflight and support bundle specs are unaffected. See [Application preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). ::: ## Helm template example diff --git a/docs/vendor/preflight-support-bundle-about.mdx b/docs/vendor/preflight-support-bundle-about.mdx index 7f9d5167e9..7c916d1228 100644 --- a/docs/vendor/preflight-support-bundle-about.mdx +++ b/docs/vendor/preflight-support-bundle-about.mdx @@ -76,7 +76,7 @@ To add preflight checks for your application, create a Preflight YAML specificat For information about how to add preflight checks to your application, including examples, see [Define Preflight Checks](preflight-defining). :::note -Preflight specs use `troubleshoot.sh/v1beta2` for KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires `troubleshoot.sh/v1beta3`, which is not supported by KOTS or Embedded Cluster v2. Support bundle specs still use `v1beta2` on all current installer products. See [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). +Application preflight specs use `troubleshoot.sh/v1beta2` for KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires `troubleshoot.sh/v1beta3`, which is not supported by KOTS or Embedded Cluster v2. The requirement applies only to the Preflight custom resource. HostPreflight, support bundle, and Redactor specs still use `v1beta2` on all current installer products. See [Application preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). ::: ### Blocking installation with required (strict) preflights diff --git a/docs/vendor/replicated-onboarding.mdx b/docs/vendor/replicated-onboarding.mdx index 5667d2933c..6d55b0e00b 100644 --- a/docs/vendor/replicated-onboarding.mdx +++ b/docs/vendor/replicated-onboarding.mdx @@ -306,7 +306,7 @@ To define preflight checks for your application: 1. In your Helm chart `templates` directory, add a Kubernetes Secret that includes a preflight spec. For more information, see [Define preflight checks](/vendor/preflight-defining). For examples, see [Example preflight specs](/vendor/preflight-examples). :::note - This uses a `troubleshoot.sh/v1beta2` spec, which is supported by KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires a `troubleshoot.sh/v1beta3` spec packaged as a release-level file instead. See [Preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). + This uses a `troubleshoot.sh/v1beta2` spec, which is supported by KOTS, kURL, and Embedded Cluster v2. Embedded Cluster v3 requires a `troubleshoot.sh/v1beta3` spec packaged as a release-level file instead. This applies to application preflight specs only. See [Application preflight specs must use v1beta3](/embedded-cluster/v3/embedded-v3-migrate#preflight-specs-must-use-v1beta3). ::: If you deploy your application as multiple Helm charts, add the Secret to the `templates` directory for the chart you install first. diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index 45c9115397..3c406a5416 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -268,7 +268,7 @@ For more information about host preflight checks that Embedded Cluster runs auto Support bundles generated with Embedded Cluster v3 always apply the Troubleshoot built-in redactors, which hide values that match common patterns for passwords, tokens, and credentials. To scrub additional data, such as API keys or account numbers, add custom redactors with the `troubleshoot.sh/v1beta2 Redactor` resource. -Redactors continue to use `v1beta2`. The `v1beta3` requirement applies only to preflight specs. See [Add preflight checks](#preflights) on this page. +Redactors continue to use `v1beta2`. The `v1beta3` requirement applies only to the Preflight custom resource, not to HostPreflight, SupportBundle, or Redactor specs. See [Add preflight checks](#preflights) on this page. :::note Custom redactors apply to support bundles only. Preflight checks apply the built-in redactors and ignore Redactor resources. diff --git a/embedded-cluster/embedded-v3-migrate.mdx b/embedded-cluster/embedded-v3-migrate.mdx index 36a2442898..c68333010a 100644 --- a/embedded-cluster/embedded-v3-migrate.mdx +++ b/embedded-cluster/embedded-v3-migrate.mdx @@ -84,19 +84,19 @@ Because Embedded Cluster v3 removes KOTS, you must include the [Replicated SDK]( Continue to configure status informers in the Replicated Application custom resource. Embedded Cluster v3 passes them to the SDK. For more information, see [Enable and understand application status](/vendor/insights-app-status). -### Preflight specs must use v1beta3 +### Application preflight specs must use v1beta3 {#preflight-specs-must-use-v1beta3} -Application preflight checks must use API version `troubleshoot.sh/v1beta3`. Embedded Cluster v3 does not support `v1beta2` preflight specs. +Application preflight checks must use API version `troubleshoot.sh/v1beta3`. Embedded Cluster v3 does not support `v1beta2` application 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 -**You do not need to migrate support bundle specs.** Support bundle and Redactor specs continue to work with `v1beta2` in Embedded Cluster v3. The v1beta3 requirement applies only to preflight specs. For more information about where redactors live in v3, see [Add custom redactors](embedded-using#redactors). +**You do not need to migrate host preflight, support bundle, or Redactor specs.** The `v1beta3` requirement applies only to the Preflight custom resource. HostPreflight, SupportBundle, and Redactor specs continue to work with `v1beta2` in Embedded Cluster v3. There is no `v1beta3` version of the HostPreflight custom resource. For more information about host preflight checks, see [Embedded Cluster host preflight checks](embedded-overview#about-host-preflight-checks). For more information about where redactors live in v3, see [Add custom redactors](embedded-using#redactors). ::: -**Key differences from v1beta2 for preflight specs:** +**Key differences from v1beta2 for application 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.