DOC-1860: Cluster sizing, tier migration, and user scaling GA docs

[micheleRP]

Summary

Consolidated doc update for the cluster sizing and scaling initiative. This PR covers how users assess how and why to scale a BYOC cluster: sizing at create time, tier migrations today, and self-service scaling at GA.

Tickets:

• DOC-1860 (main): User Scaling GA - new Scale a BYOC Cluster page, whats-new entry
• DOC-1375: tier migrations during maintenance windows - new section on maintenance.adoc
• DOC-940: FlexTiers guidance (up to) framing and machine types/RPU concept on the BYOC tiers reference
• DOC-1861 (provisioning half): new Size and Price a BYOC Cluster page (UI + Control Plane API), pointers from the three BYOC create pages
• DOC-1133: the scale page's Control Plane API section is a stub reserved for this ticket (owner: @kbatuigas)

Merge gate

Keep this PR in draft until ENG-928 (User Scaling GA) ships. Working assumption (docs plan 2026-07-20): user scaling is not feature-gated at GA and applies to all BYOC clusters.

Before marking ready to merge:

• Replace the Month TBD heading in whats-new-cloud.adoc with the GA month
• Resolve TODO(eng) items: tier-migration guardrails and duration (Nate Cole, ENG-450); guidance/enforcement wording and tier table accuracy (Travis Downs; confirm Tristan Stevens' DOC-940 hold is lifted); 24-broker limit and vertical-scaling client impact (Simon Lord, ENG-928)
• Resolve TODO(ux): verify the scale and sizing UI flows against the shipped product
• Resolve TODO(api): verify /v1beta2/sizing request/response fields against the published OpenAPI spec; document the GA scaling API surface (DOC-1133, Kat)
• Decide whether to uncomment the sizing-calculator whats-new entry (enableSizingCalculator rollout state, Julin/Denis)

Review notes

• All content follows docs-team-standards (style-reviewed 2026-07-20): active voice, broker terminology, glossterms on first mentions, sentence-case headings, no em dashes.
• Facts are sourced from shipped code research recorded on the tickets (sizing.proto, cloud-ui, install-pack); anything unverified is an inline TODO comment rather than an assertion.

🤖 Generated with Claude Code

Preview pages

• Size and Price a BYOC Cluster (new)
• Scale a BYOC Cluster (new)
• Upgrades and Maintenance (updated)
• What's New in Redpanda Cloud (updated)
• Redpanda Terraform Provider (updated)
• Create a BYOC Cluster on AWS (updated)
• Create a BYOC Cluster on Azure (updated)
• Create a BYOC Cluster on GCP (updated)
• BYOC Tiers and Regions (updated via partials/tiers.adoc)

[netlify]

✅ Deploy Preview for rp-cloud ready!

Name	Link
🔨 Latest commit	3a08754
🔍 Latest deploy log	https://app.netlify.com/projects/rp-cloud/deploys/6a5ebdc598e2a60008abb198
😎 Deploy Preview	https://deploy-preview-642--rp-cloud.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 824de7b8-e469-40bd-a931-b5162cf01634

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-1860-cluster-scaling-docs

---

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

[micheleRP]

Thanks in advance for the SME review. This PR stays in draft until ENG-928 (User Scaling GA) ships, but the content is ready for full review now. Suggested focus areas:

• @simonlord: Scale a BYOC Cluster (new). The UI steps are a placeholder pending GA. Please check the horizontal/vertical framing and timings, the 24-broker limit, vertical-scaling client impact, and our working assumption that scaling is not feature-gated at GA. Access to your "User Scaling - beta internal notes" page would also help us firm up the flow.
• @ncole: the new Tier migrations section. Please confirm guardrails (one tier at a time?), typical duration, and maintenance-window behavior.
• @travisdowns: BYOC usage tiers. Please check the guidance (up to) framing (is any dimension throttled or enforced?), tier table accuracy, and the machine types/RPU wording.
• @deniscoady @c-julin: Size and Price a BYOC Cluster (new). Please confirm the enableSizingCalculator rollout state, what non-UBB orgs see, the create-flow steps, and the /v1beta2/sizing request example (drafted from sizing.proto, marked TODO until verified against the published OpenAPI spec).
• @kbatuigas: the Control Plane API section on the scale page is a stub reserved for DOC-1133; flagging so you can shape it whenever the GA API surface lands.

Inline TODO comments in the source mark everything unverified. Full context and merge checklist are in the PR description.

[micheleRP]

@deniscoady Following your thread in Slack yesterday (tiers phasing out, customers shouldn't reason in tiers or RPUs, calculator is the intended path): I've updated this PR to lead with workload-based sizing wherever the calculator is available and to reframe RPU as an internal unit the calculator resolves, rather than a concept customers learn.

One open messaging question for you: how far should the published docs go on the tier phase-out?

1. Current state in this PR: workload-based sizing is presented as the recommended path, tiers remain fully documented (they're still what non-UBB orgs see).
2. Stronger: explicitly say tiers are being phased out / deprecated in favor of calculator-based sizing.

Option 2 needs official deprecation comms behind it before we can publish (our docs standards require a citation for any maturity/deprecation claim). If a phase-out announcement is planned, we'd time the docs change to that. Which framing do you want?

Also flagged in the source: the single load metric you mentioned as the future over/under-provisioning signal is marked as a TODO on the new Scale a BYOC Cluster page, to document once it ships.