docs(experimentation): Make the self-hosted experimentation guide easier to follow

[matthewelwell]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Walking through the Kubernetes guide to set experimentation up, it was never clear which infrastructure is the
operator's to provide and which the chart stands up, and the values example arrived with no explanation of what it was.

• Split the section into Prerequisites, Configuration, Kafka topics and permissions, and Database users, and renamed
  "Requirements" to "Prerequisites" to match the rest of the docs.
• The warehouse prerequisite now names ClickHouse or Databricks and says you host it. It read "a warehouse for each
  environment", which implies one warehouse per environment; one serves them all, as events are scoped by environment
  key.
• The values example gets a lead-in and comments, and absorbs the warehouse credentials secret and the
  passwordFromExistingSecret advice.
• Kafka: say that the chart creates the topics, identify the consumer groups as what warehouse delivery consumes with
  rather than something to provision, and explain why auto.create.topics.enable=true means creating the topics
  yourself first.
• Database users: each SQL block now says what that user is for, and the values that wire up the URLs moved into a
  closing paragraph instead of dangling off a colon.
• run-an-experiment: note that the SDKs post to Flagsmith's hosted events endpoint unless told otherwise, so
  self-hosted installations must point them at their own ingestion service.

The values example uses experimentation.warehouseCredentialsSecretFromExistingSecret, so it is accurate once
Flagsmith/flagsmith-charts#616 ships. The Chart Values table is untouched here, as #8800 covers it.

How did you test this code?

npm run build in docs/ passes and reports no new broken anchors. Each statement was checked against the chart
templates and the API source rather than the existing prose.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 16, 2026 2:29pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
flagsmith-frontend-preview	Ignored	Preview	Oct 16, 2026 2:29pm UTC
flagsmith-frontend-staging	Ignored	Preview	Oct 16, 2026 2:29pm UTC

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d5dd023a-b35e-4d0c-aa1e-3eaddd7010fd

📥 Commits

Reviewing files that changed from the base of the PR and between 0051b00 and 672fd18.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

The documentation now covers the default event API endpoint and SDK options for sending events to a self-hosted service. The Kubernetes guide adds warehouse requirements and configuration, Kafka topic and permission guidance, and database role and credential setup.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: 🔵 Low · up to 0051b

With Kafka auto-creation enabled, topics can retain broker-default settings instead of the chart’s intended partition and replication values. Documenting the configured values addresses this bounded deployment risk.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d5c4308e-4796-4dc7-a25e-8a13836b9990

📥 Commits

Reviewing files that changed from the base of the PR and between 8bed28a and 0051b00.

📒 Files selected for processing: 2

• docs/docs/deployment-self-hosting/hosting-guides/kubernetes-openshift.md
• docs/docs/experimentation/run-an-experiment.mdx

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.