Google Cloud

OrkStage creates Google Cloud resources with the OpenTofu modules in orkstage-modules/modules/gcp, one isolated state per resource, kept in a GCS bucket you own. Health, logs, secrets and redeploys go through the Google Cloud REST APIs.

What OrkStage createsCopy Anchor Link

Cloud Run services mount database and cache credentials from Secret Manager as <ID>_CREDENTIALS, and get read and write access to the buckets they depend on.

The PostgreSQL app password lives in OpenTofu state and in a Secret Manager secret (secret_ref). The Redis AUTH string is stored in Secret Manager too. readSecret returns username, password, host, port, database and url for PostgreSQL, and password, host, port and url for Redis, so a resource on another provider can connect.

Target configurationCopy Anchor Link

Credential secretCopy Anchor Link

The secret behind credentialRef is the service account key JSON file exactly as Google issues it. The adapter needs client_email and private_key, and also reads private_key_id and project_id when present.

{
  "type": "service_account",
  "project_id": "acme-prod-123",
  "private_key_id": "<key id>",
  "private_key": "<PEM private key>",
  "client_email": "orkstage-deployer@acme-prod-123.iam.gserviceaccount.com"
}

The key signs a short JWT that is exchanged for an OAuth access token, cached in memory. It reaches OpenTofu only as the GOOGLE_CREDENTIALS environment variable of one runner command. Workload identity federation, with no long lived key, is planned.

gcloud iam service-accounts create orkstage-deployer --project acme-prod-123 --display-name "OrkStage deployer"
gcloud iam service-accounts keys create key.json --iam-account orkstage-deployer@acme-prod-123.iam.gserviceaccount.com
# Store the content of key.json in the secret store, then delete the local file.

Prepare state storageCopy Anchor Link

Create the bucket once, in the region you deploy to most:

gcloud storage buckets create gs://acme-orkstage-state --project acme-prod-123 --location us-central1 \
  --uniform-bucket-level-access --public-access-prevention
gcloud storage buckets update gs://acme-orkstage-state --versioning

The state of a resource is the object orkstage/<name>.tfstate/default.tfstate. The configuration applied is kept beside it as orkstage/<name>.tfstate.config.json, so destroy never depends on a newer template.

APIs and permissionsCopy Anchor Link

Enable the APIs the modules use. Validation reports any that are off.

gcloud services enable compute.googleapis.com servicenetworking.googleapis.com run.googleapis.com \
  iam.googleapis.com secretmanager.googleapis.com sqladmin.googleapis.com redis.googleapis.com \
  storage.googleapis.com logging.googleapis.com --project acme-prod-123

Grant these roles to the deployer service account on the project:

RegionsCopy Anchor Link

Regions are Google Cloud regions such as us-central1, southamerica-east1 or europe-west1. Subnets span every zone of a region, so availabilityZones does not change the network layout.

Actions for triggersCopy Anchor Link

Known limitsCopy Anchor Link

• Cloud Run CPU is rounded up to 1, 2, 4, 6 or 8 vCPU, and memory is raised to the minimum for that CPU. Fractional CPU would force one request per instance.
• Cloud Run scales on request concurrency. targetCpuPercent is not used.
• There is no shared HTTPS load balancer with path routing yet. Each service keeps its own run.app URL.
• Same zone HA is not offered for Cloud SQL; regional availability is the HA option.
• A PostgreSQL instance without a network gets a public IP with no authorized networks, reachable only through Cloud SQL connectors.
• Memorystore needs a network in the same slot and runs without in transit encryption; traffic stays inside the VPC. Two or more replicas need at least 5 GB, so small sizes are raised.
• The private services peering is abandoned on destroy and removed with the network.
• Credentials of dependencies outside Google Cloud are not mounted into Cloud Run.