# terraform/alicloud/premium

Root Terraform module that provisions a TiDB Cloud **Premium** (`DEPLOY_TYPE_NEXTGEN`) seed cluster on Alibaba Cloud (ACK) and bootstraps all required in-cluster services.

## What this module owns

- ACK (Alibaba Cloud Kubernetes) cluster: `{env}-seed-{logical_region_name}`
- RAM roles in both the controlplane (seed) account and each dataplane account
- Shared bandwidth packages per dataplane account
- All in-cluster services via Argo Workflows: cert-manager, ESO, kube-prometheus, victoria-metrics, Crossplane (upbound + AWS + alibabacloud providers), Kong gateway, dataplane-manager, jumpserver, agent-control-server, o11y-agent, cluster-ng-service, config-center-regional, RDS, TiCDC service
- DNS CNAME `{logical_region_name}.regional-api.{env}.aliyun.tidbcloud.com` → Kong proxy LB
- Region registration in global registry as service plan `Premium`

## Required variables

| Variable | Notes |
|---|---|
| `cloud_region` | Alibaba Cloud region (e.g. `ap-northeast-1`) |
| `logical_region_name` | Logical name used in cluster name and DNS (e.g. `ali-apne1-ng`) |
| `zone_ids` | List of availability zones for the region |
| `dataplane_accounts` | List of Alibaba Cloud account IDs — **max 3**, hard-coded provider limit in `./ram` and `./shared-bandwidth` sub-modules |
| `env` | `dev` \| `staging` \| `prod` (default: `dev`) |

`test.tfvars` contains a working prod example for `ap-northeast-1`.

## Non-obvious constraints

- **`dataplane_accounts` max 3**: Both `./ram/main.tf` and `./shared-bandwidth/main.tf` statically define three alicloud provider aliases (`dp_0`, `dp_1`, `dp_2`). Adding a 4th account requires new provider blocks in both files.
- **ACR region is always `ap-southeast-1`**: The `alicloud.cr` provider alias is hardcoded to `ap-southeast-1` regardless of `cloud_region`. ACR instance names: `tidbcloud-dev` (dev/staging), `tidbcloud-prod` (prod).
- **Kubeconfig is ephemeral**: Written to `/tmp/{cluster_name}-kubeconfig` during apply by the `kubeconfig` module. Consumed by `kubernetes`, `kubectl`, and all `app` modules in the same run.
- **`env=dev` behaves differently**: No `public_access_cidrs` restriction on the ACK cluster; Kong public access is enabled (`enableKongPublicAccess = true`).
- **App deployments use Argo Workflows**: Every in-cluster service (cert-manager, kong, dataplane-manager, etc.) is deployed via `../../modules/app`, which submits a named workflow YAML to Argo and waits for specified k8s resources to reach ready state.

## Pre-existing resources (must exist before apply)

These RAM roles must already exist in the seed account; Terraform will fail with a postcondition error if they are missing:

- `jump-service-role` — checked by `jumpserver.tf`
- `dbaas-dev` — checked by `dbaas-dev.tf`
- `acrpullrole` — referenced directly in `dataplane-manager.tf`

## State and account resolution

- **Backend**: S3 bucket `autonomous-deployment-terraform-state`, region `us-west-2`, using native S3 lock (`use_lockfile = true`). State key must be set at `terraform init -backend-config=key=...`.
- **Remote state reads** (via `aws.tf_state` provider using `default` profile):
  - `alicloud/account/seed/{env}.json` → resolves `seed_account` and `base_account`
  - `gke/argocd/{env}.json`, `gke/runner/prod.json`
  - `aws/base/{env}.json`, `aws/clinic/{env}.json`, `aws/devops/{env}.json`
- `seed_account` drives the alicloud provider profile; `base_account` drives the main AWS provider profile.

## Typical workflow

```sh
terraform init -backend-config="key=alicloud/premium/<env>/<logical_region_name>.json"
terraform plan -var-file=<vars>.tfvars
terraform apply -var-file=<vars>.tfvars
```

## Related Documentation

- [ram sub-module](ram/main.tf)
- [shared-bandwidth sub-module](shared-bandwidth/main.tf)