byoc: update onboarding docs - #23350
Conversation
lilin90
added
BYOC
ti-chi-bot
Bot
added
contribution
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughBYOC documentation updates revise AWS quota planning, IAM and deployment handoffs, add a dedicated bastion host guide, update service initialization references, and add post-validation guidance. ChangesBYOC documentation flow
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 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: 5
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: de7c54c3-94d9-4a7a-8c16-4b2ea41e7b21
📒 Files selected for processing (8)
TOC-tidb-cloud-byoc.mdtidb-cloud/byoc/byoc-automated-deployment.mdtidb-cloud/byoc/byoc-bastion-host.mdtidb-cloud/byoc/byoc-iam-configuration.mdtidb-cloud/byoc/byoc-onboarding-overview.mdtidb-cloud/byoc/byoc-prepare-environment-aws.mdtidb-cloud/byoc/byoc-service-initialization.mdtidb-cloud/byoc/joint-validation.md
|
|
||
| ## Audit logs | ||
|
|
||
| For security and compliance, each bastion host is configured to collect a detailed audit trail of executed commands through the [auditd service](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/6/html/security_guide/chap-system_auditing). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace the link that fails CI.
The Red Hat URL returns HTTP 403 in the link checker, blocking the documentation pipeline. Remove the hyperlink or replace it with an accessible auditd reference. (man7.org)
| For security and compliance, each bastion host is configured to collect a detailed audit trail of executed commands through the [auditd service](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/6/html/security_guide/chap-system_auditing). | |
| For security and compliance, each bastion host is configured to collect a detailed audit trail of executed commands through the `auditd` service. |
As per path instructions, Markdown issues that can be fixed with a contiguous replacement must include a committable suggestion.
🧰 Tools
🪛 GitHub Actions: ci / external-links-in-changed-lines (pull_request) / 0_linkChecker.txt
[error] 180-180: lychee link check failed: [403] https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/6/html/security_guide/chap-system_auditing rejected with status code 403 Forbidden.
🪛 GitHub Actions: ci / external-links-in-changed-lines (pull_request) / linkChecker
[error] 180-180: lychee link check failed: HTTP 403 Forbidden for https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/6/html/security_guide/chap-system_auditing (at 180:129). Rejected status code: 403.
Sources: Path instructions, Pipeline failures
| | [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 4: Service initialization](/tidb-cloud/byoc/byoc-service-initialization.md) | Customer | Create your TiDB instance via the console. Subsequently, [configure a Bastion Host](/tidb-cloud/byoc/byoc-bastion-host.md) 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. | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Mark Bastion Host configuration as optional.
The linked Bastion Host guide states that this configuration is optional, but this phase currently presents it as a required customer step.
As per path instructions, this contiguous Markdown fix is provided as a committable suggestion.
| | [Phase 4: Service initialization](/tidb-cloud/byoc/byoc-service-initialization.md) | Customer | Create your TiDB instance via the console. Subsequently, [configure a Bastion Host](/tidb-cloud/byoc/byoc-bastion-host.md) 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 4: Service initialization](/tidb-cloud/byoc/byoc-service-initialization.md) | Customer | Create your TiDB instance via the console. Subsequently, optionally [configure a Bastion Host](/tidb-cloud/byoc/byoc-bastion-host.md) 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. | |
Sources: Coding guidelines, Path instructions
| - **Amazon EKS and scaling-related quotas**: quota values that affect EKS clusters and node scaling capacity, including EC2 capacity, Auto Scaling Group limits, and 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 | ||
| 3. Search for the relevant services: Amazon EC2, Amazon EBS, and Amazon EKS. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Include Amazon EC2 Auto Scaling in the quota-request steps.
The quota categories mention Auto Scaling Group limits, but the service search instructions list only EC2, EBS, and EKS. Users may therefore skip the quota service needed for those limits.
Suggested replacement
| - **Amazon EKS and scaling-related quotas**: quota values that affect EKS clusters and node scaling capacity, including EC2 capacity, Auto Scaling Group limits, and 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 | |
| 3. Search for the relevant services: Amazon EC2, Amazon EBS, and Amazon EKS. | |
| 4. Search for the relevant services: Amazon EC2, Amazon EC2 Auto Scaling, Amazon EBS, and Amazon EKS. |
| > **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.** | ||
| For deployment and verification steps, see [Configure a Bastion Host for {{{ .byoc }}}](/tidb-cloud/byoc/byoc-bastion-host.md). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Preserve the Bastion Host’s maintenance use case.
The dedicated guide describes authorized troubleshooting and maintenance, so “used only for troubleshooting” incorrectly narrows its purpose.
As per path instructions, this contiguous Markdown fix is provided as a committable suggestion.
| > **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.** | |
| For deployment and verification steps, see [Configure a Bastion Host for {{{ .byoc }}}](/tidb-cloud/byoc/byoc-bastion-host.md). | |
| > **Note:** | |
| > | |
| > - This step is **optional**. You may choose to provide your own secure login method for maintenance. | |
| > - The Bastion Host is used for authorized troubleshooting and maintenance and does not need to maintain a persistent connection. You may terminate this channel when it is not needed. |
Sources: Coding guidelines, Path instructions
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: c24ada41-3abc-4fba-a34b-264a80ed4814
📒 Files selected for processing (5)
TOC-tidb-cloud-byoc.mdtidb-cloud/byoc/byoc-configure-bastion-host.mdtidb-cloud/byoc/byoc-iam-configuration.mdtidb-cloud/byoc/byoc-onboarding-overview.mdtidb-cloud/byoc/byoc-service-initialization.md
| 5. In `terraform.tfvars`, configure the required fields: | ||
|
|
||
| - `aws_region`: the AWS region where your {{{ .byoc }}} environment is deployed, such as `us-west-2`. | ||
| - `tidbcloud_tenant_id`: your TiDB Cloud tenant ID. | ||
| - `bastions`: the bastion host configurations. You can configure bastions for `tidb` and `o11y`. | ||
| - `<bastion_type>.eks_cluster_name`: the EKS cluster name for the bastion type, such as `tidb.eks_cluster_name` or `o11y.eks_cluster_name`. | ||
| - `<bastion_type>.auth_key`: the Tailscale authentication key provided by TiDB Cloud. | ||
| - `<bastion_type>.subnet_id`: for Single-AZ deployments only, the subnet ID for the corresponding EKS cluster. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Treat the Terraform variables file and authentication keys as secrets.
The guide asks readers to paste Tailscale credentials into terraform.tfvars but does not warn them not to commit or share the file. Add explicit handling guidance to prevent credential leakage.
As per path instructions, this Markdown fix is provided as a committable suggestion.
Suggested replacement
| 5. In `terraform.tfvars`, configure the required fields: | |
| - `aws_region`: the AWS region where your {{{ .byoc }}} environment is deployed, such as `us-west-2`. | |
| - `tidbcloud_tenant_id`: your TiDB Cloud tenant ID. | |
| - `bastions`: the bastion host configurations. You can configure bastions for `tidb` and `o11y`. | |
| - `<bastion_type>.eks_cluster_name`: the EKS cluster name for the bastion type, such as `tidb.eks_cluster_name` or `o11y.eks_cluster_name`. | |
| - `<bastion_type>.auth_key`: the Tailscale authentication key provided by TiDB Cloud. | |
| - `<bastion_type>.subnet_id`: for Single-AZ deployments only, the subnet ID for the corresponding EKS cluster. | |
| - `<bastion_type>.auth_key`: the sensitive Tailscale authentication key provided by TiDB Cloud. Treat `terraform.tfvars` and generated Terraform state as sensitive: do not commit or share them, and restrict access to the state backend. |
Source: Path instructions
ti-chi-bot
Bot
added
size/XL
There was a problem hiding this comment.
Actionable comments posted: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5aa6e63a-ffb1-4f06-9062-33f818083408
📒 Files selected for processing (6)
TOC-tidb-cloud-byoc.mdtidb-cloud/byoc/byoc-automated-deployment.mdtidb-cloud/byoc/byoc-configure-iam-permissions.mdtidb-cloud/byoc/byoc-initialize-service.mdtidb-cloud/byoc/byoc-onboarding-overview.mdtidb-cloud/byoc/byoc-prepare-environment-aws.md
[LGTM Timeline notifier]Timeline:
|
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: lilin90 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
2 participants
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