github-ci-bootstrap: create a bucket for Terraform binary plan files (#36)

## Summary

Khan/actions#274 changes `generate-terraform-plan`/`apply-terraform-plan` to store the Terraform binary plan in GCS instead of committing it to git (a binary plan embeds a full copy of the Terraform state, including sensitive values in cleartext). Every consumer of those actions needs the same bucket with the same security posture, so this PR has the bootstrap module create it, next to the CI service accounts and WIF providers it belongs with, instead of each repo hand-rolling it.

## What the module now creates (opt-out via `create_terraform_plans_bucket = false`)

- Bucket `terraform-plans-{org}-{repo}-{service}` (same normalization as the state bucket; overridable via `terraform_plans_bucket`) in `khan-internal-services`, with uniform bucket-level access and public access prevention enforced.
- Always per-service, never shared: plan files contain that service's state, so a shared bucket would let each service's CI read the others' state.
- `roles/storage.objectAdmin` on the bucket for the read/write service account only (it uploads on plan, downloads and deletes on apply). The read-only account used for PR-branch plans gets no grant.
- Lifecycle rule deleting objects after `terraform_plans_expiration_days` (default 30); applied plans are already deleted by the apply action, this catches superseded plan PRs.
- New output `terraform_plans_bucket` to feed the actions' `plan_bucket` input.

## Rollout

Additive and enabled by default: consumers get the bucket on their next module bump plus a local bootstrap `terraform apply`. For culture-cron, which already created `khan-culture-cron-terraform-plans` by hand in its bootstrap (Khan/culture-cron#28) during testing, adoption means passing `terraform_plans_bucket = "khan-culture-cron-terraform-plans"` and moving the two resources into the module in its bootstrap state:

    terraform state mv google_storage_bucket.terraform_plans 'module.github_ci_bootstrap.google_storage_bucket.terraform_plans[0]'
    terraform state mv google_storage_bucket_iam_member.ci_rw_terraform_plans_object_admin 'module.github_ci_bootstrap.google_storage_bucket_iam_member.ci_plans_bucket_access_rw[0]'

Related: #35 (make `write_branch_patterns` explicit); if both land together, tag a single `github-ci-bootstrap-v2.0.0`.

Author: jwbron

Reviewers: csilvers

Required Reviewers:

Approved By: csilvers

Checks: ✅ 1 check was successful

Pull Request URL: #36

Author: jwbron

terraform/modules/github-ci-bootstrap/README.md

@@ -74,6 +74,10 @@ module "culture_cron_terraform_ci" {
 | `target_projects`        | Map of GCP projects where this Terraform configuration will deploy resources. Keys are project IDs.                           | `map(object)`  | `{}`                               |    no    |
 | `write_branch_patterns`  | List of branch patterns that are allowed to use the read/write service account (defaults to main and master)                  | `list(string)` | `["main", "master"]`               |    no    |
 | `terraform_state_bucket` | GCS bucket name for storing Terraform state for this configuration                                                            | `string`       | `terraform-{org}-{repo}-{service}` |    no    |
+| `create_terraform_plans_bucket` | Whether to create a bucket for binary plan files produced by the generate-terraform-plan GitHub action                 | `bool`         | `true`                             |    no    |
+| `terraform_plans_bucket` | GCS bucket name for storing Terraform binary plan files                                                                       | `string`       | `terraform-plans-{org}-{repo}-{service}` | no |
+| `terraform_plans_bucket_location` | Location for the Terraform plans bucket                                                                              | `string`       | `"us-central1"`                    |    no    |
+| `terraform_plans_expiration_days` | Days after which plan objects are deleted (cleans up plans that are never applied)                                   | `number`       | `30`                               |    no    |
 | `secrets_project_id`     | Project ID where secrets needed by the Terraform configuration are stored                                                     | `string`       | `"khan-academy"`                   |    no    |
 | `secret_ids`             | List of secret IDs that the Terraform configuration needs access to                                                           | `list(string)` | `[]`                               |    no    |
 
@@ -115,6 +119,17 @@ If `terraform_state_bucket` is not specified, the module automatically generates
 
 This ensures each Terraform setup gets its own isolated state bucket while maintaining consistent, predictable naming that complies with GCS bucket naming requirements.
 
+### Terraform Plans Bucket
+
+By default the module also creates a bucket for the binary plan files produced by the `generate-terraform-plan` GitHub action (Khan/actions). A binary plan embeds a full copy of the Terraform state, including sensitive values in cleartext, so plans live in this access-controlled bucket instead of being committed to the repository:
+
+- **Naming**: `terraform-plans-{org}-{repo}-{service}` (same normalization as the state bucket), overridable via `terraform_plans_bucket`
+- **Isolation**: always per-service, never shared, since plan files contain that service's state
+- **Access**: only the read/write service account gets object access (`roles/storage.objectAdmin`); the read-only account gets none
+- **Hygiene**: uniform bucket-level access, public access prevention enforced, and a lifecycle rule deleting objects after `terraform_plans_expiration_days` (plans that are applied get deleted by the apply-terraform-plan action immediately)
+
+Pass the bucket name (the `terraform_plans_bucket` output) as the `plan_bucket` input to the `generate-terraform-plan` and `apply-terraform-plan` actions. Set `create_terraform_plans_bucket = false` if this Terraform setup does not use those actions.
+
 ### Dual Service Account Configuration
 
 The module always creates two service accounts with different permission levels:
@@ -220,6 +235,7 @@ Each `service_name` gets its own isolated:
 | `workload_identity_provider_rw` | Full resource name of the Workload Identity provider (write-enabled branches)             |
 | `workload_identity_provider_ro` | Full resource name of the Workload Identity provider (read-only, available to any branch) |
 | `terraform_state_bucket`        | The GCS bucket name used for Terraform state (computed or provided)                       |
+| `terraform_plans_bucket`        | The GCS bucket holding binary Terraform plan files awaiting apply (null if not created)   |
 | `service_name`                  | The unique identifier for this Terraform configuration and environment                    |
 | `target_projects`               | Map of target projects configured                                                         |
 | `write_branch_patterns`         | List of branch patterns that are allowed to use the read/write service account            |

terraform/modules/github-ci-bootstrap/main.tf

@@ -52,6 +52,13 @@ locals {
   # Use provided bucket name or computed default
   terraform_state_bucket = coalesce(var.terraform_state_bucket, local.default_bucket_name)
 
+  # Compute default plans bucket name, mirroring the state bucket convention.
+  # Unlike the state bucket, this is always per-service: plan files contain
+  # the service's state (including sensitive values), so a bucket shared
+  # between services would let each service's CI read the others' state.
+  default_plans_bucket_name = replace("terraform-plans-${lower(local.github_org)}-${lower(local.github_repo)}-${lower(var.service_name)}", "_", "-")
+  terraform_plans_bucket    = coalesce(var.terraform_plans_bucket, local.default_plans_bucket_name)
+
   # Flatten target_projects into individual service permissions for read-write access
   project_service_permissions_rw = flatten([
     for project_id, config in var.target_projects : [
@@ -194,6 +201,46 @@ resource "google_storage_bucket_iam_member" "ci_state_bucket_legacy_reader_ro" {
   member = "serviceAccount:${google_service_account.github_ci_ro.email}"
 }
 
+# === TERRAFORM PLANS BUCKET ===
+
+# Bucket for the Terraform binary plan files produced by the
+# generate-terraform-plan GitHub action. A binary plan embeds a full copy of
+# the Terraform state, including sensitive values in cleartext, so plans are
+# stored here (access controlled, like the state bucket) instead of being
+# committed to the repository. Objects are keyed by commit SHA and deleted by
+# the apply-terraform-plan action after a successful apply; the lifecycle
+# rule cleans up plans that are never applied (e.g. superseded plan PRs).
+resource "google_storage_bucket" "terraform_plans" {
+  count = var.create_terraform_plans_bucket ? 1 : 0
+
+  name                        = local.terraform_plans_bucket
+  project                     = "khan-internal-services"
+  location                    = var.terraform_plans_bucket_location
+  uniform_bucket_level_access = true
+  public_access_prevention    = "enforced"
+
+  lifecycle_rule {
+    condition {
+      age = var.terraform_plans_expiration_days
+    }
+    action {
+      type = "Delete"
+    }
+  }
+}
+
+# The read/write service account uploads plans (plan runs on the deploy
+# branch) and later downloads and deletes them (apply runs), so it needs full
+# object access. The read-only service account used for PR-branch plans never
+# touches this bucket, so it deliberately gets no grant.
+resource "google_storage_bucket_iam_member" "ci_plans_bucket_access_rw" {
+  count = var.create_terraform_plans_bucket ? 1 : 0
+
+  bucket = google_storage_bucket.terraform_plans[0].name
+  role   = "roles/storage.objectAdmin"
+  member = "serviceAccount:${google_service_account.github_ci_rw.email}"
+}
+
 # === SECRET MANAGER ===
 
 # Dynamic secret admin access based on provided secret IDs (read-write access)

terraform/modules/github-ci-bootstrap/outputs.tf

@@ -50,6 +50,11 @@ output "terraform_state_bucket" {
   value       = local.terraform_state_bucket
 }
 
+output "terraform_plans_bucket" {
+  description = "The GCS bucket holding binary Terraform plan files awaiting apply (null when create_terraform_plans_bucket is false)"
+  value       = var.create_terraform_plans_bucket ? google_storage_bucket.terraform_plans[0].name : null
+}
+
 output "service_name" {
   description = "The unique identifier for this Terraform configuration and environment managed in CI"
   value       = var.service_name

terraform/modules/github-ci-bootstrap/variables.tf

@@ -58,6 +58,30 @@ variable "terraform_state_bucket" {
   default     = null
 }
 
+variable "create_terraform_plans_bucket" {
+  description = "Whether to create a GCS bucket for the Terraform binary plan files produced by the generate-terraform-plan GitHub action. A binary plan embeds a full copy of the Terraform state, including sensitive values, so plans are stored in this access-controlled bucket instead of being committed to the repository."
+  type        = bool
+  default     = true
+}
+
+variable "terraform_plans_bucket" {
+  description = "GCS bucket name for storing Terraform binary plan files (defaults to terraform-plans-{org}-{repo}-{service})"
+  type        = string
+  default     = null
+}
+
+variable "terraform_plans_bucket_location" {
+  description = "Location for the Terraform plans bucket"
+  type        = string
+  default     = "us-central1"
+}
+
+variable "terraform_plans_expiration_days" {
+  description = "Days after which objects in the Terraform plans bucket are deleted. This cleans up plans that are never applied (e.g. superseded plan PRs); applied plans are deleted by the apply-terraform-plan action itself."
+  type        = number
+  default     = 30
+}
+
 variable "secrets_project_id" {
   description = "The Google Cloud project ID where secrets are stored (defaults to khan-academy)"
   type        = string