rad-modules: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

rad-modules is a catalog of standalone OpenTofu/Terraform modules that deploy educational Google Cloud and multi-cloud Kubernetes reference architectures ("RAD Lab"). Modules are deployed via the interactive rad-launcher CLI or via Cloud Build pipelines driven by the RAD platform UI.

Common Commands

All Terraform commands run from within a module directory (e.g. cd modules/Istio_GKE):

# Validate and format-check a module
tofu init -backend=false
tofu validate
tofu fmt -check

# Run module-level tests (uses mock providers, no GCP credentials needed)
tofu test

# Plan/apply with a real project
tofu plan  -var="project_id=my-gcp-project"
tofu apply -var="project_id=my-gcp-project"
tofu destroy -var="project_id=my-gcp-project"

Lint all modules from the repo root:

# Format check (CI uses terraform, but tofu also works)
terraform fmt -check -recursive modules/

# tflint (run from within a module directory)
tflint --init --config ../../.tflint.hcl
tflint --config ../../.tflint.hcl --format compact

Run the interactive launcher:

cd rad-launcher
python3 installer_prereq.py   # install prerequisites once
python3 radlab.py             # interactive module deploy/destroy

Non-interactive launcher:

python3 rad-launcher/radlab.py \
  -m Istio_GKE -a create \
  -p my-mgmt-project -b my-mgmt-project-radlab-tfstate \
  -f /path/to/my.tfvars

Before running tofu plan/apply directly against a module directory (bypassing the launcher), check for leftovers from a prior manual run:

• ls *.auto.tfvars — OpenTofu loads these automatically with no -var-file flag. A stale one from an earlier lab pins project_id (or other vars) to a project you may no longer have access to, and the failure mode is a confusing 403 deep in plan, not an obviously-wrong-input error. Bank_GKE has shipped one before; there is no repo convention preventing another.
• ls *.tfstate* — local state from a previous run against a different project makes plan try to reconcile resources that don't exist in the target project. The launcher and rad-ui always use a GCS backend and never hit this; a bare tofu init/apply in a module directory does.