cloud: update docs for BYOC single AZ support - #23591
Open
wildpcww wants to merge 2 commits into
Open
Conversation
ti-chi-bot
Bot
added
contribution
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review. 📝 WalkthroughWalkthroughBYOC documentation now describes selectable Zonal and Regional high availability modes for resource pools, availability zone requirements, Pool vCPU Limit behavior, mode inheritance, and immutable placement settings. ChangesBYOC high availability
Estimated code review effort: 1 (Trivial) | ~5 minutes Merge Risk: 🔵 Low · up to The documentation adds BYOC single-AZ guidance, but some terminology, Regional resource-pool prerequisites, and vCPU limit conditions remain unclear or incomplete, which could lead users to choose unsupported configurations or encounter failed operations. The PR is mergeable with explicit owner awareness and follow-up on these bounded documentation issues. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 070ab6e7-407b-4394-8bbc-082a18f07ee0
📒 Files selected for processing (8)
tidb-cloud/architecture-concepts.mdtidb-cloud/byoc/byoc-initialize-service.mdtidb-cloud/byoc/byoc-prepare-environment-aws.mdtidb-cloud/byoc/create-resource-pool-byoc.mdtidb-cloud/byoc/create-tidb-instance-byoc.mdtidb-cloud/byoc/manage-resource-pools-byoc.mdtidb-cloud/byoc/multi-region-deployment.mdtidb-cloud/premium/backup-and-restore-premium.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
| > Multi-AZ deployment functionality is disabled for this configuration. | ||
| The availability zones prepared for the BYOC region determine where TiDB Cloud can place resource pools. When creating a resource pool, you select either Zonal or Regional high availability. A Zonal resource pool is placed in one availability zone. A Regional resource pool requires at least three eligible availability zones in the region. | ||
|
|
||
| If the BYOC region is initially prepared with a single availability zone, TiDB Cloud uses that availability zone for Zonal resource pools. You can create a Regional resource pool only when two additional eligible availability zones are available. If you plan to use Regional resource pools, confirm during environment preparation that the region can provide at least three eligible availability zones. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- target document context ---'
sed -n '1,100p' tidb-cloud/byoc/byoc-prepare-environment-aws.md
printf '%s\n' '--- related Regional resource-pool and availability-zone guidance ---'
rg -n -i -C 3 'Regional resource pool|Zonal resource pool|availability zone|availability zones|eligible' \
tidb-cloud resources 2>/dev/null || true
printf '%s\n' '--- repository references to changing BYOC preparation or availability zones ---'
rg -n -i -C 3 'BYOC.*(update|redeploy|re-?prepare)|availability zone.*(add|change|update)|resource pool.*(enable|available)' \
. --glob '*.md' --glob '*.mdx' 2>/dev/null || trueRepository: pingcap/docs
Length of output: 50371
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- BYOC documentation references ---'
rg -n -i -C 4 'availability zone|availability zones|AZs|region configuration|BYOC region|resource pool' \
tidb-cloud/byoc --glob '*.md' --glob '*.mdx' | head -n 500
printf '%s\n' '--- procedures for updating, recreating, or adding BYOC regions ---'
rg -n -i -C 5 'update.*(region|availability)|modify.*(region|availability)|add.*(availability|AZ)|re-?deploy|redeploy|delete.*region|create.*region|BYOC region' \
tidb-cloud/byoc --glob '*.md' --glob '*.mdx' | head -n 500
printf '%s\n' '--- links and headings in BYOC management documents ---'
for f in $(git ls-files 'tidb-cloud/byoc/*.md'); do
case "$f" in
*manage*|*resource*|*deploy*|*region*) printf '\n### %s\n' "$f"; rg -n '^(#|.*\]\(/tidb-cloud/byoc/)' "$f" | head -n 120 ;;
esac
doneRepository: pingcap/docs
Length of output: 50368
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- multi-region update procedure ---'
sed -n '1,190p' tidb-cloud/byoc/multi-region-deployment.md
printf '%s\n' '--- BYOC setup/update script references and availability-zone parameters ---'
rg -n -i -C 5 'tidbcloud-byoc-(setup|update)\.sh|availability|AZ|region' \
tidb-cloud/byoc/multi-region-deployment.md \
tidb-cloud/byoc/byoc-automated-deployment.md \
tidb-cloud/byoc/byoc-configure-iam-permissions.md 2>/dev/null
printf '%s\n' '--- exact region and AZ lifecycle statements in BYOC docs ---'
rg -n -i -C 4 'cannot.*(change|modify|update)|must.*(prepare|select|provide).*3|single.*AZ|additional.*(AZ|availability)|existing.*region' \
tidb-cloud/byoc --glob '*.md' --glob '*.mdx' | head -n 400Repository: pingcap/docs
Length of output: 50370
🌐 Web query:
site:github.com/tidbcloud/byoc-account-setup "tidbcloud-byoc-update.sh" availability zones
💡 Result:
The script is located at:
iam_roles/tidbcloud-byoc-update.sh
It does not explicitly handle availability zones. It retrieves existing CloudFormation parameters and redeploys the selected stack while preserving those parameter values. [1]
Supported stacks: deploy, dataplane, o11y, or all. [1]
[1] (raw.githubusercontent.com)
Citations:
Clarify how users can enable Regional resource pools after single-AZ preparation.
The documented tidbcloud-byoc-update.sh flow adds regions, reuses existing CloudFormation parameters, and does not provide a path to change availability zones in an existing region. State whether users must prepare three availability zones before deployment or provide the supported migration procedure.
| <CustomContent plan="byoc"> | ||
|
|
||
| For {{{ .byoc }}}, select an active resource pool in the same cloud provider and region as the backup. If no suitable resource pool is available, an `Organization Owner` can create one before restoring the instance. Other roles cannot create resource pools. For more information, see [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md). | ||
| For {{{ .byoc }}}, select an active resource pool in the same cloud provider and region as the backup. The restored instance inherits the high availability mode of the selected resource pool. You can restore the same backup to a Zonal or Regional resource pool if the resource pool meets the restore requirements. If no suitable resource pool is available, an `Organization Owner` can create one before restoring the instance. Other roles cannot create resource pools. For more information, see [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Define the Regional resource-pool eligibility requirement in both restore workflows.
Both changed lines use the undefined phrase restore requirements. State that a Regional resource pool requires at least three eligible availability zones in the applicable region.
tidb-cloud/premium/backup-and-restore-premium.md#L245-L245: add the requirement for the backup's region.tidb-cloud/premium/backup-and-restore-premium.md#L369-L369: add the requirement for the target region.
As per path instructions, the contiguous Markdown fixes use committable suggestions. The Regional prerequisite follows the resource-pool contract.
📍 Affects 1 file
tidb-cloud/premium/backup-and-restore-premium.md#L245-L245(this comment)tidb-cloud/premium/backup-and-restore-premium.md#L369-L369
Source: Path instructions
qiancai
changed the title
qiancai
added
translation/no-need
ti-chi-bot
Bot
removed
the
missing-translation-status
qiancai
reviewed
Aug 24, 2026
| 6. In the **High Availability** area, select a high availability mode for the resource pool. | ||
|
|
||
| - **Zonal**: deploys the resource pool in a single availability zone for lower network latency. | ||
| - **Regional**: deploys the resource pool across multiple availability zones for higher availability and resilience against an availability-zone-level outage. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Regional**: deploys the resource pool across multiple availability zones for higher availability and resilience against an availability-zone-level outage. | |
| - **Regional**: deploys the resource pool across multiple availability zones for higher availability and resilience to outages at the availability zone level. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
qiancai
reviewed
Aug 24, 2026
|
|
||
| 1. Confirm the AWS Regions to be added. | ||
| 2. Select the Availability Zones for the new regions. | ||
| 2. Select the Availability Zones for the new regions. A Regional resource pool requires at least three eligible availability zones. If you plan to create Regional resource pools in a new region, confirm that the region can provide at least three eligible availability zones. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 2. Select the Availability Zones for the new regions. A Regional resource pool requires at least three eligible availability zones. If you plan to create Regional resource pools in a new region, confirm that the region can provide at least three eligible availability zones. | |
| 2. Select the Availability Zones for the new regions. A regional resource pool requires at least three eligible availability zones. If you plan to create regional resource pools in a new region, select at least three eligible availability zones for that region. |
|
|
||
| To meet different workload requirements, TiDB Cloud BYOC supports both Single-AZ and Multi-AZ deployments, enabling you to choose between lower-latency zonal deployment and higher-resilience deployment across multiple availability zones. | ||
|
|
||
| High availability is configured for each resource pool. A Zonal resource pool is deployed in a single availability zone, while a Regional resource pool is deployed across multiple availability zones. TiDB Cloud determines the availability zone placement based on the BYOC region configuration and available cloud resources. Instances created or restored in a resource pool inherit its high availability mode. After a resource pool is created, you cannot change its high availability mode or availability zone placement. |
Collaborator
There was a problem hiding this comment.
Suggested change
| High availability is configured for each resource pool. A Zonal resource pool is deployed in a single availability zone, while a Regional resource pool is deployed across multiple availability zones. TiDB Cloud determines the availability zone placement based on the BYOC region configuration and available cloud resources. Instances created or restored in a resource pool inherit its high availability mode. After a resource pool is created, you cannot change its high availability mode or availability zone placement. | |
| You can configure high availability mode for each resource pool as **Zonal** or **Regional** when you [create the pool](/tidb-cloud/byoc/create-resource-pool-byoc.md). A zonal resource pool is deployed in a single availability zone, while a regional resource pool is deployed across multiple availability zones. TiDB Cloud determines the availability zone placement based on the BYOC region configuration and available cloud resources. TiDB Cloud BYOC instances created or restored in a resource pool inherit the high availability mode of the pool. After a resource pool is created, you cannot change its high availability mode or availability zone placement. |
| You can now provision resource pools and TiDB instances directly via the TiDB Cloud console. | ||
|
|
||
| 1. Create a resource pool. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and follow the instructions in [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md) to create a resource pool in the target cloud provider and region. | ||
| 1. Create a resource pool. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and follow the instructions in [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md) to create a resource pool in the target cloud provider and region. When creating the resource pool, select Zonal or Regional high availability based on your workload requirements. Instances created or restored in the resource pool inherit its high availability mode. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. Create a resource pool. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and follow the instructions in [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md) to create a resource pool in the target cloud provider and region. When creating the resource pool, select Zonal or Regional high availability based on your workload requirements. Instances created or restored in the resource pool inherit its high availability mode. | |
| 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/), and then follow the instructions in [Create a Resource Pool](/tidb-cloud/byoc/create-resource-pool-byoc.md) to create a resource pool in the target cloud provider and region. | |
| >**Note:** | |
| > | |
| > When creating the resource pool, select **Zonal** or **Regional** high availability based on your workload requirements. {{{ .byoc }}} instances created or restored in the resource pool inherit the high availability mode of the pool. |
| Once the access keys are configured, you can initiate the restore job from the TiDB Cloud console. | ||
|
|
||
| During restore, select an active resource pool in the target cloud provider and region. | ||
| During restore, select an active resource pool in the target cloud provider and region. The restored instance inherits the high availability mode of the selected resource pool. |
Collaborator
There was a problem hiding this comment.
Suggested change
| During restore, select an active resource pool in the target cloud provider and region. The restored instance inherits the high availability mode of the selected resource pool. | |
| During restore, select an active resource pool in the target cloud provider and region. The restored {{{ .byoc }}} instance inherits the high availability mode of the selected resource pool. |
| > **Note:** | ||
| > | ||
| > Multi-AZ deployment functionality is disabled for this configuration. | ||
| The availability zones prepared for the BYOC region determine where TiDB Cloud can place resource pools. When creating a resource pool, you select either Zonal or Regional high availability. A Zonal resource pool is placed in one availability zone. A Regional resource pool requires at least three eligible availability zones in the region. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The availability zones prepared for the BYOC region determine where TiDB Cloud can place resource pools. When creating a resource pool, you select either Zonal or Regional high availability. A Zonal resource pool is placed in one availability zone. A Regional resource pool requires at least three eligible availability zones in the region. | |
| The availability zones prepared for the BYOC region determine where TiDB Cloud places resource pools. When creating a resource pool, you select either **Zonal** or **Regional** high availability. A zonal resource pool is placed in one availability zone. A regional resource pool requires at least three eligible availability zones in the region. |
|
|
||
| > **Important:** | ||
| > | ||
| > Even when the current provisioned vCPU is below the Pool vCPU Limit, creating or restoring an instance might cause the total provisioned vCPU to exceed the limit. This might constrain resource scaling and degrade the performance of all instances in the resource pool. Before creating or restoring an instance, make sure that the resource pool has sufficient vCPU capacity. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > Even when the current provisioned vCPU is below the Pool vCPU Limit, creating or restoring an instance might cause the total provisioned vCPU to exceed the limit. This might constrain resource scaling and degrade the performance of all instances in the resource pool. Before creating or restoring an instance, make sure that the resource pool has sufficient vCPU capacity. | |
| > Even when the current provisioned vCPU is below the Pool vCPU Limit, creating or restoring an instance might cause the total provisioned vCPU to exceed the limit. This might restrict resource scaling and degrade the performance of all instances in the resource pool. Before creating or restoring an instance, make sure that the resource pool has sufficient vCPU capacity. |
|
|
||
| If the selected resource pool has a Pool vCPU Limit and its current provisioned vCPU is greater than or equal to the limit, TiDB Cloud displays a warning and you cannot restore the instance to that resource pool. To continue, go to the Resource Pool details page to increase or turn off the Pool vCPU Limit, or select another resource pool. | ||
|
|
||
| > **Important:** |
Collaborator
There was a problem hiding this comment.
Suggested change
| > **Important:** | |
| > **Note:** |
Collaborator
There was a problem hiding this comment.
Important: is not supported in our doc site
|
|
||
| If the selected resource pool has a Pool vCPU Limit and its current provisioned vCPU is greater than or equal to the limit, TiDB Cloud displays a warning and you cannot restore the instance to that resource pool. To continue, go to the Resource Pool details page to increase or turn off the Pool vCPU Limit, or select another resource pool. | ||
|
|
||
| > **Important:** |
Collaborator
There was a problem hiding this comment.
Suggested change
| > **Important:** | |
| > **Note:** |
| > Multi-AZ deployment functionality is disabled for this configuration. | ||
| The availability zones prepared for the BYOC region determine where TiDB Cloud can place resource pools. When creating a resource pool, you select either Zonal or Regional high availability. A Zonal resource pool is placed in one availability zone. A Regional resource pool requires at least three eligible availability zones in the region. | ||
|
|
||
| If the BYOC region is initially prepared with a single availability zone, TiDB Cloud uses that availability zone for Zonal resource pools. You can create a Regional resource pool only when two additional eligible availability zones are available. If you plan to use Regional resource pools, confirm during environment preparation that the region can provide at least three eligible availability zones. |
Collaborator
There was a problem hiding this comment.
Suggested change
| If the BYOC region is initially prepared with a single availability zone, TiDB Cloud uses that availability zone for Zonal resource pools. You can create a Regional resource pool only when two additional eligible availability zones are available. If you plan to use Regional resource pools, confirm during environment preparation that the region can provide at least three eligible availability zones. | |
| If a BYOC region is initially prepared with a single availability zone, TiDB Cloud uses that availability zone for zonal resource pools. You can create a regional resource pool only when two additional eligible availability zones are available. If you plan to use regional resource pools, confirm during environment preparation that the region provides at least three eligible availability zones. |
| - **Zonal**: deploys the resource pool in a single availability zone for lower network latency. | ||
| - **Regional**: deploys the resource pool across multiple availability zones for higher availability and resilience against an availability-zone-level outage. | ||
|
|
||
| You must select a high availability mode before creating the resource pool. You cannot select the specific availability zones. TiDB Cloud determines the availability zones based on the BYOC region configuration and available cloud resources. |
Collaborator
There was a problem hiding this comment.
Suggested change
| You must select a high availability mode before creating the resource pool. You cannot select the specific availability zones. TiDB Cloud determines the availability zones based on the BYOC region configuration and available cloud resources. | |
| >**Note:** | |
| > | |
| > - If you select the **Regional** mode, make sure that the region for this pool contains at least three eligible availability zones. If this requirement is not met, the process of creating the regional resource pool might get stuck. | |
| > - TiDB Cloud determines the availability zones based on the [BYOC region configuration](/tidb-cloud/byoc/byoc-prepare-environment-aws.md#step-3-select-region-and-availability-zones-azs) and available cloud resources. |
Collaborator
There was a problem hiding this comment.
reason: "You must select a high availability mode before creating the resource pool." can be deleted because each step here is mandatory by default.
qiancai
reviewed
Aug 24, 2026
Comment on lines
+58
to
+59
| To create a Regional resource pool, at least three eligible availability zones must be available in the region. If this requirement is not met, you cannot create the Regional resource pool. | ||
|
|
Collaborator
There was a problem hiding this comment.
Suggested change
| To create a Regional resource pool, at least three eligible availability zones must be available in the region. If this requirement is not met, you cannot create the Regional resource pool. |
qiancai
reviewed
Aug 24, 2026
|
|
||
| > **Important:** | ||
| > | ||
| > Even if the current provisioned vCPU is below the Pool vCPU Limit, restoring an instance might cause the total provisioned vCPU to exceed the limit. This might constrain resource scaling and degrade the performance of all instances in the resource pool. Before restoring the instance, make sure that the resource pool has sufficient vCPU capacity. If necessary, increase or turn off the Pool vCPU Limit, or select another resource pool. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > Even if the current provisioned vCPU is below the Pool vCPU Limit, restoring an instance might cause the total provisioned vCPU to exceed the limit. This might constrain resource scaling and degrade the performance of all instances in the resource pool. Before restoring the instance, make sure that the resource pool has sufficient vCPU capacity. If necessary, increase or turn off the Pool vCPU Limit, or select another resource pool. | |
| > Even if the current provisioned vCPU is below the Pool vCPU Limit, restoring an instance might cause the total provisioned vCPU to exceed the limit. This might restrict resource scaling and affect the performance of all instances in the resource pool. Before restoring the instance, make sure that the resource pool has sufficient vCPU capacity. If necessary, increase or turn off the Pool vCPU Limit, or select another resource pool. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First-time contributors' checklist
What is changed, added or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit