# tidb-onebox

TiDB OneBox dev/test environment built on Terraform + EKS + TiDB Operator v2.

All resources (VPC, EKS, K8s add-ons, tidb-operator, TiDB cluster CRDs) are deployed via Terraform.
The single entry point is `tidb-onebox.py`, which wraps `terraform apply`, pause/resume, destroy remediations, diagnostics, and all other operations.

## Quick Start

```bash
# 1. Initialise + generate plan (first run copies dev.tfvars from the example)
uv run tidb-onebox.py bootstrap

# 2. Deploy
uv run tidb-onebox.py deploy

# 3. Health check + SQL pushdown verification
uv run tidb-onebox.py validate
uv run tidb-onebox.py verify-sql

# 4. Optional: scale the workload and/or pause / resume the environment
uv run tidb-onebox.py scale --tikv 2 --tiflash-compute 2 --desired-size 3
uv run tidb-onebox.py stop
uv run tidb-onebox.py start

# 5. Destroy (with automatic remediation for S3 / ELB / Helm timeout / finalizers / SSO, etc.)
uv run tidb-onebox.py destroy --auto-approve
```

Notes:

- `stop` / `start` operate at the EKS managed node group level. They are designed as a practical pause/resume mechanism for one-box dev/test environments.
- `scale` applies temporary Terraform replica overrides for TiDB-X components and can optionally resize the EKS node group in the same operation. It does not rewrite `dev.tfvars`.
- one-box automatically sets PD replication `max-replicas` to the effective TiKV replica count so small dev/test clusters can safely scale TiKV in and out.
- `scale` now fails early if the workload status is unchanged for too long; override with `--wait-timeout-seconds` and `--stall-timeout-seconds` when needed.
- Long-running Terraform `plan` / `apply` output is streamed to stdout and also tee'd to a log file under `/tmp`; the script prints the log path before each step so full output is still available if your terminal/UI truncates it.

See [SKILL.md](SKILL.md) and [AGENTS.md](AGENTS.md) for detailed commands, field reference, and troubleshooting.