docs: add full IaC migration guide to terraform/main.tf

Covers step-by-step migration order, resource-by-resource import vs create
breakdown, risks (Cloud SQL replacement detection, secret version timing,
VPC CIDR conflicts, IAM propagation lag, local state loss), and what stays
intact vs what changes for the running application.

https://claude.ai/code/session_01SRRzCWrpwgMpdYFurMVn7m

Author: claude

terraform/main.tf

@@ -1,3 +1,159 @@
+# =============================================================================
+# MIGRATION GUIDE: Moving from Manual / CI-managed Infrastructure to Full IaC
+# =============================================================================
+#
+# CURRENT STATE
+# -------------
+# The following resources exist in GCP but are managed manually or by the CI
+# pipeline (not by Terraform):
+#   - Cloud SQL instance:   querypal-db           (manually created)
+#   - Cloud SQL database:   querypal              (manually created)
+#   - Cloud Run services:   querypal-backend/frontend  (deployed by CI)
+#   - Secrets:              stored in GitHub Secrets   (not in Secret Manager)
+#
+# WHAT TERRAFORM NOW MANAGES
+# ---------------------------
+# This configuration manages the infrastructure layer only. The CI pipeline
+# (.github/workflows/google-cloudrun-docker.yml) continues to own image builds
+# and Cloud Run deployments.
+#
+#   Resource                  | Terraform action   | App impact
+#   --------------------------|--------------------|---------------------------
+#   VPC connector             | CREATE (new)       | None until next CI deploy
+#   Secret Manager secrets    | CREATE (new)       | None until values added
+#   Cloud Run service account | CREATE (new)       | None until next CI deploy
+#   IAM bindings              | CREATE (new)       | None
+#   Cloud SQL instance        | IMPORT (existing)  | Zero — instance untouched
+#   Cloud SQL database        | IMPORT (existing)  | Zero — database untouched
+#
+# =============================================================================
+# MIGRATION STEPS — run once, in this order
+# =============================================================================
+#
+# STEP 1 — Verify Terraform config matches your actual Cloud SQL instance.
+#
+#   Before importing, check that database.tf reflects the real instance:
+#   - tier (e.g. db-f1-micro)
+#   - database_version (POSTGRES_15)
+#   - region (europe-west1)
+#   - backup settings, flags, IP config
+#
+#   To inspect the current instance:
+#     gcloud sql instances describe querypal-db --format=json
+#
+#   If anything in database.tf does not match, fix it BEFORE importing.
+#   After import, any mismatch will show as a planned change. Most settings
+#   (tier, flags, backup) can be modified in-place with no downtime. Changing
+#   database_version would require recreation — avoid it.
+#
+# STEP 2 — Import existing Cloud SQL resources into Terraform state.
+#
+#   This registers the existing instance with Terraform without touching it.
+#   No data is moved, no connections are interrupted, the application keeps
+#   running throughout.
+#
+#     cd terraform
+#     cp terraform.tfvars.example terraform.tfvars
+#     terraform init
+#     ./import.sh
+#
+#   After import, run `terraform plan`. The plan should show no changes (or
+#   only safe in-place updates to settings you deliberately changed in the
+#   config). If you see a resource scheduled for REPLACEMENT, stop and fix the
+#   config — do not apply until the plan is clean.
+#
+# STEP 3 — Apply Terraform to create new resources.
+#
+#     terraform apply
+#
+#   This creates: VPC connector, Secret Manager secrets (empty), Cloud Run SA,
+#   and all IAM bindings. Nothing here touches the running application.
+#
+#   The VPC connector takes 2–5 minutes to provision. The apply will wait.
+#
+# STEP 4 — Populate Secret Manager with the actual secret values.
+#
+#   The secrets created in Step 3 are empty shells. Cloud Run will refuse to
+#   start if it tries to mount a secret with no versions. Populate them NOW,
+#   before triggering a new CI deployment:
+#
+#     for SECRET_ID in \
+#       querypal-azure-tenant-id \
+#       querypal-azure-client-id \
+#       querypal-azure-client-secret \
+#       querypal-gemini-api-key \
+#       querypal-db-user \
+#       querypal-db-pass; do
+#       echo -n "Enter value for ${SECRET_ID}: "
+#       read -rs VALUE
+#       echo
+#       echo -n "${VALUE}" | gcloud secrets versions add "${SECRET_ID}" --data-file=-
+#     done
+#
+#   Verify each secret has at least one version:
+#     gcloud secrets versions list querypal-gemini-api-key
+#
+# STEP 5 — Trigger a CI deployment (push to production branch).
+#
+#   The updated workflow now uses:
+#     --set-secrets        (reads from Secret Manager instead of env vars)
+#     --vpc-connector      (attaches both services to the VPC)
+#     --ingress=internal   (backend becomes unreachable from public internet)
+#     --service-account    (uses the new dedicated Cloud Run SA)
+#
+#   The frontend will be publicly reachable as before. The backend will only
+#   accept traffic that arrives through the VPC connector (from the frontend
+#   nginx proxy). Direct requests to the backend Cloud Run URL from the internet
+#   will receive a 403 from Google's frontend.
+#
+#   Monitor the deployment:
+#     gcloud run services describe querypal-backend --region=europe-west1
+#     gcloud run services describe querypal-frontend --region=europe-west1
+#
+# STEP 6 — Clean up GitHub Secrets (optional but recommended).
+#
+#   Once the application is verified working with Secret Manager, delete the
+#   now-unused GitHub Secrets from the repository settings:
+#     AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET,
+#     GEMINI_API_KEY, DB_USER, DB_PASS
+#
+# =============================================================================
+# RISKS AND THINGS TO WATCH FOR
+# =============================================================================
+#
+# Cloud SQL import divergence
+#   If `terraform plan` after import shows resource replacement (destroy +
+#   create) for the Cloud SQL instance, do NOT apply. Terraform cannot recreate
+#   a Cloud SQL instance in-place — it would destroy the instance and all data.
+#   deletion_protection = true in database.tf will block the destroy, but it is
+#   safer to fix the config discrepancy first.
+#
+# Secret versions must exist before deployment
+#   If Step 5 runs before Step 4 completes, Cloud Run will fail to start
+#   because the secret mount has no versions. The previous revision stays live
+#   (Cloud Run only switches traffic after the new revision is healthy), so the
+#   application continues to work — but the deploy will time out. Fix: add the
+#   missing secret version, then re-deploy.
+#
+# VPC connector CIDR must not overlap existing subnets
+#   The connector reserves 10.8.0.0/28. If your VPC already has a subnet in
+#   that range, change vpc_connector_cidr in variables.tf before applying.
+#   Check existing ranges:
+#     gcloud compute networks subnets list --filter="region:europe-west1"
+#
+# Cloud Run SA permissions propagate with eventual consistency
+#   IAM bindings may take up to 60 seconds to take effect after `terraform
+#   apply`. If the first CI deploy fails with a permission error immediately
+#   after applying Terraform, wait a minute and retry.
+#
+# Terraform state is local by default
+#   The state file (terraform.tfstate) is gitignored. If you lose it, you lose
+#   the link between Terraform and the real GCP resources, and Terraform will
+#   try to recreate everything. Enable the GCS backend (commented out below)
+#   before running in a team or CI environment.
+#
+# =============================================================================
+
 terraform {
   required_version = ">= 1.5"