mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 04:33:13 +00:00
b651a74c7e
Some checks are pending
ci / ci / ci (push) Waiting to run
Those reviews are no longer merge gates. A new deploy workflow still needs its job_workflow_ref on the deploy role.
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# Terraform Project Layout
|
|
|
|
Default layout for new deployable repos. HCP Terraform applies this tree. GitHub Actions publishes application content. See [hcp-terraform.md](hcp-terraform.md) and [cicd.md](cicd.md).
|
|
|
|
## Standard Directory Structure
|
|
|
|
```
|
|
project-name/
|
|
├── terraform/
|
|
│ ├── bootstrap/ # Committed stubs Terraform can create
|
|
│ │ └── handler-stub.zip
|
|
│ ├── iam_github_deploy.tf # githubdeploy-<repo> only
|
|
│ ├── lambda.tf
|
|
│ ├── s3.tf
|
|
│ ├── ssm.tf # /<repo>/deploy/* contract
|
|
│ ├── variables.tf
|
|
│ ├── outputs.tf
|
|
│ └── versions.tf
|
|
├── src/ # Application code (GHA owns the zip)
|
|
├── scripts/ # Live-state verify scripts
|
|
├── .github/
|
|
│ └── workflows/
|
|
│ ├── ci.yaml
|
|
│ └── deploy-<name>.yaml # One workflow per deployable
|
|
└── README.md
|
|
```
|
|
|
|
Working directory in both HCP workspaces is `terraform`. Do not flatten per-env roots (`terraform/live/dev`) unless a remaining stack already has them. New repos use one tree; workspaces select the account via variables.
|
|
|
|
## File Purposes
|
|
|
|
### `terraform/bootstrap/`
|
|
|
|
A tiny committed zip (or equivalent) so Terraform can create the Lambda. GitHub Actions overwrites the live code on the first deploy. Check the stub in. Do not generate it at plan time with `data.external` or `archive_file` from application source.
|
|
|
|
### `lambda.tf` (or equivalent)
|
|
|
|
Create the skeleton. Point it at the stub. Set `lifecycle.ignore_changes` on `filename`, `s3_bucket`, `s3_key`, `s3_object_version`, and `source_code_hash`. Do not set `GIT_SHA` or a release label as a Terraform env var.
|
|
|
|
### `ssm.tf`
|
|
|
|
Write `/<repo>/deploy/*` (see [hcp-terraform.md](hcp-terraform.md#deploy-contract-ssm)). Workflows read these. YAML does not hardcode resource names.
|
|
|
|
### `iam_github_deploy.tf`
|
|
|
|
The `githubdeploy-<repo>` role only. Trust and permissions are in [cicd.md](cicd.md#github-deploy-role). Adding a deploy workflow means adding its `job_workflow_ref` here.
|
|
|
|
Do **not** add `hcp_iam.tf`. `hcptf-<repo>` and `hcptf-<repo>-plan` live in `seahaven-org-baseline`.
|
|
|
|
### Application trees (`src/`, `bff/`, `web/`, `functions/`)
|
|
|
|
Owned by GitHub Actions. HCP trigger prefixes do not include these paths.
|
|
|
|
## CI for Terraform
|
|
|
|
Repo CI runs `terraform fmt -check -recursive`, `terraform init -backend=false`, and `terraform validate`. Plans stay in HCP speculative runs. Do not have GitHub Actions call the HCP API to create or apply a run.
|
|
|
|
## Remaining path
|
|
|
|
Stacks that still package Lambda code inside Terraform (mgmt migrations that have not been cut over) keep their source paths in HCP file triggers until they adopt this layout. New repos start here.
|