diff --git a/TOC-tidb-cloud-byoc.md b/TOC-tidb-cloud-byoc.md index eab29bec45ee1..a38fe52785b6d 100644 --- a/TOC-tidb-cloud-byoc.md +++ b/TOC-tidb-cloud-byoc.md @@ -29,7 +29,16 @@ - [Select Your Plan](/tidb-cloud/select-cluster-tier.md) - [Manage TiDB Cloud Resources and Projects](/tidb-cloud/manage-projects-and-resources.md) -- Manage {{{ .premium }}} Instances +- Deploy BYOC + - [Onboarding Overview](/tidb-cloud/byoc/byoc-onboarding-overview.md) + - [Prepare AWS Environment](/tidb-cloud/byoc/byoc-prepare-environment-aws.md) + - [Configure IAM Permissions](/tidb-cloud/byoc/byoc-iam-configuration.md) + - [Automated Deployment](/tidb-cloud/byoc/byoc-automated-deployment.md) + - [Service Initialization](/tidb-cloud/byoc/byoc-service-initialization.md) + - [Joint Validation](/tidb-cloud/byoc/joint-validation.md) + - [Security Hardening](/tidb-cloud/byoc/security-hardening.md) + - [Multi-Region Deployment](/tidb-cloud/byoc/multi-region-deployment.md) +- Manage Instances - [Create a {{{ .premium }}} Instance](/tidb-cloud/premium/create-tidb-instance-premium.md) - Connect to Your {{{ .premium }}} Instance - [Connection Overview](/tidb-cloud/premium/connect-to-tidb-instance.md) diff --git a/media/tidb-cloud/byoc-architecture.png b/media/tidb-cloud/byoc-architecture.png new file mode 100644 index 0000000000000..1555d215f06a6 Binary files /dev/null and b/media/tidb-cloud/byoc-architecture.png differ diff --git a/scripts/verify-internal-links-in-toc.js b/scripts/verify-internal-links-in-toc.js index 8f9a1431c7a4b..39dc806fd74dc 100644 --- a/scripts/verify-internal-links-in-toc.js +++ b/scripts/verify-internal-links-in-toc.js @@ -19,6 +19,7 @@ const CLOUD_TOC_FILES = [ "TOC-tidb-cloud-premium.md", "TOC-tidb-cloud-starter.md", "TOC-tidb-cloud-essential.md", + "TOC-tidb-cloud-byoc.md", ]; const PREFIX_TO_TOC = [ diff --git a/tidb-cloud/byoc/_index.md b/tidb-cloud/byoc/_index.md index 43aeb5cc3fecb..5e275d4a68a0a 100644 --- a/tidb-cloud/byoc/_index.md +++ b/tidb-cloud/byoc/_index.md @@ -35,6 +35,22 @@ summary: TiDB Cloud is a fully-managed Database-as-a-Service (DBaaS) that brings + + +[BYOC Onboarding Overview](https://docs.tidb.io/tidbcloud/byoc-onboarding-overview/?plan=byoc) + +[Prepare AWS Environment](https://docs.tidb.io/tidbcloud/byoc-prepare-environment-aws/?plan=byoc) + +[Configure IAM Permissions](https://docs.tidb.io/tidbcloud/byoc-iam-configuration/?plan=byoc) + +[Automated Deployment](https://docs.tidb.io/tidbcloud/byoc-automated-deployment/?plan=byoc) + +[Service Initialization](https://docs.tidb.io/tidbcloud/byoc-service-initialization/?plan=byoc) + +[Joint Validation](https://docs.tidb.io/tidbcloud/joint-validation/?plan=byoc) + + + [Create a {{{ .premium }}} Instance](https://docs.tidb.io/tidbcloud/create-tidb-instance-premium/?plan=byoc) diff --git a/tidb-cloud/byoc/byoc-automated-deployment.md b/tidb-cloud/byoc/byoc-automated-deployment.md new file mode 100644 index 0000000000000..7e9f1c4209c61 --- /dev/null +++ b/tidb-cloud/byoc/byoc-automated-deployment.md @@ -0,0 +1,50 @@ +--- +title: TiDB Cloud BYOC Automated Deployment +summary: This document outlines the automated deployment process for TiDB Cloud BYOC on AWS. +--- + +# TiDB Cloud BYOC Automated Deployment + +With the AWS environment prepared and IAM permissions established, the TiDB Cloud team will initiate the automated provisioning process. + +> **Note:** +> +> This phase is fully managed by TiDB Cloud. No customer action is required until you receive the completion notification. + +## Deployment process + +The deployment consists of two automated steps: + +### Step 1: Image synchronization (approx. 1-2 hours) + +* **Customer action:** Select the AWS Region where the BYOC deployment will be created and provide the Region information to your TiDB Cloud representative. +* **What happens:** Database container images are synchronized from the TiDB Cloud central repository to your AWS account's region. + +> **Note:** +> +> This step is time-intensive only for the **first BYOC deployment** in a new region. Subsequent deployments in the same region will reuse the existing images and complete significantly faster. + +### Step 2: Infrastructure provisioning (approx. 3 hours) + +**Action**: The system automatically provisions dedicated resources within your AWS account, including: + +* **Network Environment (VPC & Networking):** Creates an isolated VPC to provide a secure network foundation for the database cluster. + +* **Control Plane Initialization:** Deploys essential management components responsible for the database's full lifecycle management. This includes automated resource provisioning, service scheduling, elastic scaling, and failure recovery—all executed automatically with no manual intervention required. + +* **Compute Resource Provisioning:** Creates two EKS clusters serving the following purposes: + + * Deploy Observability Services: Hosts components such as Prometheus and Grafana to collect monitoring metrics and logs. + * Deploy Data Plane Management Nodes: Hosts components (such as the TiDB Operator) to provide the runtime environment for the subsequent creation of TiDB compute and storage nodes. + +## Deployment completion + +Once the automation completes: + +1. **Notification**: You will be notified by the TiDB Cloud Team that the BYOC Region is ready. + +2. **Billing Activation:** + + **AWS Invoice:** You will begin seeing charges from AWS for the underlying resources (EC2, NAT Gateways, EKS). + +**Status:** Your BYOC region is now fully operational. You may proceed to [**BYOC service initialization**](/tidb-cloud/byoc/byoc-service-initialization.md) to create your first TiDB instance. diff --git a/tidb-cloud/byoc/byoc-iam-configuration.md b/tidb-cloud/byoc/byoc-iam-configuration.md new file mode 100644 index 0000000000000..01b407eca947b --- /dev/null +++ b/tidb-cloud/byoc/byoc-iam-configuration.md @@ -0,0 +1,54 @@ +--- +title: TiDB Cloud BYOC IAM Configuration +summary: This document outlines the IAM configuration required for TiDB Cloud BYOC controller access. +--- + +# TiDB Cloud BYOC IAM Configuration + +Once the AWS environment is prepared, you must authorize the TiDB Cloud Control Plane to manage resources within your account. This is achieved by executing a bootstrapping script that establishes the necessary IAM Roles based on the Principle of Least Privilege. + +## Preparation + +Before executing the script, ensure you have the following: + +1. **AWS CLI installed:** The CLI must be configured with an Access Key that has permissions to create IAM roles and policies. +2. **TiDB Cloud account info:** Contact your TiDB Cloud support representative to obtain the **Control Plane Account ID** and **Clinic Account ID**. + +## Gather parameters + +Use the table below to map the required parameters for the script: + +| Parameter | Source | Description | +| :---- | :---- | :---- | +| `` | **TiDB Support** | The AWS Account ID of the TiDB Control Plane. | +| `` | **TiDB Support** | The AWS Account ID for the TiDB Clinic service. | +| `` | [Required information](/tidb-cloud/byoc/byoc-prepare-environment-aws.md#summary-required-information) | The ID of the TiDB Cluster Hosted Zone you created. | +| `` | [Required information](/tidb-cloud/byoc/byoc-prepare-environment-aws.md#summary-required-information) | The ID of the Observability Hosted Zone you created. | +| `` | [Required information](/tidb-cloud/byoc/byoc-prepare-environment-aws.md#summary-required-information) | The ARN of the Private CA you created. | + +## Execute bootstrapping script + +1. Download the script from the [PingCAP GitHub repository](https://github.com/tidbcloud/byoc-account-setup/tree/main). + +2. In your terminal, run the following command. Note to replace the placeholders with your actual values. + + ```bash + sh tidbcloud-byoc-setup.sh \ + --control-plane-id \ + --clinic-id \ + --tidb-hz-id \ + --o11y-hz-id \ + --pca-arn + ``` + +3. Monitor the process. Upon execution, the script initiates AWS CloudFormation to provision and update resources. You can observe a log stream in the terminal displaying status messages such as `waiting for changeset to be created` and `successfully created/updated stack`. + + + +## Verification + +After execution, the script will output the ARNs of the created IAM roles. + +* **Action required:** Share the **execution result/log** with your TiDB Cloud representative. + +* **Next step:** Once TiDB Cloud verifies the roles, the [automated deployment](/tidb-cloud/byoc/byoc-automated-deployment.md) will be triggered. diff --git a/tidb-cloud/byoc/byoc-onboarding-overview.md b/tidb-cloud/byoc/byoc-onboarding-overview.md new file mode 100644 index 0000000000000..e13830c30873a --- /dev/null +++ b/tidb-cloud/byoc/byoc-onboarding-overview.md @@ -0,0 +1,36 @@ +--- +title: TiDB Cloud BYOC Onboarding Overview +summary: Overview of the TiDB Cloud BYOC onboarding process, detailing the responsibilities and steps for both the customer and TiDB Cloud team. +--- + +# TiDB Cloud BYOC Onboarding Overview + +TiDB Cloud BYOC (Bring Your Own Cloud) is an enterprise solution that lets you run the data plane in your own cloud environment while retaining the fully managed experience of TiDB Cloud. + +The TiDB Cloud BYOC deployment process is a collaborative effort between your organization and the TiDB Cloud team. The process includes secure infrastructure preparation, automated provisioning, and comprehensive validation. + + + +## Deployment phases + +| Phase | Responsibility | Description | +| :---- | :---- | :---- | +| [**Phase 1: Environment preparation**](/tidb-cloud/byoc/byoc-prepare-environment-aws.md) | **Customer** | Prepare the AWS foundation required for deployment. This includes creating a dedicated AWS account configuring Route 53 Hosted Zones setting up the private certificate authority (PCA). | +| [**Phase 2: IAM bootstrapping**](/tidb-cloud/byoc/byoc-iam-configuration.md) | **Customer** | Execute the provided bootstrapping scripts to install the necessary IAM roles and policies. This authorizes the TiDB Cloud Control Plane to securely manage resources within your AWS account. | +| [**Phase 3: Automated deployment**](/tidb-cloud/byoc/byoc-automated-deployment.md) | **TiDB Cloud** | Once IAM permissions are verified, TiDB Cloud automatically provisions the VPC, EKS clusters, and control plane resources. Note: This process is **fully automated** and requires no customer intervention. | +| [**Phase 4: Service initialization**](/tidb-cloud/byoc/byoc-service-initialization.md) | **Customer** | Create your TiDB instance via the console. Subsequently, deploy the Bastion Host and authentication scripts to establish secure maintenance channels (Tailscale) and observability pipelines. Note: You may also choose to establish maintenance channels using your own custom methods. | +| [**Phase 5: Validation**](/tidb-cloud/byoc/joint-validation.md) | **Joint** | Both teams collaborate to validate connectivity, verify metric collection, and confirm system health to ensure the BYOC environment is ready for use. | + +> **Note:** +> +> Each phase requires timely coordination between teams. We recommend assigning dedicated resources from both organizations to ensure smooth progression through all stages. + +## Architecture overview + +TiDB Cloud BYOC employs a strict separation between the Control Plane and the Data Plane. Your data remains entirely within your AWS account. The Control Plane connects to your VPC exclusively via AWS PrivateLink. No public internet exposure is required for database nodes. + +> **Note:** +> +> This architecture defaults to a Multi-AZ deployment for production high availability, but also supports a Single-AZ deployment for Proof of Concept (POC) or cost optimization scenarios. + +![TiDB Cloud BYOC Architecture](/media/tidb-cloud/byoc-architecture.png) diff --git a/tidb-cloud/byoc/byoc-prepare-environment-aws.md b/tidb-cloud/byoc/byoc-prepare-environment-aws.md new file mode 100644 index 0000000000000..98a22c4f46208 --- /dev/null +++ b/tidb-cloud/byoc/byoc-prepare-environment-aws.md @@ -0,0 +1,183 @@ +--- +title: Prepare Your BYOC Environment in AWS +summary: Instructions for preparing the necessary infrastructure components for TiDB Cloud BYOC deployment. +--- + +# Prepare Your BYOC Environment in AWS + +Before initiating the BYOC deployment, prepare the required infrastructure components in your AWS environment. Complete the following steps in order. + +## Step 1. Retrieve TiDB Cloud Organization ID + +Unique identifier for your organization within TiDB Cloud. + +1. Log in to the [TiDB Cloud Console](https://tidbcloud.com/). + + If you do not have a TiDB Cloud account, click [here](https://tidbcloud.com/free-trial) to sign up. You can sign up with an email and password to manage TiDB Cloud credentials, or use single sign-on (SSO) via Google, GitHub, or Microsoft accounts. + +2. In the left navigation pane, click your profile icon > **Organization Settings**. + +3. Under **Organization Information**, copy the **Organization ID** and save it for later use. + +## Step 2. Prepare an AWS account + +We strongly recommend using a **dedicated AWS account** for your BYOC environment to ensure isolation, simplified compliance, and accurate cost management. + +- **Account ID:** Ensure you have the 12-digit AWS Account ID ready. +- **Permissions:** Ensure you have AdministratorAccess or equivalent privileges to configure IAM roles and Route 53. + +## Step 3. Select region and availability zones (AZs) + +TiDB is a distributed database that requires specific infrastructure for high availability. + +1. **Region:** Select the AWS Region where the database will be deployed. +2. **Availability zones (AZs):** Depending on your deployment goal, choose one of the following configurations: + + - **Option A: Production Environment (Multi-AZ).** You **must** identify at least **3 AZs** in your selected region. For example, `us-west-2a`, `us-west-2b`, `us-west-2c`. + + - **Option B: POC / Cost Optimization (Single-AZ).** Select exactly **1 AZ**. For example, `us-west-2a`. + + > **Note:** + > + > Multi-AZ deployment functionality is disabled for this configuration. + +## Step 4. Create hosted zones for TiDB and observability (O11Y) + +You need to create two separate **public hosted zones** in Amazon Route 53. + +1. **Create the Zones.** + + Follow the [Creating a public hosted zone in AWS documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html) to create the following: + + - **TiDB Cluster Zone:** Manages DNS for the TiDB Service. + + * Naming Constraint: Max 38 characters. + * Example: `byoc.cluster.example.com`. + + - **Observability (O11y) Zone:** Manages DNS for monitoring tools (Grafana/Prometheus). + + * Naming Constraint: Max 34 characters. + * Example: `o11y.cluster.example.com`. + +2. **Delegate DNS.** + + > **Important:** + > + > **DNS Delegation Required.** After creating the hosted zones, you **must** add Route 53 Name Servers (NS records) to your parent domain's DNS configuration (for example, in your corporate DNS or parent AWS zone). + + - **Action:** Copy the 4 NS records from your new Route 53 zones and add them to the parent domain. + - **Result:** Without this, internal service discovery will fail. + +3. **Verify the DNS delegation.** + + Verify the DNS delegation by running `nslookup` or `dig` from any internet-connected command-line environment. The domain must resolve correctly. + + ```bash + nslookup -type=ns {hosted_zone_name} + nslookup -type=ns byoc-tidb.cluster.example.com + nslookup -type=ns o11y.cluster.example.com + ``` + + + + > **Note:** + > + > If you plan to deploy TiDB Cloud BYOC in **multiple AWS regions**, the same hosted zones can be shared across all regions, or you can choose to create dedicated hosted zones per region. See [Multi-Region Deployment](/tidb-cloud/byoc/multi-region-deployment.md) for detailed multi-region architecture configurations. | + +## Step 5. Set up private certificate authority (PCA) + +TiDB Cloud utilizes the AWS private certificate authority (PCA) service to issue certificates and the AWS Certificate Manager (ACM) service to manage digital certificates, ensuring secure communication between internal database cluster components via mTLS. + +To meet compliance requirements, TiDB Cloud BYOC integrates with a customer-provided PCA to issue identity certificates for data nodes using your enterprise's own domain. This ensures that the Root of Trust for all encrypted communications remains strictly within your organization's control. + +Therefore, you must prepare a valid Subordinate CA in the deployment region. Please follow the steps below: + +1. **Create a CA.** Follow [Create a private CA in AWS Private CA](https://docs.aws.amazon.com/privateca/latest/userguide/create-CA.html). + + Configuration: Ensure the validity period is set to at least **20 years**. + +2. **Install the CA certificate.** Follow [Installing the CA certificate](https://docs.aws.amazon.com/privateca/latest/userguide/PCACertInstall.html). + + Prerequisite: You must have an active Root CA. + +3. **Record ARN.** Copy the **Subordinate CA ARN**. + + Example: `arn:aws:acm-pca:us-west-2:123456789012:ca/abcd-1234...` + +4. **Verify PCA information** from your AWS console. + + + +> **Note:** +> +> - **For POC or cost optimization**: If you are in the Proof of Concept (POC) phase, you may choose to use Self-Signed Certificates instead of AWS Private CA to reduce costs. Contact your TiDB Cloud Support Representative directly for specific configuration instructions regarding this option. +> - **For multi-region deployment**: Similar to hosted zones, the same private certificate authority (PCA) can be shared across all regions for multi-region deployments. Alternatively, you can create a dedicated PCA for each new region. See [Multi-Region Deployment](/tidb-cloud/byoc/multi-region-deployment.md) for details. + +## Step 6. Plan network CIDR ranges + +Before starting the BYOC deployment, plan dedicated CIDR ranges for the TiDB cluster and observability (O11Y) infrastructure. This planning must be evaluated on a **per-region** basis. + +The CIDR ranges will be used by TiDB Cloud to provision the required AWS networking resources for the BYOC environment. + +Prepare the following information: + +| Item | Description | Example | +| ----- | ----- | ----- | +| TiDB Cluster CIDR | CIDR range reserved for TiDB cluster and dataplane resources. | `10.10.0.0/16` | +| O11Y CIDR | CIDR range reserved for observability infrastructure and related services. | `10.20.0.0/16` | + +When planning the CIDR ranges, ensure that: + +**CIDR Planning Rules & Constraints:** When planning the CIDR ranges, ensure you strictly follow these connectivity rules: + +1. **Internal Isolation:** The TiDB Cluster CIDR and O11Y CIDR within the same environment must not overlap with each other. + +2. **VPC Peering Rule:** + + * **Cannot Overlap:** Anything that will be peered *cannot* overlap. If you plan to establish VPC Peering between the TiDB Cluster VPC and your existing application VPCs, on-premises networks, or VPNs, the CIDR ranges must be strictly de-conflicted. + * **Can Overlap:** Things that will *never* be peered can safely overlap with the TiDB Cloud BYOC environment. + +3. **Cross-Cluster Replication (Critical):** If you plan to deploy multiple TiDB clusters (whether in the same region or across different regions) and eventually want to **replicate data between them** (for example, using TiCDC for Disaster Recovery or data consolidation), their respective TiDB Cluster CIDR ranges **must be de-conflicted**. + +Provide the planned CIDR ranges to your TiDB Cloud representative before the automated deployment starts. + +## Summary: Required information + +Fill out the table below with the information gathered in steps above and share it with your TiDB Cloud representative to initiate the deployment. + +**Required information:** + +| Category | Details to provide | Example | Comments | +| :---- | :---- | :---- | :---- | +| **TiDB Cloud Organization ID** | Unique identifier for your TiDB Cloud org | `1372813089209270552` | Step 1 | +| **AWS Account ID** | 12-digit AWS account number | `123456789012` | Step 2 | +| **AWS Region** | Region selected for deployment | `us-west-2`, `us-east-1`, `us-east-2` | Step 3. For multi-region deployment, list all regions. | +| **Availability Zones** | 3 AZs or single AZ per region (specify names and ID) | **Us-east-1:** `us-east-1a`, `use1-az1`, `us-east-1b`, `use1-az2`, `us-east-1c`, `use1-az4`; **Us-east-2:** `us-east-2a`, `use2-az1`, `us-east-2b`, `use2-az2`, `us-east-2c`, `use2-az3`; **Us-west-2:** `us-west-2a`, `usw2-az1` | Step 3. Note to meet the AZ quantity requirement for **each** selected region. | +| **Subordinate CA ARN** | AWS ACM Private CA ARN | `arn:aws:acm-pca:us-west-2:123456789012:ca/abcd-1234` | Step 5. The ARN can be shared across multiple regions. | +| **Hosted Zone Names & Host Zone ID** | TiDB Cluster Zone, Observability (O11Y) Zone | **Hosted TiDB cluster zone name:** `clusters.byoc-0929.pingcap.net`; **Hosted TiDB cluster zone ID:** `Z1039122VAY4T8UNWR8E`. **Hosted O11Y zone name:** `o11y.byoc-0929.pingcap.net`; **Hosted O11Y zone ID:** `Z10389823CTXFNM7VG79P`. | Step 4. The zone names and IDs can be shared across multiple regions. | +| **CIDR** | Customer-planned CIDR range for the TiDB cluster, Customer-planned CIDR range for the O11Y cluster | **TiDB cluster CIDR:** `10.10.0.0/16`; **O11Y cluster CIDR:** `10.20.0.0/16` | Step 6 | +| **Image Sync Region** | Region ID chosen for image synchronization | `us-west-2` | Refer to [image synchronization](/tidb-cloud/byoc/byoc-automated-deployment.md#deployment-process) for details. | + +## Review and increase AWS service quotas + + + +### Recommended Quota Limits + +You can request quota increases for the following resources in your target AWS region: + +* **Amazon EC2 (vCPU-based quotas):** Increase relevant instance family quotas (e.g., Standard instances) to support up to 1024 vCPUs. +* **Amazon EBS (gp3 storage):** Increase General Purpose (gp3) volume storage quota to 150 TiB. +* **Amazon EKS / Cluster Scaling Capacity:** Ensure the environment supports scaling to at least 40 worker nodes, including: + * EC2 capacity + * Auto Scaling Group limits + * EKS managed node group limits + +### How to Request a Quota Increase + +1. Log in to the AWS Management Console. +2. Navigate to Service Quotas. +3. Search for the relevant services: Amazon EC2， Amazon EBS，Amazon EKS +4. Select the required quota. +5. Click Request quota increase. +6. Enter the target values and submit the request. diff --git a/tidb-cloud/byoc/byoc-service-initialization.md b/tidb-cloud/byoc/byoc-service-initialization.md new file mode 100644 index 0000000000000..be162c50ca39b --- /dev/null +++ b/tidb-cloud/byoc/byoc-service-initialization.md @@ -0,0 +1,70 @@ +--- +title: Create a TiDB Cloud BYOC Instance +summary: This document outlines the process for creating a TiDB Cloud BYOC instance and setting up secure access. +--- + +# Create a TiDB Cloud BYOC Instance + +Following the successful deployment of your BYOC infrastructure, the next phase involves creating your first database instance and establishing secure administrative access channels. + +## Create TiDB Instance + +### Create a new TiDB Instance + +You can now provision TiDB instances directly via the TiDB Cloud Console. + +1. Initiate instance creation. Log in to the [TiDB Cloud Console](https://tidbcloud.com/) and follow the standard workflow to create a new instance. + + + +2. Select the region and specifications that match your workload requirements. + + * Initial Setup Time: The creation of the **first instance** typically takes approximately **1 hour** as the system initializes the Kubernetes environment. + * Subsequent instances: Creating additional instances in the same region will only take a few minutes. + +3. Consult with your TiDB Cloud representative to determine the appropriate Request Unit (RU) settings for your initial connectivity and functional tests. They will recommend a configuration based on your specific testing requirements. + +### Restore a new instance from Amazon S3 + +After successfully preparing your backup file in Amazon S3, you can proceed to restore the data into your newly created TiDB Cloud BYOC instance. + +1. **Configure Amazon S3 Access (AK/SK).** + + To allow TiDB Cloud to read your S3 backup, you must configure external storage access by generating an AWS Access Key ID and Secret Access Key (AK/SK) with the appropriate S3 read permissions. + + Follow the detailed instructions here: [Configure Amazon S3 access using an AWS Access Key](https://docs-preview.pingcap.com/tidbcloud/configure-external-storage-access/#configure-amazon-s3-access-using-an-aws-access-key). + +2. **Execute the Restore Process.** + + Once the access keys are configured, you can initiate the restore job from the TiDB Cloud Console. + + For step-by-step restoration procedures, refer to [Restore backups from cloud storage](/tidb-cloud/premium/backup-and-restore-premium.md#restore-backups-from-cloud-storage). + +## (Optional) Deploy secure access solution (bastion host) + +To enable TiDB Support to assist with troubleshooting and observability, a secure access channel must be established. This is achieved by deploying a hardened Bastion Host within your VPC that connects via **Tailscale** (a secure VPN protocol). + +> **Note:** +> +> - This step is **optional**. You may choose to provide your own secure login method for maintenance. +> - The Bastion Host is used only for troubleshooting and does not need to maintain a persistent connection. You may terminate this channel at any time. +> - The Bastion Host deployment instruction for Single-AZ will be provided in the separated tab. + +1. **Execute the deployment script.** + + 1. Download the bastion host deployment script from the [PingCAP GitHub repository](https://github.com/tidbcloud/byoc-account-setup/tree/main/bastion). + + 2. Execute Terraform deployment. + + What this deployment does: + + * Provisions a hardened EC2 Bastion Host in your VPC. + * Creates an EKS Access Entry to allow the Bastion limited access to the Kubernetes cluster for management tasks. + * Establishes a secure Tailscale tunnel upon startup. + +2. **Verify access.** + + After the script completes: + + 1. **Check AWS Console:** verify that the Bastion Host EC2 instance is running. + 2. **Confirm with TiDB:** Notify your TiDB Cloud Representative. They will verify that the PingCAP engineering team can successfully connect via the internal secure tunnel. diff --git a/tidb-cloud/byoc/joint-validation.md b/tidb-cloud/byoc/joint-validation.md new file mode 100644 index 0000000000000..34da42ac711f0 --- /dev/null +++ b/tidb-cloud/byoc/joint-validation.md @@ -0,0 +1,24 @@ +--- +title: TiDB Cloud BYOC Joint Validation +summary: This document outlines the joint validation process for TiDB Cloud BYOC deployments. +--- + +# TiDB Cloud BYOC Joint Validation + +The final phase ensures that the environment is stable, secure, and fully observable. The TiDB Cloud team will collaborate with you to perform the following checks. + +## Validation checklist + +| Category | Validation Item | Owner | +| :---- | :---- | :---- | +| **Connectivity** | SQL Endpoint: verify connectivity to both private and public SQL endpoints from your application servers. | Customer | +| **Connectivity** | Secure Tunnel (optional): confirm stable VPN links via the Bastion Host. | TiDB Cloud | +| **Observability** | Metrics: verify that system metrics are populating correctly in Grafana and Prometheus. | TiDB Cloud | +| **Observability** | Logging: Confirm that logs are being collected. | TiDB Cloud | +| **Security** | Audit: verify that AWS CloudTrail is actively logging access attempts to the Bastion Host. | Customer | +| **Alerting** | Test Alerts: trigger a test alert to confirm the notification delivery system is functioning. | Joint | + +Once all validation items are marked as **Pass**: + +1. The deployment is officially considered **Complete**. +2. You can proceed with data migration or application integration. diff --git a/tidb-cloud/byoc/multi-region-deployment.md b/tidb-cloud/byoc/multi-region-deployment.md new file mode 100644 index 0000000000000..4d06b5a4c3933 --- /dev/null +++ b/tidb-cloud/byoc/multi-region-deployment.md @@ -0,0 +1,226 @@ +--- +title: TiDB Cloud BYOC Multi-Region Deployment +summary: This document outlines the process for deploying TiDB Cloud BYOC across multiple AWS regions. +--- + +# TiDB Cloud BYOC Multi-Region Deployment + +TiDB Cloud BYOC supports deployments across **multiple AWS Regions**. The same IAM roles can be reused across regions, so you do not need to recreate the BYOC IAM roles when enabling an additional region. + +The following two scenarios apply to multi-region deployments: + +| Scenario | Description | Script | +| ----- | ----- | ----- | +| New multi-region deployment | No BYOC region has been deployed yet, and multiple regions are planned from the beginning. | `tidbcloud-byoc-setup.sh` | +| Add a region to an existing deployment | One or more BYOC regions have already been deployed, and an additional region will be enabled later. | `tidbcloud-byoc-update.sh` | + +* For a new deployment with multiple planned regions, see [Scenario 1: New multi-region deployment](#scenario-1-new-multi-region-deployment). +* To add a region to an existing BYOC deployment, see [Scenario 2: Add a region to an existing deployment](#scenario-2-add-a-region-to-an-existing-byoc-deployment). + +## Resource planning: shared and dedicated resources + +Before configuring multiple regions, determine whether the following foundational resources will be shared across regions or dedicated to each region: + +* AWS private certificate authority (PCA) +* Route 53 hosted zone for TiDB +* Route 53 hosted zone for O11Y + +### Shared resources + +The same PCA, TiDB hosted zone, and O11Y hosted zone can be shared across all enabled regions. + +In this configuration, provide the primary PCA and Hosted Zones through the standard parameters and omit the corresponding \--additional-\* parameters. + +### Dedicated resources + +You can prepare a separate PCA, TiDB hosted zone, and O11Y hosted zone for each additional region. + +The primary region resources are provided through the standard parameters: + +* `--pca-arn` +* `--tidb-hz-id` +* `--o11y-hz-id` + +Resources for additional regions are provided through: + +* `--additional-pca-arns` +* `--additional-tidb-hz-ids` +* `--additional-o11y-hz-ids` + +For two or more additional regions, provide the values as comma-separated lists in the same regional order. + +### Mixed resources + +Shared and dedicated resources can be combined. + +For example, all regions can share the same PCA while using separate Hosted Zones. + +Each additional resource parameter is independent. Omit a parameter when the corresponding resource will remain shared with the primary region. + +## Scenario 1: New multi-region deployment + +Use this section if you have not deployed any BYOC regions yet and plan to deploy multiple regions from the start. + +Run `tidbcloud-byoc-setup.sh` to initialize the BYOC environment and configure the required resources. + +### All regions share the same resources + +When all regions share the same PCA and hosted zones, run the standard setup command: + +```shell +bash tidbcloud-byoc-setup.sh \ + --control-plane-id \ + --clinic-id \ + --tidb-hz-id \ + --o11y-hz-id \ + --pca-arn +``` + +No `--additional-*` parameters are required. + +### Additional regions use dedicated resources + +Provide the primary region resources through the standard parameters and the additional region resources through the `--additional-*` parameters: + +```shell +bash tidbcloud-byoc-setup.sh \ + --control-plane-id \ + --clinic-id \ + --tidb-hz-id \ + --o11y-hz-id \ + --pca-arn \ + --additional-tidb-hz-ids , \ + --additional-o11y-hz-ids , \ + --additional-pca-arns , +``` + +The values in all comma-separated lists must follow the same regional order. For example: + +* The first value represents Region 2. +* The second value represents Region 3. + +### Mixed shared and dedicated resources + +The following example shares one PCA across all regions while using dedicated hosted zones: + +```shell +bash tidbcloud-byoc-setup.sh \ + --control-plane-id \ + --clinic-id \ + --tidb-hz-id \ + --o11y-hz-id \ + --pca-arn \ + --additional-tidb-hz-ids , \ + --additional-o11y-hz-ids , +``` + +Because the PCA is shared, `--additional-pca-arns` is omitted. + +## Scenario 2: Add a region to an existing BYOC deployment + +Use this section if one or more BYOC regions have already been deployed and you want to add one or more new regions. + +Do not run `tidbcloud-byoc-setup.sh` again. + +Use `tidbcloud-byoc-update.sh` to update the existing CloudFormation stacks. The existing IAM roles and previously configured stack parameters will be reused. + +### Before adding the region + +Before running the update script: + +1. Confirm the AWS Regions to be added. +2. Select the Availability Zones for the new regions. +3. Plan the TiDB Cluster CIDR and O11Y CIDR for each new region. +4. Confirm whether each new region will: + * share the existing PCA and hosted zones, or + * use dedicated PCA and hosted zones. +5. Review and increase AWS service quotas in each new region. +6. Share the information for the new regions with your TiDB Cloud representative. + +The CIDR ranges for the new regions must not overlap with: + +* the TiDB Cluster CIDR and O11Y CIDR within the same region; +* existing application VPCs, on-premises networks, or VPN networks that will be connected through VPC Peering or VPN; or +* other TiDB clusters that will participate in cross-region replication. + +### Share existing PCA and hosted zones + +Use this option if all new regions will share the PCA and hosted zones already used by the existing deployment. + +No additional resource parameters are required: + +```shell +bash tidbcloud-byoc-update.sh \ + --stack all +``` + +The existing resources will continue to be used by all enabled regions. + +A plain \--stack all update is safe when no new multi-region resource values are required. + +### Use dedicated resources for the new regions + +Use this option if the new regions require dedicated PCAs, TiDB hosted zones, or O11Y hosted zones. + +Provide the resources for the new Regions through the corresponding `--additional-*` parameters: + +```shell +bash tidbcloud-byoc-update.sh \ + --stack all \ + --additional-pca-arns , \ + --additional-tidb-hz-ids , \ + --additional-o11y-hz-ids , + +``` + +Each parameter is independent. Omit a parameter when the corresponding resource will remain shared with the existing Regions. + +The values in all comma-separated lists must follow the same regional order. For example: + +* The first value in each list represents Region 2. +* The second value in each list represents Region 3. + +### Use a mix of shared and dedicated resources + +The new regions can share some existing resources while using dedicated resources for others. + +For example, to share the existing PCA while using dedicated hosted zones for the new regions: + +```shell +bash tidbcloud-byoc-update.sh \ +--stack all \ +--additional-tidb-hz-ids , \ --additional-o11y-hz-ids , +``` + +Because the existing PCA is shared, `--additional-pca-arns` is omitted. + +The resource strategy can also differ between the new regions. However, the values supplied for each `--additional-*` parameter must remain aligned with the same regional order. + +### Add Regions When Multiple Regions Already Exist + +When the existing deployment already includes multiple regions, use the same update process to add further regions. + +The multi-region resource values are stored in the CloudFormation stacks and reused during future updates. When running the update command, provide any new or changed resource values required by the Regions being added. + +For example, if Region 1 is the primary region, Region 2 is already configured, and Region 3 is being added with dedicated resources: + +```shell +bash tidbcloud-byoc-update.sh \ + --stack all \ + --additional-pca-arns , \ + --additional-tidb-hz-ids , \ + --additional-o11y-hz-ids , +``` + +Ensure that previously configured and newly added resource values remain in the correct regional order. + +### Complete the Regional Deployment + +Updating the CloudFormation stacks prepares the account-level permissions and resource configuration required by the new regions. It does not by itself complete the regional infrastructure deployment. + +After the update succeeds: + +1. Share the script execution result with your TiDB Cloud representative. +2. TiDB Cloud verifies the updated IAM and regional resource configuration. +3. TiDB Cloud initiates automated infrastructure provisioning for the new regions. +4. After provisioning completes, perform the joint validation described in Section 5 for each new region. diff --git a/tidb-cloud/byoc/security-hardening.md b/tidb-cloud/byoc/security-hardening.md new file mode 100644 index 0000000000000..70fab3d9d4808 --- /dev/null +++ b/tidb-cloud/byoc/security-hardening.md @@ -0,0 +1,61 @@ +--- +title: TiDB Cloud BYOC Security Hardening +summary: This document outlines the security hardening steps for TiDB Cloud BYOC deployments. +--- + +# TiDB Cloud BYOC Security Hardening + +After the BYOC environment has been fully delivered and is in production, you may choose to remove the bootstrap permissions used only during the installation phase to follow the **Principle of Least Privilege** recommended in cloud security best practices. + +These permissions involve two IAM roles: + +* **auto-deploy-cli**: The highest-privilege role used for creating infrastructure such as VPCs and EKS clusters. +* **auto-deploy-sync-image**: The role used to pull and synchronize images from TiDB Cloud. + +> **Important:** +> +> **For multi-region and multiple resource pools:** The `auto-deploy-cli` and `auto-deploy-sync-image` IAM roles are Global (Account-level) resources. If you plan to deploy TiDB Cloud BYOC in multiple AWS regions or provision multiple physically isolated Resource Pools within your account, it is recommended to delay this security hardening step until ALL environments are fully deployed. + +Depending on your requirements for **automatic upgrades**, you can choose one of the following options. + +## Option 1: Retain automatic upgrades, remove infrastructure deployment permissions + +**Goal:** Remove the `auto-deploy-cli` role while keeping the `auto-deploy-sync-image` role. + +**Impact:** + +* Security: The control plane can no longer create new infrastructure resources (e.g., VPCs) in your account. +* Maintainability: The cluster can still perform automatic upgrades, as image synchronization permissions are retained. + +**Steps:** + +1. Locate the CloudFormation template used during deployment: `tidbcloud-byoc-setup-deploy.yaml`. + +2. Edit the file. Find the `TiDBCloudAutoDeployRole` field and delete that line along with all its subordinate content, while keeping the `TiDBCloudAutoDeploySyncImageRole` section intact. + +3. Apply the updated script in your terminal: + + ```shell + bash tidbcloud-byoc-update.sh --stack deploy + ``` + +## Option 2: Remove all bootstrap permissions (automatic upgrades disabled) + +**Goal:** Remove both the `auto-deploy-cli` and `auto-deploy-sync-image` roles. + +**Impact:** + +* Maximum security: All IAM roles used during the bootstrap phase are removed. +* Feature limitation: Automatic upgrades will no longer be available. To upgrade database components in the future, you must redeploy the sync-image role. + +**Steps:** + +Delete the corresponding CloudFormation stack via AWS CLI: + +```shell +aws cloudformation delete-stack --stack-name tidbcloud-byoc-setup-deploy +``` + +> **Important:** +> +> Regardless of the option you choose, **do not delete stacks with** `dataplane` **or** `o11y` **suffixes** (for example, `tidbcloud-byoc-setup-dataplane`), because they provide runtime permissions required for cluster operation, monitoring, and backups.