# terraform/aws/account/shoot

Standalone Terraform root module for a **Gardener shoot (data-plane) AWS account**. Applied once per shoot account. Consumes outputs from the sibling `../seed/` module and the `base` and `clinic` stacks via remote state.

## Commands

```sh
# State key is NOT hardcoded — must be passed at init time
terraform init -backend-config="key=aws/account/shoot/<env>.json"
terraform plan  -var-file=test.tfvars
terraform apply -var-file=test.tfvars
```

`test.tfvars` targets `env=prod`, `account=296171618728`, `plan=premium` and is safe for local planning.

## Backend

- Bucket: `autonomous-deployment-terraform-state`, region `us-west-2`, native S3 locking (`use_lockfile = true`).
- State key **not hardcoded** — always supply `-backend-config="key=aws/account/shoot/<env>.json"` at `terraform init`.

## Required variables

| Variable  | Type   | Example           | Purpose                                                    |
|-----------|--------|-------------------|------------------------------------------------------------|
| `env`     | string | `"prod"`          | Environment; drives which remote state keys are fetched    |
| `account` | string | `"296171618728"`  | AWS account ID of the shoot account; used as CLI profile name |
| `plan`    | string | `"premium"`       | Controls whether premium-only resources are created        |

## Provider wiring

| Provider alias    | Profile                            | Region      | Purpose                                          |
|-------------------|------------------------------------|-------------|--------------------------------------------------|
| _(default)_       | `local.clinic_outputs.account.value` | `us-west-2` | Primary operations in the shoot account          |
| `aws.tf_state`    | `default`                          | `us-west-2` | Reads state objects from the S3 state bucket     |
| `aws.pca_owner`   | `local.base_outputs.account.value` | `us-west-2` | Owns the ACM Private CA being shared             |
| `aws.pca_accepter`| `var.account`                      | `us-west-2` | Accepts the PCA RAM share in the shoot account   |
| `awscc`           | `var.account`                      | `us-west-2` | Manages the CloudFormation stack (awscc provider)|

Four AWS profiles must be configured locally: `default`, the base account ID, the clinic account ID, and the shoot account ID.

## Remote state dependencies

Reads three state objects from the bucket at init time:

| Key                                       | Local name       | Purpose                              |
|-------------------------------------------|------------------|--------------------------------------|
| `aws/base/<env>.json`                     | `base_outputs`   | Base account ID, PCA ARN             |
| `aws/account/seed/<env>.json`             | `seed_outputs`   | Base/seed account IDs                |
| `aws/clinic/<env>.json` (or `staging.json` when `env=dev`) | `clinic_outputs` | Clinic account ID, endpoint service ID |

Note: when `env=dev`, the clinic state key resolves to `aws/clinic/staging.json` instead of `aws/clinic/dev.json`.

## What this module provisions

All resources are gated on `var.plan == "premium"` (count = 0 for non-premium accounts):

- **`aws_vpc_endpoint_service_allowed_principal`** — allows the shoot account principal to connect to the clinic's VPC endpoint service. Always created (not plan-gated).
- **`awscc_cloudformation_stack`** (premium only) — deploys `cloudformation/tidbcloud-premium-setup-dataplane.yaml`, which creates IAM roles (`tidbcloud-eks-service-role`, `tidbcloud-dataplane-manager-assumed-role`) in the shoot account.
- **`module.pca`** (premium only) — shares the ACM Private CA from the base account to the shoot account via `../../aws_modules/pca-share`.

## CloudFormation stack name freeze

`terraform_data.backward_compatible` freezes the CloudFormation stack name. For accounts that already have a stack named something other than `tidbcloud-premium-setup-dataplane`, follow the migration procedure documented at `main.tf:87–110` before applying.

## Related Documentation

- [../seed/AGENTS.md](../seed/AGENTS.md) — upstream state producer consumed by this module
- [cloudformation/tidbcloud-premium-setup-dataplane.yaml](cloudformation/tidbcloud-premium-setup-dataplane.yaml) — IAM roles deployed into the shoot account