Document safe credential handling in troubleshoot specs - #4418
Conversation
Adds a support bundle example that passes a credential to a runPod collector via a Secret reference, and warns against literal credentials in collector specs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
Replaces real-looking credentials in the Redis, MySQL, and modular spec examples with placeholders, and adds an admonition to the support bundle and preflight examples noting that Helm template functions and KOTS config options do not protect a credential in a collector uri. Also demotes the runPod secretKeyRef example to a subsection of the existing runPod section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds a section to preflight-defining covering runPod with env.valueFrom.secretKeyRef, the requirement that the Secret already exist when preflights run, and the two ways to meet it. Replaces the previous guidance to avoid credentialed collectors in preflight checks, which offered no alternative. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Promotes the customer-supplied existing Secret from one of two options to the recommended design, and notes that a pre-install Helm hook does not make a chart-created Secret available to preflight checks. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uses literal placeholder values for the host, user, database, namespace, and Secret name so the example does not template values into a preflight spec. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Only v3 supports Replicated template functions in extensions.helmCharts[].values, so only v3 can template a user-provided password into a Secret created by an extension. For v2, recommend a support bundle after the install completes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
8ccfe6e to
61e26ff
Compare
The support bundle section said the secretKeyRef pattern does not apply to preflight checks, which contradicts the preflight section that shows exactly that pattern. The real constraint is that the Secret must already exist when preflight checks run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
banjoh
changed the title
|
docs/vendor/support-bundle-examples.mdx line 113: "This pattern does not apply to preflight checks, which run before the application is deployed. For more information, see Define preflight checks (/vendor/preflight-defining)." docs/vendor/preflight-defining.mdx line 77: "To check a credentialed resource without exposing the credential, use a runPod collector and pass the credential to the Pod with env.valueFrom.secretKeyRef. The kubelet resolves the credential when the Pod starts, so the credential never appears in the spec." To me one says the secretKeyRef pattern does not apply to preflights. The other is a how-to for using that same pattern in a preflight. Those two can’t both be true. |
Discussed offline and fixed. |
3 participants
Summary
The docs had no example of
runPodwithenv, let aloneenv.valueFrom.secretKeyRef— currently the only non-literal way to get a credential into a collector on KOTS.Story: sc-139336
Preview
Changes
runPodwithenv.valueFrom.secretKeyRef, for support bundles (support-bundle-examples.mdx) and preflights (preflight-defining.mdx#credentials).my-secret-pw,default:replicated,default:password→<PASSWORD>.helm.sh/hook: pre-install. On Embedded Cluster v3, an extension chart can create the Secret, becauseextensions.helmCharts[].valuessupports Replicated template functions and a config screen password can be templated in. Embedded Cluster v2 has no template function support in its Config, so the recommendation there is a support bundle after the install completes.Not covered
The redactor reference still shows
values:redaction without noting that the redactor spec is itself plain text, andpreflight-support-bundle-aboutstill lists passwords and database connection strings as automatically redacted without qualification. Both need the actualredact.gocoverage confirmed before the claims are rewritten.The underlying gap is that
troubleshoot.sh/v1beta2has no non-literal credential form for the database collectors, which is a product issue rather than a docs one.Testing
npm run buildpasses, with no broken links or anchors on any changed page.