--- name: deploy-tidbx-aws-multinode description: | Deploy or review the canonical AWS EC2 multi-node TiDB X test shape: upstream nextgen PD/TiDB, cloud-engine TiKV and tikv-worker, real AWS S3 through a TiKV instance profile, TiUP, and post-deploy validation. Use for empty TiDB X clusters built from prebuilt Linux artifacts. --- # Deploy TiDB X on AWS EC2 Use this skill for the canonical TiDB X test shape: | Layer | Required identity | |---|---| | Control plane | Upstream nextgen `tikv/pd`, `pingcap/tidb`, and `tikv/client-go` | | Data plane | `tidbcloud/cloud-storage-engine` `cloud-engine` TiKV and `tikv-worker` | | DFS | Real AWS S3 over HTTPS, authenticated through a TiKV EC2 instance profile | | Runtime | Fresh multi-node TiUP cluster with one co-located worker per TiKV host | Single-host smoke deployment uses `deploy-tidbx`; EKS deployment uses `tidb-onebox`. Source builds, data import, incident replay, and workload tests belong to their own plans. This skill consumes prebuilt artifacts and hands over an empty validated cluster. ## Required Inputs - AWS profile, expected account, region, AZ, VPC, subnet, key pair, and operator CIDR. - An approved S3 network path for that subnet: S3 gateway endpoint, NAT gateway, or public IP plus internet gateway. The route must be verified before mutation. - Cluster name, owner, TTL, cost ceiling, tags, and cleanup owner. - Existing Linux amd64 control/build host with AWS CLI access and network access to the cluster subnet. Run every bundled script from this host so the state file, TiUP metadata, rendered configuration, and artifacts share one context. - Explicit AMI/bootstrap SSH identity and TiDB runtime user, group, and home. Do not infer any identity from a workstation account name or an AMI default. - TiUP metadata version, keyspace name, ports, deploy directory, and data directory. - Node counts, instance types, and root EBS sizes. Size TiKV local storage for `db`, raft, WAL, cache, and working state even though SST data is stored in S3. - Globally unique S3 bucket, fresh prefix, and TiKV IAM role/profile name. - Prebuilt Linux amd64 tarballs for PD, TiDB, TiKV, and `tikv-worker`. - Run-log path for approvals, expected and actual results, deviations, and the exact cleanup inventory. ## Canonical Steps 1. Read `references/tidbx-aws-runbook.md` and render the approval block from `references/tidbx-aws-config.md`. Run `scripts/aws_plan.sh`. This step is complete when the account check passes and the user has approved the exact bill of materials, exposure, cost, TTL, and cleanup plan SHA256. Export that exact hash as `APPROVED_PLAN_SHA256`; any input change invalidates it. 2. Run `scripts/aws_provision.sh` in plan mode, then with `--apply`. This step is complete when the private encrypted bucket and fresh prefix exist, the bucket-scoped role/profile is attached only to every TiKV node, the S3 put/head/delete preflight passes, every EC2 status check passes, and each creation intent is recorded before each request and each returned resource ID or EC2 client token is recorded for reconciliation. 3. Verify all four tarballs using the artifact gate in `references/tidbx-aws-config.md`. This step is complete when each archive has one Linux amd64 binary at its root, PD/TiDB report Next Generation, TiKV and worker report Cloud Storage Engine, their exact commits are recorded, and TiKV and worker share one commit. 4. Render `references/topology-tidbx.yaml` and `references/cse-worker.toml` from the same identity, directory, port, S3, and PD values. This step is complete when no placeholder remains, both DFS configurations match, static S3 credentials are absent, and both TiKV remote URLs point to `http://127.0.0.1:9500/coprocessor`. 5. Deploy the fresh TiUP metadata, offline-patch PD, TiDB, and TiKV, then perform the first start. If the exact SYSTEM-keyspace error appears, follow `references/tidbx-aws-troubleshooting.md`. This step is complete when every TiUP component is Up with the intended runtime binaries. 6. Run `scripts/install_cse_worker.sh` for every TiKV host. This step is complete when every `cse-worker` service is active and every local `/healthz` returns successfully. 7. Run `scripts/validate_cluster.sh` in plan mode, then with `--apply`. This step is complete only when all cluster, identity, IAM, S3, DFS, worker, log, SQL, and `ANALYZE TABLE` gates pass on every applicable node. 8. Record the handoff inventory. Use `scripts/pause_cluster.sh` for a recoverable stop and `scripts/cleanup_aws.sh` only after reviewing the exact destructive inventory. This step is complete when the final state of TiUP, EC2, S3, IAM, EBS, and security-group resources is explicit. ## Guardrails - Treat fresh TiUP metadata, data directories, ports, and S3 prefix as one isolation boundary. When reusing EC2, inventory and stop the old cluster, then allocate a separate boundary for the new cluster. - Patch all three TiUP roles before the first start. A vanilla-first start makes keyspace and Resource Manager state unsuitable for TiDB X validation. - Keep S3 credentials on the EC2 metadata path: the instance profile is the runtime credential source for TiKV and its co-located worker. - Treat every account ID, profile, user, key, host, path, resource ID, version, and run label in this skill as an input or rendered placeholder. Never copy a value from a previous run into the reusable skill. - Run the workflow from the designated Linux control/build host. Connect to that host first when operating remotely; do not add a second workstation execution context to the bundled scripts. - Every mutating bundled script defaults to plan mode and requires `--apply`. - Provision and destructive cleanup additionally require the SHA256 printed by their immediately preceding reviewed plan, binding apply to the exact inputs. - Use explicit timeouts for AWS, SSH, and TiUP steps and update the running record after every material result. Load `references/tidbx-aws-troubleshooting.md` only for failure recovery, reuse/resume, pause, or destructive cleanup details.