household-bot/docs/runbooks/iac-terraform.md

Terraform IaC Runbook

Purpose

Provision and maintain GCP infrastructure for bot API, mini app, scheduler, and runtime secrets.

Prerequisites

• Terraform >= 1.8
• GCP project with billing enabled
• Local auth:

gcloud auth application-default login

Bootstrap

cp infra/terraform/terraform.tfvars.example infra/terraform/terraform.tfvars
terraform -chdir=infra/terraform init -backend-config="bucket=<terraform-state-bucket>"
terraform -chdir=infra/terraform plan
terraform -chdir=infra/terraform apply

Quality checks

bun run infra:fmt:check
bun run infra:validate

Add secret values

After first apply, add secret versions:

echo -n "<telegram-bot-token>" | gcloud secrets versions add telegram-bot-token --data-file=- --project <project_id>
echo -n "<telegram-webhook-secret>" | gcloud secrets versions add telegram-webhook-secret --data-file=- --project <project_id>
echo -n "<scheduler-shared-secret>" | gcloud secrets versions add scheduler-shared-secret --data-file=- --project <project_id>

If you set optional secret IDs such as database_url_secret_id or openai_api_key_secret_id, add versions for those secrets too.

Keep bot runtime config that is not secret in your *.tfvars file:

• bot_household_id
• bot_household_chat_id
• bot_purchase_topic_id
• optional bot_parser_model

Environment strategy

• Keep separate states for dev and prod.
• Prefer separate GCP projects for stronger isolation.
• Keep environment-specific variables in dedicated *.tfvars files.

Destructive operations

Review plan output before apply/destroy:

terraform -chdir=infra/terraform plan -destroy
terraform -chdir=infra/terraform destroy