docs/RUNBOOK.md

# CloudOps runbook

Next steps if someone deploys the fictional Thistle Analytics `insights-api` for real. This repository does not run those commands. `make check` does not submit a build, exchange a token, or create a resource.

Configs here are real and offline-validated. They are not deployed to any cloud account. Project id `thistle-analytics-demo` and project number `000000000000` are placeholders. The AWS account id `000000000000` is a placeholder. Thistle Analytics is fictional.

## Before a real GCP deploy

- A GCP project you are allowed to change, plus billing enabled on that project.
- Workload Identity Federation for the GitHub repository that will ship the code. The pool in `gcp/wif/github-pool.yaml` uses a placeholder project number and the repository `example.invalid/thistle-analytics/insights-api`.
- A dedicated runtime service account. Do not use the default compute service account.
- Secret Manager secret `insights-api-signing-key` created out of band. Pin a version. Do not commit the value.
- Replace the placeholder CMEK name before `terraform apply`. This module does not create key material.

The Cloud Build file and the GitHub workflow are the two ways in. The workflow uses `google-github-actions/auth` with a full commit SHA and `id-token: write`. It does not read a JSON key.

Suggested order, on a machine that is allowed to change the project:

```bash
terraform -chdir=gcp/terraform init
terraform -chdir=gcp/terraform plan
terraform -chdir=gcp/terraform apply
```

Or submit `gcp/build/cloudbuild.yaml` with substitutions `_PROJECT_ID`, `_REGION`, and `_SERVICE`. The portfolio does not do either.

Roll back a Cloud Run revision by sending traffic to the previous revision in the console or with `gcloud run services update-traffic`. That command is not part of `make check`.

## Before a real AWS deploy (secondary)

This path is secondary. GCP is the primary narrative.

The SAM template is `aws/template.yaml`. The GitHub fragment assumes role `insights-api-deploy` with OIDC. The execution role can write one log group and read one Secrets Manager ARN. The deploy role can update function `insights-api-secondary` only.

There is no VPC, no load balancer, and no NAT gateway in this path. Do not copy a network module from another demo into this folder.

## What can show up on the bill

Names only. This page does not estimate a price.

GCP, if you apply the primary path:

- Cloud Run
- Artifact Registry
- Secret Manager
- Cloud Monitoring
- Cloud Logging
- Cloud Build
- Workload Identity Federation

AWS, if you apply the secondary path:

- Lambda
- API Gateway
- CodeBuild
- CloudWatch
- IAM
- Secrets Manager

IAM itself is not a separate priced line in the usual case. It is listed because the secondary path creates roles. Workload Identity Federation is listed because the primary path depends on it. No amount belongs in this file.