Skip to content

Add v1beta3 preflight guidance for Embedded Cluster v3#4186

Merged
AmberAlston merged 4 commits into
mainfrom
ec-v3-preflight-v1beta3-docs
Jun 23, 2026
Merged

Add v1beta3 preflight guidance for Embedded Cluster v3#4186
AmberAlston merged 4 commits into
mainfrom
ec-v3-preflight-v1beta3-docs

Conversation

@AmberAlston

@AmberAlston AmberAlston commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

Expands the v1beta3 preflight documentation for EC v3 from a one-liner link to the troubleshoot.sh project into actionable, Replicated-owned guidance.

What this PR covers:

  • Why EC v3 requires v1beta3 for preflights (Helm-native rendering, external spec packaging)
  • That support bundles are unaffected (v1beta2 continues to work)
  • Key differences from v1beta2 (Helm syntax not repl{{}}, spec lives outside charts, not valid YAML pre-render)
  • Migration checklist on the v2-to-v3 page: change apiVersion, move spec out of chart, remove Secret wrapper, replace template syntax
  • Dual-spec guidance: how to support both KOTS and EC v3 during the transition period (v1beta2 + v1beta3 specs, each install method ignores the other)
  • New "Add preflight checks" section on the configure page with:
    • How the rendering pipeline works end-to-end (inject into chart, render via helm template, merge per-chart outputs)
    • What Helm context is available during rendering (chart values/defaults, helpers, .Chart.Name, .Release.*)
    • Single-chart and multi-chart examples with .Chart.Name conditionals
    • Conditional checks using chart values (e.g. gating GPU checks on .Values.gpu.enabled)
    • How gated-out checks are handled (excluded from output, no error)
  • Current limitations (one spec per release, Helm syntax only, YAML linters won't work pre-render)

Tracked separately:

  • In-cluster collector execution (sc-138530): Needs owner assignment and implementation before it can be documented. Does not block this PR.

@AmberAlston @claude
Add v1beta3 preflight guidance for EC v3
849b57f 
Expand the migration page's v1beta3 section from a one-liner into
actionable guidance: what changed, why v1beta3 is required, step-by-step
migration checklist, and clarification that support bundles are unaffected.

Add a new "Add preflight checks" section to the EC v3 configure page
with how v1beta3 specs work, single-chart and multi-chart examples,
and current limitations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@netlify

netlify Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Deploy Preview for replicated-docs ready!

Name Link
🔨 Latest commit bb2ffed
🔍 Latest deploy log https://app.netlify.com/projects/replicated-docs/deploys/6a3aeedbe358fd000815946b
😎 Deploy Preview https://deploy-preview-4186--replicated-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify

netlify Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Deploy Preview for replicated-docs-upgrade ready!

Name Link
🔨 Latest commit bb2ffed
🔍 Latest deploy log https://app.netlify.com/projects/replicated-docs-upgrade/deploys/6a3aeedbcff52300081e7e4d
😎 Deploy Preview https://deploy-preview-4186--replicated-docs-upgrade.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@replicated-ci replicated-ci added type::docs Improvements or additions to documentation type::feature labels Jun 18, 2026
@AmberAlston @claude
Add dual-spec guidance for KOTS/EC v3 transition period
1db4dd4 
During the transition period where a single release targets both KOTS
and EC v3, vendors need both a v1beta2 and v1beta3 preflight spec.
This adds a note explaining that each install method ignores the
other's spec.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
github-actions[bot]
github-actions Bot reviewed Jun 23, 2026
View reviewed changes

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

embedded-cluster/embedded-using.mdx|58 col 99| [Replicated.Passive] In general, use active voice instead of passive voice ('are packaged').
embedded-cluster/embedded-using.mdx|66 col 31| [Replicated.Passive] In general, use active voice instead of passive voice ('are merged').
embedded-cluster/embedded-using.mdx|67 col 123| [Replicated.Passive] In general, use active voice instead of passive voice ('are needed').
embedded-cluster/embedded-using.mdx|72 col 107| [Replicated.Passive] In general, use active voice instead of passive voice ('being rendered').
embedded-cluster/embedded-using.mdx|75 col 135| [Replicated.Passive] In general, use active voice instead of passive voice ('are excluded').
embedded-cluster/embedded-using.mdx|100 col 61| [Replicated.Passive] In general, use active voice instead of passive voice ('is needed').
embedded-cluster/embedded-using.mdx|104 col 152| [Replicated.Passive] In general, use active voice instead of passive voice ('is rendered').
embedded-cluster/embedded-using.mdx|104 col 164| [Replicated.WordSwaps] Use 'after' or 'one time' instead of 'once'.
embedded-cluster/embedded-using.mdx|146 col 1| [Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
embedded-cluster/embedded-using.mdx|146 col 105| [Replicated.Passive] In general, use active voice instead of passive voice ('is defined').
embedded-cluster/embedded-using.mdx|150 col 80| [Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
embedded-cluster/embedded-using.mdx|150 col 142| [Replicated.Passive] In general, use active voice instead of passive voice ('be enabled').
embedded-cluster/embedded-using.mdx|177 col 114| [Replicated.Passive] In general, use active voice instead of passive voice ('is excluded').

Comment thread docs/vendor/team-management-saml-auth.md Outdated
Comment thread docs/vendor/team-management-saml-auth.md Outdated
Comment thread docs/vendor/team-management-saml-auth.md Outdated
Comment thread docs/vendor/team-management-saml-auth.md Outdated
Comment thread docs/vendor/team-management-saml-auth.md Outdated
Comment thread embedded-cluster/embedded-v3-migrate.mdx
Comment thread embedded-cluster/embedded-v3-migrate.mdx
Comment thread embedded-cluster/embedded-v3-migrate.mdx
Comment thread embedded-cluster/embedded-v3-migrate.mdx
Comment thread embedded-cluster/embedded-v3-migrate.mdx
@AmberAlston @claude
Expand v1beta3 preflight docs with rendering pipeline details from ec…
6a5500b 
…#475

Now that ec#475 has merged, flesh out the preflight section with concrete
implementation details: how the per-chart rendering pipeline works, what
Helm context is available, multi-chart gating with .Chart.Name, conditional
checks using chart values, and gated-out handling. Cross-link migration
page to the new detailed section.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@AmberAlston AmberAlston force-pushed the ec-v3-preflight-v1beta3-docs branch from 41541a5 to 6a5500b Compare June 23, 2026 20:25
@AmberAlston @claude
Fix vale linter warnings in preflight docs
bb2ffed 
- Heading: sentence case (remove backticks from heading)
- Active voice: "you package" not "are packaged", "you wrapped" not
  "was wrapped", "you do not need to update" not "do not need to be
  updated", "Embedded Cluster excludes" not "are excluded"
- Word swap: "one time per chart" not "once per chart"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@AmberAlston AmberAlston marked this pull request as ready for review June 23, 2026 20:39
@AmberAlston AmberAlston requested a review from a team as a code owner June 23, 2026 20:39
@AmberAlston AmberAlston requested a review from sgalsaleh June 23, 2026 20:43
@AmberAlston AmberAlston merged commit 877b1fc into main Jun 23, 2026
5 checks passed
@AmberAlston AmberAlston deleted the ec-v3-preflight-v1beta3-docs branch June 23, 2026 21:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actions github-actions[bot] github-actions[bot] left review comments

@sgalsaleh sgalsaleh sgalsaleh approved these changes

Assignees

No one assigned

Labels

type::docs Improvements or additions to documentation type::feature

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@AmberAlston @sgalsaleh @replicated-ci