redpanda-data · micheleRP · Jul 20, 2026 · Jul 21, 2026
@@ -9,6 +9,7 @@
 * xref:get-started:cluster-types/index.adoc[Deploy]
 ** xref:get-started:cluster-types/serverless.adoc[Serverless]
 ** xref:get-started:cluster-types/byoc/index.adoc[BYOC]
+*** xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[]
 *** xref:get-started:cluster-types/byoc/aws/index.adoc[AWS]
 **** xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[]
 **** xref:get-started:cluster-types/byoc/aws/vpc-byo-aws.adoc[]
@@ -416,6 +417,7 @@
 ** xref:manage:cluster-maintenance/index.adoc[Cluster Maintenance]
 *** xref:manage:cluster-maintenance/cluster-state.adoc[]
 *** xref:manage:maintenance.adoc[]
+*** xref:manage:cluster-maintenance/scale-cluster.adoc[]
 *** xref:manage:cluster-maintenance/config-cluster.adoc[]
 *** xref:manage:audit-logging.adoc[]
 **** xref:manage:audit-logging/audit-log-samples.adoc[]

@@ -4,7 +4,7 @@
 
 To create a Redpanda cluster in your virtual private cloud (VPC), follow the instructions in the Redpanda Cloud UI. The UI contains the parameters necessary to successfully run `rpk cloud byoc apply`. See also: xref:get-started:byoc-arch.adoc[BYOC architecture].
 
-NOTE: With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:./vpc-byo-aws.adoc[BYOVPC cluster on AWS].
+NOTE: With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:get-started:cluster-types/byoc/aws/vpc-byo-aws.adoc[BYOVPC cluster on AWS].
 
 == Prerequisites
 
@@ -26,7 +26,7 @@ To verify access, you should be able to successfully run `aws sts get-caller-ide
 
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC. 
-. Enter a cluster name, then select the resource group, provider (AWS), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version.
+. Enter a cluster name, then select the resource group, provider (AWS), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ==== 

@@ -150,7 +150,7 @@ To create a Redpanda cluster in your Azure VNet, follow the <<prerequisites,prer
 
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
-. Enter a cluster name, then select the resource group, provider (Azure), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. 
+. Enter a cluster name, then select the resource group, provider (Azure), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ==== 

@@ -29,7 +29,7 @@ include::partial$gpq-quotas.adoc[]
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
 +
-Enter a cluster name, then select the resource group, provider (GCP), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version.
+Enter a cluster name, then select the resource group, provider (GCP), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ====

@@ -0,0 +1,76 @@
+= Size and Price a BYOC Cluster
+:description: Get machine configurations and price estimates matched to your workload before you create a BYOC cluster.
+:page-topic-type: how-to
+:personas: platform_admin
+:learning-objective-1: Describe your workload to get recommended machine configurations with price estimates
+:learning-objective-2: Compare sizing options by RPU rate, machine type, and node count
+:learning-objective-3: Request sizing estimates programmatically with the Control Plane API
+
+When you create a BYOC cluster, size it from your workload requirements instead of translating them into Redpanda tier terminology. Describe your workload, such as throughput, glossterm:partition[,partitions], and retention, and Redpanda recommends machine configurations with itemized price estimates. Workload-based sizing is the recommended way to size a cluster: it applies the same logic Redpanda's performance team uses, and it stays accurate as performance improvements change what a given configuration can handle.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+[NOTE]
+====
+Sizing options appear only for organizations on usage-based billing. If you don't see them when you create a BYOC cluster, contact your Redpanda account team.
+====
+// TODO(pm): DOC-1861 - confirm rollout state of the `enableSizingCalculator` feature flag with Julin/Denis: is it enabled for all usage-based-billing orgs in production? Also confirm what annual-commit (non-UBB) customers see, and adjust the note above.
+
+== How sizing works
+
+You can size a cluster in two ways:
+
+* *Describe your workload.* Provide workload parameters, such as partition count, ingress and egress throughput, retention, average message size, replication factor, producer count, and target latency. You can also indicate whether you plan to use cloud topics or Iceberg topics. Redpanda resolves the compute capacity your workload needs and recommends machine configurations that provide it.
+* *Specify capacity directly.* Provide a rate of Redpanda Processing Units (RPUs), from 1 to 384. One RPU represents two vCPUs of glossterm:broker[] compute. Redpanda resolves the machine configurations that deliver that capacity. Use this mode only if you already know the capacity you need; describing your workload is the recommended path.
+
+Both ways return a ranked list of viable machine configurations. Each option includes the machine type, node count, RPU rate, and the xref:reference:tiers/byoc-tiers.adoc[usage tier] it maps to, along with an itemized price estimate covering compute, ingress, egress, storage, and Iceberg, with hourly and monthly totals.
+
+Price estimates use your organization's rate card.
+
+// TODO(eng): DOC-1861 - confirm how to describe estimates vs billed amounts (estimates are based on the org rate card, but actual billing depends on measured usage).
+
+== Size a cluster in the Cloud UI
+
+. Log in to https://cloud.redpanda.com[Redpanda Cloud^].
+. On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
+. In the cluster settings step, describe your workload or enter an RPU rate, then compare the recommended configurations and price estimates.
+. Select a configuration and continue with the create flow for your cloud provider. See xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[AWS], xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc[GCP], or xref:get-started:cluster-types/byoc/azure/create-byoc-cluster-azure.adoc[Azure].
+
+// TODO(ux): DOC-1861 - verify the exact field names and step order against the production create flow before publishing, and capture screenshots if the docs team wants them.
+
+== Size a cluster with the Control Plane API
+
+To script sizing estimates, send a `POST` request to the `/v1beta2/sizing` endpoint of the link:/api/doc/cloud-controlplane[Control Plane API^]. Include your cloud provider, region, availability zone configuration, cluster type, and either a workload description or an RPU rate. The request requires the `read:organization-info` permission.
+
+// TODO(api): DOC-1861 - verify that /v1beta2/sizing appears in the published Control Plane API reference, and replace this example with the exact request and response field names from the published OpenAPI spec. The field names below are drafted from sizing.proto and are unverified.
+
+[source,bash]
+----
+curl -X POST "https://api.redpanda.com/v1beta2/sizing" \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cloud_provider": "CLOUD_PROVIDER_AWS",
+    "region": "us-east-1",
+    "cluster_type": "TYPE_BYOC",
+    "workload": {
+      "partition_count": 5000,
+      "ingress_mbps": 100,
+      "egress_mbps": 200,
+      "retention_days": 7,
+      "average_message_size_bytes": 1024,
+      "replication_factor": 3
+    }
+  }'
+----
+
+The response contains the resolved RPU rate and a ranked list of machine configurations, each with an itemized price breakdown.
+
+== Next steps
+
+* xref:get-started:cluster-types/byoc/index.adoc[Create a BYOC cluster]
+* xref:reference:tiers/byoc-tiers.adoc[BYOC tiers and regions]
@@ -6,6 +6,23 @@
 
 This page lists new features added to Redpanda Cloud.
 
+// TODO(DOC-1861): Uncomment and file under the correct month once the sizing
+// calculator rollout is confirmed (enableSizingCalculator flag broadly enabled
+// for usage-based-billing orgs; confirm with Julin/Denis).
+////
+=== Workload-based sizing and pricing for BYOC clusters
+
+If your organization uses usage-based billing, you can now describe your workload, such as throughput, partitions, and retention, when you create a BYOC cluster, and get recommended machine configurations with itemized price estimates instead of selecting a tier directly. You can also request sizing estimates through the Control Plane API. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and Price a BYOC Cluster].
+////
+
+// TODO(DOC-1860): Replace the placeholder month heading with the actual GA month
+// before merging, and verify horizontal timing/limits and the API surface.
+== Month TBD (user scaling GA)
+
+=== Self-service cluster scaling for BYOC
+
+You can now scale a BYOC cluster up or down directly from the Redpanda Cloud UI or the Control Plane API, without contacting Redpanda Support. Add or remove brokers in about 15 to 30 minutes to absorb short-term traffic changes, or change the cluster's machine type to right-size for sustained throughput changes. See xref:manage:cluster-maintenance/scale-cluster.adoc[Scale a BYOC Cluster].
+
 == July 2026
 
 === Improved Serverless trial onboarding

@@ -0,0 +1,84 @@
+= Scale a BYOC Cluster
+:description: Scale a BYOC cluster up or down by changing its node count or machine type to match your workload.
+:page-topic-type: how-to
+:personas: platform_admin
+:learning-objective-1: Choose between horizontal and vertical scaling for a workload change
+:learning-objective-2: Scale a cluster up or down from the Redpanda Cloud UI
+:learning-objective-3: Explain what happens to your cluster and clients during a scaling operation
+
+// Draft for User Scaling GA (ENG-928, in development). The PR stays in
+// draft until GA ships; merge with the GA release. Before merge, resolve
+// the TODO(eng)/TODO(ux)/TODO(api) items against the shipped UI and
+// public API. Sources: ENG-928 epic, ENG-315 (LA epic). The API section
+// supports DOC-1133 (owned by Kat Batuigas - coordinate before editing).
+// Simon Lord's "User Scaling - beta internal notes" Confluence page is
+// restricted; request access to firm up the UI flow before GA.
+
+Scale a BYOC cluster up or down as your workload changes, without contacting Redpanda Support. You can add or remove glossterm:broker[,brokers] to absorb short-term changes in traffic, or change the machine type to right-size the cluster for a sustained change in throughput.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+== Choose a scaling method
+
+You can scale a cluster in two ways:
+
+[cols="1,2,2", options="header"]
+|===
+| Method | What changes | When to use it
+
+| Horizontal scaling
+| Adds or removes brokers of the current machine type. Completes in about 15 to 30 minutes.
+| Intraday changes in traffic, such as daily peaks or batch windows.
+
+| Vertical scaling
+| Changes the machine type that the cluster runs on. Redpanda decommissions the existing brokers and recommissions brokers of the new type, which takes a few hours.
+| Sustained changes in throughput on a timescale of days, such as scaling up for weekdays and down for weekends.
+|===
+
+// TODO(eng): DOC-1860 - confirm at GA (Simon Lord): (1) is the 24-node horizontal maximum a GA limit or a tested-so-far number, (2) availability and client impact during vertical scaling (partition movement, latency), (3) confirm scale-to-zero is out of scope (Aha comment flagged confusion between "user scaling" and "scale to zero").
+
+If you are not sure how much capacity your workload needs, describe your workload in the sizing calculator to get recommended configurations and price estimates. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
+
+// TODO(eng): DOC-1860 - Core is releasing a single load metric for judging whether a cluster is over- or under-provisioned, and PM wants it exposed to users (Denis Coady, Slack 2026-07-20; Piyush Agarwal owns exposure timing; may not be RPU-aware, check Tyson/Matt). When it ships, document it here as the signal for deciding when to scale. Related: DOC-1381 tracks the Self-Managed load factor dashboard.
+
+== Scale a cluster in the Cloud UI
+
+// TODO(ux): DOC-1860 - replace with the shipped UI flow at GA. The steps below are a placeholder drafted from the ENG-928 design intent (scaling UX integrates the sizing calculator so you scale in workload terms).
+
+. Log in to https://cloud.redpanda.com[Redpanda Cloud^] and open your cluster.
+. Open the cluster's settings and select the option to resize the cluster.
+. Describe your new workload requirements, or select a target configuration (machine type and broker count).
+. Review the price estimate for the new configuration, then confirm.
+. Monitor the scaling operation's progress from the cluster overview.
+
+== Scale a cluster with the Control Plane API
+
+// TODO(api): DOC-1133 (Kat Batuigas) - document the public API surface when it ships with GA. As of 2026-07-15, the public cluster.proto (v1beta2) has no scaling fields; ScaleCluster exists only in the internal admin API. Confirm whether GA ships a new scaling endpoint or new UpdateCluster fields, and add request/response examples from the published OpenAPI spec.
+
+== What happens during scaling
+
+// TODO(eng): DOC-1860 - verify this section with engineering at GA.
+
+During both horizontal and vertical scaling, your cluster continues to serve traffic and its endpoints do not change:
+
+* When scaling horizontally, Redpanda adds or removes brokers and rebalances glossterm:partition[] data and leadership across the resulting set of brokers.
+* When scaling vertically, Redpanda provisions brokers of the new machine type, moves partition data and leadership to them in a rolling fashion, then decommissions the original brokers.
+
+When Redpanda decommissions a broker, the broker's client connections restart, and all mainstream Kafka client libraries reconnect automatically.
+
+== Limits
+
+* You can scale horizontally up to 24 brokers.
+* Scaling applies to BYOC clusters only.
+
+// TODO(eng): DOC-1860 - confirm both limits at GA. (Per docs plan 2026-07-20, we assume scaling is not feature-gated at GA and is available to all BYOC clusters.)
+
+== Next steps
+
+* xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster]
+* xref:manage:maintenance.adoc#tier-migrations[Tier migrations]
+* xref:manage:monitor-cloud.adoc[Monitor your cluster]
@@ -3,7 +3,7 @@
 :page-topic-type: concepts
 :personas: platform_admin, app_developer, streaming_developer
 :learning-objective-1: Compare minor upgrades, major upgrades, and deprecations and what to expect from each
-:learning-objective-2: Explain how scheduled maintenance windows work for BYOC and Dedicated clusters
+:learning-objective-2: Explain how scheduled maintenance windows and tier migrations work for BYOC and Dedicated clusters
 :learning-objective-3: Distinguish maintenance behavior for Serverless versus BYOC and Dedicated clusters
 
 As a fully-managed service, the Redpanda Cloud glossterm:control plane[] handles all maintenance operations, such as upgrades to your software and infrastructure. Here, _control plane_ refers to the Redpanda Cloud managed service that orchestrates cluster operations, not the Kubernetes control plane.
@@ -30,6 +30,25 @@ If you select a *Scheduled* maintenance window, then Redpanda Cloud runs operati
 
 TIP: Redpanda Cloud maintenance cycles always start on Tuesdays. Clusters scheduled for maintenance on Tuesdays are updated first, and clusters scheduled on Mondays are updated last. Keep this in mind when sequencing updates for multiple clusters.
 
+[[tier-migrations]]
+== Tier migrations
+
+You can move a BYOC or Dedicated cluster to a different xref:reference:tiers/byoc-tiers.adoc[usage tier] as your workload changes, for example to scale up before expected traffic growth, or to scale down after peak demand. To request a tier change, contact https://support.redpanda.com/hc/en-us/requests/new[Redpanda Support^]. Redpanda runs the migration for you, and your maintenance window controls when it starts.
+
+// TODO(eng): Confirm guardrails with engineering (ENG-450, Nate Cole): can customers move multiple tiers in one migration, or one tier at a time? Also confirm typical migration duration per tier step.
+
+A tier migration changes the compute resources underlying your cluster while the cluster continues to serve traffic:
+
+. Redpanda provisions new brokers that match the target tier.
+. Partition data and leadership move to the new brokers in a rolling fashion, accompanied by health checks.
+. Redpanda decommissions and removes the original brokers.
+
+Your cluster's endpoints do not change. When Redpanda decommissions a broker, the broker's client connections restart, and all mainstream Kafka client libraries reconnect automatically.
+
+Like other maintenance operations, tier migrations begin during your scheduled maintenance window, but a migration may complete after the window closes.
+
+NOTE: If you manage your cluster with the Redpanda Terraform provider, add a `lifecycle` block that ignores changes to `throughput_tier` before requesting a tier migration. Otherwise, the next `terraform apply` destroys and replaces the cluster. See xref:manage:terraform-provider.adoc#limitations[Redpanda Terraform provider limitations].
+
 [[serverless-maintenance]]
 == Serverless maintenance
 

@@ -132,9 +132,17 @@ lifecycle {
 }
 ----
 +
-This setting protects your cluster in the event Redpanda Support upgrades your cluster's throughput tier. Without it, the next `terraform apply` command triggers replacement.
+This setting protects your cluster when Redpanda migrates it to a different tier, for example after you request a xref:manage:maintenance.adoc#tier-migrations[tier migration]. Without it, the next `terraform apply` command triggers replacement.
 ====
 
+// TODO(DOC-1860, gated on ENG-928): When user scaling reaches GA, revise the
+// warning above. Self-service scaling replaces the support-mediated tier-change
+// framing, and the provider story needs eng confirmation: does the provider gain
+// scaling support (machine type and node count fields, or in-place
+// throughput_tier updates), or should customers scale through the UI/API and
+// keep the ignore_changes lifecycle block? Coordinate with DOC-1133 (Kat
+// Batuigas) for the API surface.
+
 == Prerequisites
 
 [IMPORTANT]