# PRD: Layer 00 - Bootstrap

**Scope:** Deployment account. Remote state bucket, KMS keys, Parameter Store baseline contract, and IAM for Terraform execution.

**Dependencies:** PRD_00-cross-cutting (constraints, Parameter Store contract, backend rules).

## 1. Purpose and Execution Order

| ID | Requirement |
| ---- | ------------- |
| R-B00-001 | This layer SHALL be the first layer applied in any environment; all other layers depend on its outputs. |
| R-B00-002 | This layer SHALL provision the remote state bucket, KMS keys, and the bootstrap Parameter Store contract. |
| R-B00-003 | Outputs SHALL be published only to Parameter Store (no Terraform outputs consumed by other layers via remote state). |

## 2. KMS Keys

| ID | Requirement |
| ---- | ------------- |
| R-B00-101 | A KMS key SHALL be created for the Terraform state bucket (SSE-KMS for state and lockfile objects). |
| R-B00-102 | A KMS key SHALL be created for AWS Secrets Manager (for encryption of all secrets used by workloads and automation). |
| R-B00-103 | KMS keys SHALL have key policies that restrict usage to authorized principals (e.g. Terraform execution role, Secrets Manager, S3). |

## 3. S3 State Bucket

| ID | Requirement |
| ---- | ------------- |
| R-B00-201 | An S3 bucket SHALL be created for storing Terraform state. |
| R-B00-202 | The state bucket SHALL have versioning enabled. |
| R-B00-203 | The state bucket SHALL use SSE-KMS as default encryption, using the state bucket KMS key. |
| R-B00-204 | The state bucket SHALL have a bucket public access block applied (block all public access). |
| R-B00-205 | Terraform workspaces SHALL be used; workspace name = `<region>-<env>`; state key = `env:/<workspace>/<layer>/terraform.tfstate`. The bucket SHALL allow multiple keys for all layers and environments. |

## 4. Parameter Store Bootstrap Contract

| ID | Requirement |
| ---- | ------------- |
| R-B00-301 | The layer SHALL write all bootstrap contract keys under the prefix `wikijs/<region>/<env>/00-bootstrap/`. |
| R-B00-302 | The following keys SHALL be written (minimum): `tfstate_bucket`, `tfstate_kms_key_arn`, `domain_name`, `wikijs_fqdn`, `hosted_zone_id`, `acm_cert_arn`. |
| R-B00-303 | `tfstate_bucket` SHALL contain the name of the S3 state bucket. |
| R-B00-304 | `tfstate_kms_key_arn` SHALL contain the ARN of the KMS key used for the state bucket. |
| R-B00-305 | `domain_name` SHALL contain the base domain name (non-secret). |
| R-B00-306 | `wikijs_fqdn` SHALL contain the fully qualified domain name for Wiki.js (e.g. `wiki.<domain>`). |
| R-B00-307 | `hosted_zone_id` SHALL contain the Route 53 hosted zone ID (domain account) where DNS will be managed. |
| R-B00-308 | `acm_cert_arn` SHALL contain the ACM certificate ARN (deployment account) used for TLS on the Wiki.js endpoint. |
| R-B00-309 | All values SHALL be stored as non-secret (String type); no secret material SHALL be written to Parameter Store. |

## 5. IAM (Terraform Execution)

| ID | Requirement |
| ---- | ------------- |
| R-B00-401 | IAM permissions for Terraform execution SHALL allow minimal S3 access to the state bucket: read/write/delete for state objects and lockfile objects under the same prefix. |
| R-B00-402 | IAM permissions SHALL allow KMS Encrypt/Decrypt/GenerateDataKey (as needed) for the state bucket KMS key. |
| R-B00-403 | IAM permissions SHALL allow SSM Parameter Store GetParameter and PutParameter under `wikijs/<region>/<env>/00-bootstrap/*` for the layer's own prefix. |
| R-B00-404 | IAM SHALL follow least privilege; no broader SSM or S3 access than required for this layer. |

## 6. Destroy Behavior

| ID | Requirement |
| ---- | ------------- |
| R-B00-501 | On `terraform destroy`, the layer SHALL remove only resources it owns, including the bootstrap Parameter Store prefix `wikijs/<region>/<env>/00-bootstrap/*`. |
| R-B00-502 | Destroy SHALL be executed last in the teardown sequence (after all other layers have been destroyed). |
| R-B00-503 | A provision workflow and a destroy workflow SHALL exist for this layer, conforming to the cross-cutting CI/CD requirements. |

## 7. Backend Configuration

| ID | Requirement |
| ---- | ------------- |
| R-B00-601 | This layer MAY use a local backend or a fixed backend configuration for initial bootstrap (e.g. state stored in the bucket with a known key). |
| R-B00-602 | Non-bootstrap layers SHALL read backend configuration (bucket name, KMS key ARN) from Parameter Store; bootstrap SHALL NOT depend on Parameter Store for its own backend. |

## 8. Implementation Notes

- **Terraform:** Root module at `terraform/00-bootstrap/`. Bootstrap MAY use a local backend or fixed backend configuration for initial bootstrap; state key pattern for non-bootstrap layers is `env:/<workspace>/<layer>/terraform.tfstate`.
- **Workflows:** `tf-00-bootstrap-provision.yaml` and `tf-00-bootstrap-destroy.yaml` (extension `.yaml`), calling `_terraform-layer.yaml`. Destroy SHALL run last in teardown order.
- **Parameter Store (writes):** Under `wikijs/<region>/<env>/00-bootstrap/`: `tfstate_bucket`, `tfstate_kms_key_arn`, `domain_name`, `wikijs_fqdn`, `hosted_zone_id`, `acm_cert_arn`. All type `String`; no secret material.
- **Reads:** Bootstrap SHALL NOT depend on Parameter Store for its own backend; no reads from other layers.