SQL engine deployment for multi-AZ#609
Conversation
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR updates the Redpanda SQL Cloud API deployment documentation to introduce and clarify the Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Docs standards review
Files reviewed: 1 .adoc file (modules/sql/pages/get-started/deploy-sql-cluster.adoc, +42/-11)
Overall: Solid clarification PR addressing real customer confusion about how Redpanda SQL behaves on multi-AZ clusters. @simonlord approved on 2026-06-03. Two structural suggestions (heading placement + zones-as-array clarification) and one cross-file gap (no What's New entry).
What this PR does
Clarifies the Cloud API request shape for enabling Redpanda SQL by introducing the new optional zones field on rpsql, and adds a standalone explanation of how Redpanda SQL behaves on multi-AZ clusters — SQL deploys to one AZ even when the parent cluster spans multiple AZs, the AZ is locked in at first-enable time, and it can be set explicitly or auto-chosen. Also tightens authentication-step wording and replaces the generic <n> placeholder with the clearer <compute-nodes>. Audience: BYOC operators deploying or scaling SQL via the Cloud API.
Jira ticket alignment
Ticket: DOC-2224 — multi-AZ deployment information for SQL.
Status: Addressed. The page now covers the three things a customer doing multi-AZ deployment needs to know: (a) where to specify the zone in the request body, (b) what happens if you omit it (auto-chosen), (c) that the choice is permanent after first enable.
Critical issues
None.
Suggestions
-
=== Redpanda SQL availability zonesheading placement is awkward. The section sits at H3 between=== On an existing clusterand== Scale Redpanda SQL, making it visually a third sub-flow of "Enable Redpanda SQL" alongside the two cluster scenarios:== Enable Redpanda SQL === On a new cluster === On an existing cluster === Redpanda SQL availability zones ← reads as a 3rd enable flow == Scale Redpanda SQLIt's not a flow — it's reference/concept info that applies to both
On a new clusterandOn an existing cluster. Two cleaner placements:- Promote to H2 between "Enable Redpanda SQL" and "Scale Redpanda SQL". Makes the AZ concept its own first-class topic.
- Move before the tabs as a brief callout (NOTE block) or short prose section under
== Enable Redpanda SQLdirectly, so readers see the lock-in constraint before they make the choice in the request body.
Either reads more cleanly than the current "third sub-section that turns out not to be a step."
-
zones: ["<sql-az>"]— clarify why the field is an array but only takes one zone. The example payload uses an array ("zones": ["<sql-az>"]), and the prose then says "Provide a single zone string from the cluster'szoneslist." Readers who study the API shape will notice the array wrapper and wonder if they can list multiple zones. Worth one sentence to disambiguate:- "The
zonesfield is an array for forward compatibility, but Redpanda SQL currently uses only the first zone. Provide an array containing exactly one zone string from the cluster'szoneslist."
Or whatever the actual API guarantee is. The current wording leaves the array shape unexplained.
- "The
-
== Scale Redpanda SQLCloud API flow doesn't mentionzonesis locked. A reader who sawzonesin the create/update payloads will reasonably try to include it in the scale request. ThePATCHbody shown for scaling correctly omits it, but doesn't acknowledge that the field is immutable. One sentence under the scale Cloud-API section would close this:- "You can't change the SQL availability zone during scaling. The
zonesfield is locked at first-enable time — see <> for context."
(Anchor name assumes you keep the section roughly where it is and add
[[redpanda-sql-availability-zones]].) - "You can't change the SQL availability zone during scaling. The
-
== Disable Redpanda SQLcould clarify whether re-enable lets you pick a new AZ. Current prose under Disable says: "Re-enabling SQL on the same cluster provisions a fresh engine: no prior catalog state, table mappings, or grants are restored." That implies a fresh engine. Does fresh engine mean fresh AZ choice? Readers wanting to migrate SQL to a different AZ (for example, because their current zone has capacity issues) will look for this answer. One short line under Disable would help:- "On re-enable, you can specify a different AZ in the
zonesfield." (if that's actually true)
Worth confirming with engineering, then documenting whichever way it goes.
- "On re-enable, you can specify a different AZ in the
-
Authentication step simplification — make sure the link text is still findable. The previous wording was "Authenticate to the link:/api/doc/.../topic-cloud-api-overview[Cloud API]. For details, see link:/api/doc/.../authentication[Authenticate to the Cloud API]." That's two links to two different pages (overview + authentication). The new shorter wording — "Authenticate to the Cloud API." with one link to the authentication page — is cleaner, but loses the "Cloud API overview" pointer. If readers benefit from the overview before authenticating, worth keeping both. If not, the simplification is fine.
Impact on other files
-
modules/get-started/pages/whats-new-cloud.adoc— no entry for SQL multi-AZ deployment support. This is a customer-visible new capability (thezonesfield is new in the API), so a What's New entry is appropriate. Suggested placement: a new bullet under the existing "Redpanda SQL" section in the most recent month's entry, or a fresh entry if appropriate for the release cadence. -
modules/sql/pages/get-started/overview.adoc— currently makes no mention of AZ behavior. The "Why use Redpanda SQL" section talks about scaling but not deployment topology. If multi-AZ Redpanda clusters are common, a one-sentence note in overview ("Redpanda SQL deploys to a single availability zone within your cluster — see xref...[deploy-sql-cluster] for details") would help readers planning architecture. -
No nav.adoc change needed — page is existing.
-
No xref breakage — no headings renamed; new anchors are additive only.
CodeRabbit findings worth considering
None — CodeRabbit completed its review with no actionable findings.
What works well
- Real customer pain point. Customers running multi-AZ clusters who hit the SQL
zonesfield with no docs would have been confused about why the API takes a list when only one zone is used. This page now answers that. <compute-nodes>placeholder is much clearer than<n>. Anyone copy-pasting won't try to figure out whatnmeans.- The three-bullet AZ explanation is the right shape. "Specify a zone, omit for auto-choice, locked at first-enable" covers the decisions a customer has to make.
@simonlord's approval — Simon owns the SQL engine area, so his sign-off validates the technical content (especially the lock-in semantics).- Voice and tone consistent — active voice, second person, no em dashes, sentence case for H3.
- Symmetric coverage of the create + update flows. Both Cloud API tabs (on a new cluster, on an existing cluster) have the same explanatory bullet structure (
<compute-nodes>:,<sql-az>:(optional)), so readers comparing the two see the same shape. - Scale flow update is internally consistent. Numbered steps for "Make the PATCH request → Poll the long-running operation" now parallel the create flow's structure.
Process note
This PR was opened on 2026-06-03 and approved within ~12 hours. The single-file scope and clear ownership (Simon for SQL) is what enabled fast turnaround. Worth replicating the shape — a tightly scoped DOC ticket, one file, one reviewer who owns the area.
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Some suggestions, but no critical issues
3 participants
Description
This pull request updates the documentation for deploying and scaling Redpanda SQL clusters via the Cloud API, focusing on clarifying how to configure availability zones and compute nodes. The changes improve instructions for specifying SQL compute node counts, introduce guidance for multi-AZ deployments, and add a new section explaining how Redpanda SQL uses availability zones.
API request and configuration improvements:
<compute-nodes>instead of<n>for clarity, and added the optionalzonesfield for specifying the availability zone when enabling Redpanda SQL. Instructions now explicitly describe how to set these fields and what values to use. [1] [2] [3]Availability zone documentation:
General documentation clarity:
Resolves DOC-2224
Review deadline:
Page previews
Checks