docs: restructure self-hosting kubernetes guide

[nicktrn]

Restructures the Kubernetes self-hosting guide around two explicit paths - an evaluation install (bundled datastores, one command) and a production install (external datastores, your own secrets) - so every configuration decision belongs to one path or the other instead of being a flat list of options with caveats.

Also in this pass:

• Adds an architecture overview (component-to-values.yaml map) and a post-install "verify it" step.
• Consolidates the previously scattered upgrade notes into a single collapsible group, and cuts implementation detail and historical asides that no longer apply.
• Removes a duplicated object-storage section (two configs in two styles) and trims the Docker ClickHouse note down to what a self-hoster needs to act on.

[changeset-bot]

⚠️ No Changeset found

Latest commit: bc9a752

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Reorganized the Kubernetes self-hosting guide around evaluation and production installation paths. Added architecture, bundled-service, secret, datastore, registry, worker-token, upgrade, troubleshooting, task-event, realtime-stream, CLI, CI, and telemetry guidance. Updated ClickHouse migration instructions in the Kubernetes and Docker guides. Updated S3 and PostgreSQL configuration examples. Corrected the webapp documentation link for Kubernetes secrets.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the main changes but omits the required issue, checklist, testing, changelog, and screenshots sections.	Add the required template sections and complete the issue reference, checklist, testing steps, changelog, and screenshots fields.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: restructuring the self-hosting Kubernetes guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/self-hosting-kubernetes-paths

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (5)

docs/self-hosting/kubernetes.mdx (5)

163-163: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Mark ALLOW_INSECURE_DEFAULT_SECRETS as emergency-only.

This production guidance permits the deployment to continue with a published default ENCRYPTION_KEY. If the setting remains enabled, the key is not deployment-specific. Put this instruction in a <Warning> block and require operators to supply a real key and remove the override immediately after migration.

Proposed wording

-If a deployment is still running a previously published default and cannot rotate yet, set `ALLOW_INSECURE_DEFAULT_SECRETS=true` on the webapp to keep booting while you plan a migration.
+<Warning>
+  Use `ALLOW_INSECURE_DEFAULT_SECRETS=true` only for an emergency migration. Supply a
+  deployment-specific `ENCRYPTION_KEY` and remove this setting immediately after migration.
+</Warning>

Source: Coding guidelines

---

503-514: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not expose the worker token through logs and shell history.

The manual flow exposes a potentially long-lived bearer token to log readers, then asks the operator to place it in a --from-literal command. Use a Secret-backed bootstrap or a file/stdin flow that does not persist the token in shell history. If logs are unavoidable, document log-access restrictions and token rotation after bootstrap.

---

530-536: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Qualify the “safe to run as-is” upgrade claim.

The same page states that 4.5.1 and later reject v3 triggers and deploys. An unpinned upgrade can therefore break a deployment that still runs v3 tasks. State this exception in the upgrade introduction and require pinning to 4.5.0 or migrating before upgrading.

---

148-153: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Clarify that S3 and chart-managed MinIO use the same root credentials.

Bundled MinIO and webapp S3 use the same store, so document that s3.auth.existingSecret keys are for both MinIO and webapp S3 auth, and that chart-managed credentials are named trigger-datastore:minio-root-user / trigger-datastore:minio-root-password.

---

423-435: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Use Secret-backed configuration for production credentials.

registry.external.auth.password, AUTH_GITHUB_CLIENT_SECRET, and RESEND_API_KEY are displayed as inline values.yaml values. These can enter source control, Helm release history, or rendered manifests; show Secret-backed examples first and mark inline values as local-only.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5312d024-aee8-4138-bf98-bad5df6791af

📥 Commits

Reviewing files that changed from the base of the PR and between f51320c and bc9a752.

📒 Files selected for processing (1)

• docs/self-hosting/kubernetes.mdx

📜 Review details

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Documentation in docs/ uses MDX conventions defined by the documentation guidance.

Files:

• docs/self-hosting/kubernetes.mdx

🧠 Learnings (2)

📚 Learning: 2026-03-10T12:44:14.176Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.

Applied to files:

• docs/self-hosting/kubernetes.mdx

📚 Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

• docs/self-hosting/kubernetes.mdx

🪛 LanguageTool

docs/self-hosting/kubernetes.mdx

[grammar] ~156-~156: Ensure spelling is correct
Context: ...CRETandCOORDINATOR_SECRET` into the webapp deployment, and the pre-upgrade check r...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (12)

docs/self-hosting/kubernetes.mdx (12)

40-79: LGTM!

---

128-147: LGTM!

---

156-161: LGTM!

---

165-176: LGTM!

---

254-277: LGTM!

---

317-347: LGTM!

---

419-421: LGTM!

---

442-450: LGTM!

---

538-551: LGTM!

---

571-577: LGTM!

---

310-314: 🗄️ Data Integrity & Integration

ClickHouse storage migration guidance is accurate.

---

487-526: 🗄️ Data Integrity & Integration

Worker-token values contract matches the chart.