Document preflight checks for Stacklok Enterprise Platform - #1068
Open
glageju wants to merge 12 commits into
Open
Document preflight checks for Stacklok Enterprise Platform#1068glageju wants to merge 12 commits into
glageju wants to merge 12 commits into
Conversation
Implements documentation for issue #1067: - Add "Run preflight checks" section covering the shipped Preflight CR - Cover CLI plugin install, running against real values, and all checks - Document advisory-by-default behavior and preflight.enforce=true - Note the RBAC and CRD-collision gaps preflight cannot verify
Implements documentation for issue #1067: - Add a subsection under "Step 5: Install and verify" showing that the default preflight spec runs entirely offline - Show templating the locally transferred chart instead of oci:// - Note mirroring the CLI plugin release asset for the transfer workstation
Follow-up for issue #1067: - Prefix idpConfig.issuer and signingConfig.existingSecret with the enterprise-manager subchart key, matching the rest of the page - Rephrase the enforcement heading to plain English
Follow-up for issue #1067, iteration 2: - Qualify preflightDatabaseUri with the toolhive-registry-server prefix in the checks table, matching the other conditional rows - Distinguish the preflight.enforce values-file form from the --set flag - Restructure two run-on sentences for clarity
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation for the Stacklok Enterprise Platform Helm chart preflight checks so readers can validate cluster prerequisites (and optionally enforce checks in-cluster) before running an install/upgrade that fails partway through.
Changes:
- Added a new “Run preflight checks” section to the standard deployment guide, including plugin install, running against real values, a checks table, advisory vs. enforced modes, and manual verification gaps.
- Added an air-gapped install subsection showing how to run preflight checks against a locally mirrored chart directory and mirror the CLI plugin asset if needed.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/platform/enterprise-platform/deployment.mdx | Adds comprehensive preflight-check guidance (install, run, interpret results, enforcement mode, and limitations). |
| docs/platform/enterprise-platform/airgap-install.mdx | Adds air-gap specific preflight workflow using the mirrored chart directory and mirrored plugin assets. |
Comment on lines
+102
to
+106
| PREFLIGHT_VERSION=v0.131.1 | ||
| os=$(uname -s | tr '[:upper:]' '[:lower:]') | ||
| arch=$(uname -m); [ "$arch" = "x86_64" ] && arch=amd64 | ||
| curl -fsSL -o preflight.tar.gz \ | ||
| "https://github.com/replicatedhq/troubleshoot/releases/download/${PREFLIGHT_VERSION}/preflight_${os}_${arch}.tar.gz" |
Author
There was a problem hiding this comment.
Good catch, thanks. Fixed in 61fe891: macOS now resolves to the real preflight_darwin_all.tar.gz asset (Troubleshoot ships one universal binary for darwin, not per-arch), and Linux keeps the uname -m normalization for arm64/amd64.
Comment on lines
+160
to
+163
| helm template stacklok-enterprise <CHART> \ | ||
| --set registryServer.enabled=true \ | ||
| --set 'toolhive-registry-server.preflightDatabaseUri=postgres://user:pass@host:5432/db?sslmode=require' \ | ||
| | kubectl preflight - |
Author
There was a problem hiding this comment.
Following up: you're right that a literal-looking connection string isn't great practice regardless of the redaction question. Fixed in d155dc6 by switching to <USER>/<PASSWORD>/<HOST>/<DATABASE> placeholders, matching this page's existing convention.
Comment on lines
+175
to
+178
| On the Helm CLI install path, `kubectl preflight` can't block `helm install`. A | ||
| `fail` result is a signal you act on yourself, not an automatic gate: don't | ||
| proceed to [Step 4](#4-install-the-chart) while any check reports `fail`. Fix | ||
| the underlying cluster condition first. |
Author
There was a problem hiding this comment.
Fixed in 61fe891: reworded to "a signal to act on, not an automatic gate."
Match how the docs already treat third-party tool versions (helm, cosign): a minimum/compatible version, not a pin tied to Stacklok's internal CI. krew becomes the primary install path; the pinned release download moves to a fallback for air-gapped or krew-less setups, without claiming to match a CI-validated version.
Match the <ALL_CAPS> placeholder convention used elsewhere on this page instead of a literal-looking connection string.
- Explain <CHANNEL> and <VERSION> at first use, since the preflight section now runs before Step 1 where they were previously introduced - Replace the vague <CHART> placeholder with the concrete oci:// reference
Preflight is meant to catch problems before helm install, but the prior placement ran it after install already succeeded and pods were verified Running, defeating the point. Move "Run preflight checks" ahead of "Install and verify" within Step 5, and rename the step to "Preflight, install, and verify" to reflect both subsections.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (4)
docs/platform/enterprise-platform/deployment.mdx:130
- This line encourages using whatever is "current"/"latest" on the Troubleshoot releases page. That conflicts with the pinned-version guidance described in the PR (pick a specific version that Stacklok validates, rather than chasing latest). Consider rephrasing to avoid implying readers should update to the newest version opportunistically.
Check the [releases page](https://github.com/replicatedhq/troubleshoot/releases)
for the current version rather than assuming `v0.131.1` above is still latest.
docs/platform/enterprise-platform/deployment.mdx:93
- This section says to run preflight "before you authenticate", but the workflow here uses
helm templateagainst an OCI chart URL, which requires authenticating tooci.stacklok.com(as described in Step 1 later in this file). This is inconsistent and can block readers from running preflight at the intended point in the install flow.
Before you authenticate and install, run the platform's **preflight** spec
against your target cluster. The umbrella chart ships a `Preflight` custom
resource as a labeled Secret, so rendering the chart and piping it to the
`kubectl-preflight` plugin analyzes real prerequisites automatically. It catches
misconfigurations before they surface later as failed pods or a stuck rollout: a
docs/platform/enterprise-platform/deployment.mdx:155
helm templatedoesn't typically "prompt" for registry credentials; it will fail unless you've already authenticated (e.g.,helm registry login) or otherwise configured credentials. Since this page already documentshelm registry loginin Step 1, reword this to avoid implying an interactive prompt and to keep the flow consistent.
`helm template` prompts for the same registry credentials you use in
[Step 1](#1-authenticate-to-the-replicated-registry): your license email as the
username and your **License ID** as the password.
docs/platform/enterprise-platform/deployment.mdx:105
- This suggests "Any recent release works" for the
kubectl-preflightplugin, but the PR description/issue scope calls out recommending a pinned Troubleshoot release (the version Stacklok CI validates) and noting krew as an unpinned alternative that can drift. As written, readers will likely default to krew/latest and miss the pinned-version guidance.
This issue also appears on line 129 of the same file.
Any recent release works; the chart's `Preflight` spec doesn't depend on a
specific CLI version.
- Add the missing --values values.yaml flag to the registry database credential example; without it, copying that block standalone drops the real values file and silently skips every other analyzer - Reword the "Step 4" cross-reference, since no numbered steps are visible from the preflight section itself
- deployment.mdx: explain where global.replicated.dockerconfigjson comes from (injected by the registry at pull time, not hand-set), verified against stacklok-enterprise-platform's appendix-b-helm- distribution.md and troubleshoot.md - airgap-install.mdx: fix the preflight template command to reference the actual .tgz this flow produces, not an invented unpacked directory that never exists in this walkthrough
"Before you authenticate and install" was wrong: helm template against an oci:// reference is itself a registry pull, so it needs the same authentication as helm install. Verified against Replicated's own docs and the upstream install-helm.md, which orders preflight right after authentication, not before it. Fix the framing to point the reader at Step 1 and Step 3 first, rather than claiming preflight runs before authenticating.
glageju
marked this pull request as ready for review
July 30, 2026 00:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents the preflight checks feature for the Stacklok Enterprise Platform
Helm chart: the shipped
Preflightcustom resource, the advisorykubectl preflightworkflow on the Helm CLI install path, and the opt-inpreflight.enforce=truein-cluster blocking mode. This lets customers catchinstall-time misconfigurations, an unsupported Kubernetes version, tight
node capacity, an unreachable OIDC issuer, a missing signing-key Secret,
before
helm installfails partway through a release.docs/platform/enterprise-platform/deployment.mdxAdds a "Run preflight checks" section between "What the chart includes" and
"Deploy with Helm", covering:
values.yamlare prerequisites forrunning the check, since
helm templateagainst anoci://reference isitself a registry pull; the section points readers to the relevant
numbered steps below
kubectl-preflightCLI plugin withkrewas the primarypath (any recent release works), with a pinned direct-download fallback
for air-gapped or krew-less environments
signing-key, registry database) actually render
a one-off
--setflag alongside the real values file, using placeholdervalues rather than a literal-looking connection string
preflight.enforce=truein-cluster blocking mode: itsprerequisites, how to diagnose a blocked install, and how to bypass a
known false positive
with a prior install) and how to verify them manually
docs/platform/enterprise-platform/airgap-install.mdxAdds a "Preflight, install, and verify" step (renamed from "Install and
verify") with two subsections in order: "Run preflight checks against the
mirrored chart" runs first, templating the local chart archive from the
mirror step instead of an
oci://reference, followed by "Install andverify" (the prior content, unchanged). Preflighting runs before install so
it can catch problems ahead of time.
Type of change
Related issues/PRs
Closes #1067
Upstream implementation: stacklok/stacklok-enterprise-platform#2513
Screenshots
Not applicable, no navigation or formatting changes.
Submitter checklist
Content and formatting
style
Reviewer checklist
Content
style
Vercel Deployment: CLICK HERE