Skip to content

Google Cloud target reference

What cloudseed setup gcp builds, every variable you can set with --var, and every output. In the terminal: cloudseed help gcp or cloudseed explain target gcp.

Generated from the code

This page is generated by scripts/gen-docs.py from terraform/gcp/variables.tf, terraform/gcp/outputs.tf, the setup questions and skills/cloudseed-gcp/SKILL.md, so it always matches the CLI you install (this build: cloudseed 0.2.3).

What it builds

cloudseed setup gcp --env <env> --project-id <project> builds, in one region/zone:

  • APIs enabled: cloudresourcemanager, compute, iam, logging, monitoring, oslogin; with GKE also container, iamcredentials, secretmanager and dns (never disabled on destroy; enable_apis=false skips them).
  • Custom-mode VPC with two subnets carved from network_cidr: public and private (Private Google Access on, VPC flow logs on both).
  • Cloud Router + Cloud NAT for the private subnet only (error logging on).
  • Firewall: SSH to bastion tag from allowed_ssh_cidrs (logged); SSH from bastion tag to private tag; internal traffic inside the private subnet; an explicit, logged deny-all ingress at priority 65000.
  • Bastion: e2-micro Debian 12 (Ubuntu Pro FIPS 22.04 in FIPS mode), Shielded VM (secure boot, vTPM, integrity monitoring), static external IP, dedicated service account with only logging.logWriter + monitoring.metricWriter, project SSH keys blocked, in zone (default <region>-a; <region>-b in us-east1 and europe-west1, which have no -a zone; it must be inside the region). Login user = ssh_username (defaults to your local username) with metadata keys; with OS Login see Gotchas.
  • Logging baseline (enable_project_baseline, one env per project): _Default log bucket retention set to log_retention_days; optional Data Access audit logs for all services (enable_data_access_audit_logs). Both are project-wide and kept on destroy (see Gotchas).
  • Remote state (when chosen): GCS bucket, versioned, uniform bucket-level access, public access prevention enforced.
  • GKE (optional, enable_kubernetes=true): private cluster in the private subnet (private nodes, private endpoint unless kubernetes_public_endpoint=true, control plane in kubernetes_master_cidr), VPC-native, Dataplane V2, Workload Identity, shielded COS nodes, autoscaling from max(kubernetes_node_min, kubernetes_node_count) - the count is the floor, 2 by default - up to max(kubernetes_node_max, kubernetes_node_count), control-plane logs (API server, scheduler, controller manager). Secrets are encrypted at rest with Google-managed keys (no application-layer KMS key). Workload Identity service accounts for external-secrets, external-dns and (via cloudseed platform install velero) velero, plus the Velero GCS bucket. kubectl needs gke-gcloud-auth-plugin (gcloud components install gke-gcloud-auth-plugin); after creation the node pool is resized through the GKE API (cloudseed node add|remove|scale).
  • VPN host (optional, enable_vpn=true): OpenVPN (default) or a Tailscale subnet router (vpn_type=tailscale, needs TS_AUTHKEY) in the public subnet; project SSH keys blocked.
  • FIPS 140 (optional, fips_mode=true, new environments only): bastion and VPN host on the Ubuntu Pro FIPS 22.04 image (metered, no token needed), GKE on Container-Optimized OS, RSA-4096 SSH keys; Tailscale, kubeadm and ed25519 keys are refused.

Stack variables

Override any of these with --var name=value on cloudseed setup gcp (JSON for lists and maps; --var name=null drops a saved override). Values are read by the variable's declared type.

Variable Default Description
project_id none: --project-id, GOOGLE_PROJECT, GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT or GCLOUD_PROJECT GCP project to deploy into.
zone <region>-a, or <region>-b in us-east1 / europe-west1 (--zone) Zone (inside region) for the bastion, the VPN host and the zonal GKE cluster.
subnet_newbits 4 Extra bits added to network_cidr to carve the public and private subnets (4 => /20s from a /16).
ssh_username your local username (--ssh-username) Login user on the bastion and VPN host (metadata SSH key). With enable_os_login cloudseed passes your Google account's OS Login POSIX username instead.
enable_os_login false Use OS Login (IAM-managed SSH) on the bastion and VPN host instead of a metadata key. cloudseed registers the environment's key with your Google account through gcloud and grants that account OS Admin Login on both.
bastion_machine_type "e2-micro" Machine type of the bastion (a name such as e2-micro or e2-small).
bastion_image "debian-cloud/debian-12" Boot image of the bastion (project/family such as debian-cloud/debian-12, or project/image). With fips_mode = true it is replaced by Ubuntu Pro FIPS 22.04 while left at this default.
bastion_disk_size 10 Boot disk size of the bastion in GB (at least 10: the image size).
enable_apis true Enable the required Google APIs on the project.
enable_project_baseline true Manage the project-wide logging settings (the _Default log bucket's retention and, with enable_data_access_audit_logs, the allServices audit config) from this environment. Set false for a second environment in the same project. A destroy leaves both settings in place; switching this off on an environment that set them removes the audit config (unless cloudseed destroy --target module.stack.module.security_baseline first drops it from the state) and leaves the retention as it is.
enable_data_access_audit_logs false Turn on Data Access audit logs for all services (extra logging cost). Project-wide; needs enable_project_baseline.
log_retention_days 90 Retention for the project's _Default log bucket (1-3650 days). Project-wide; needs enable_project_baseline.
enable_kubernetes false Create a private GKE cluster in the private subnet.
kubernetes_version null GKE minimum master version (null = release channel default).
kubernetes_node_size "e2-standard-2" Kubernetes node size: the machine type of the GKE nodes (a name such as e2-standard-2).
kubernetes_node_count 2 Nodes in the GKE node pool, and the pool's autoscaling floor (what cloudseed node add&#124;remove&#124;scale changes).
kubernetes_node_min 1 Autoscaler minimum of the GKE node pool; the pool never scales below kubernetes_node_count (floor = max(kubernetes_node_min, kubernetes_node_count)).
kubernetes_node_max 4 Autoscaler maximum of the GKE node pool (raised to kubernetes_node_count / kubernetes_node_min when lower).
kubernetes_public_endpoint false Also expose the control plane publicly, restricted to allowed_ssh_cidrs. Default: private endpoint only.
kubernetes_master_cidr "172.16.0.0/28" /28 for the GKE control plane; must not overlap network_cidr (cloudseed picks a free one when the default would).
enable_vpn false Create a VPN host (OpenVPN or a Tailscale subnet router) in the public subnet for private-network access.
vpn_type "openvpn" VPN on the VPN host: openvpn (self-contained, client certificates) or tailscale (subnet router, needs TS_AUTHKEY).
vpn_machine_type "e2-micro" Machine type of the VPN host (a name such as e2-micro).
vpn_port 1194 UDP port the OpenVPN server listens on (unused with vpn_type = tailscale: a Tailscale VPN host uses 41641).
fips_mode false FIPS 140 mode for the whole environment: Ubuntu Pro FIPS bastion (unless bastion_image is set) and VPN images, COS nodes on GKE (FIPS-validated kernel crypto), FIPS-only SSH algorithms, ECDSA SSH keys.
kubernetes_regional false Create a regional GKE control plane instead of a zonal one. Changing this replaces the cluster; review the plan and backups first.
kubernetes_node_locations [] Explicit GKE node zones. Empty preserves the zonal default; regional clusters require explicit zones so node counts and costs are predictable. Node count/min/max are per zone.

Set by cloudseed

These stack variables are refused in --var: cloudseed sets them itself. Use the flag shown instead.

Variable How to set it
region --region
name --name (default: cloudseed)
environment --env (default: dev)
network_cidr --cidr (default: the first free 10.N.0.0/16 across your environments)
allowed_ssh_cidrs --allow-ip or cloudseed update-ip (default: your public IP)
ssh_public_key the environment's generated key, or --ssh-public-key
os_login_member your gcloud account, registered by setup when enable_os_login=true
labels project/environment/owner/managedby/cloudseedenv/cloudseedenvid + --tag KEY=VALUE
platform_prereqs managed by cloudseed platform install <item> (never set it by hand)

Outputs

Read them with cloudseed output gcp --env <env> (add --json for scripts).

Output Description
project_id GCP project.
region Region of the stack.
network_name VPC network name.
network_self_link VPC self link (use when attaching resources).
public_subnet_id Public subnet (bastion).
private_subnet_id Private subnet for workloads (Cloud NAT egress).
nat_name Cloud NAT name.
bastion_public_ip Static external IP of the bastion.
bastion_name Bastion instance name.
bastion_instance_id Server-assigned ID of the bastion instance (changes when the instance is replaced).
bastion_service_account Service account of the bastion.
workload_network_tag Put this tag on private VMs so the bastion can reach them over SSH.
ssh_user Login user on the bastion and VPN host (the OS Login POSIX username when enable_os_login is on).
kubernetes_cluster_name GKE cluster name (null when Kubernetes is disabled).
kubernetes_endpoint GKE control-plane endpoint (private unless kubernetes_public_endpoint = true; null when Kubernetes is disabled).
kubernetes_location Zone or region of the cluster, for gcloud container clusters get-credentials (null when Kubernetes is disabled).
kubernetes_node_pool Name of the GKE node pool, for gcloud container clusters resize / node-pools describe (null when Kubernetes is disabled).
kubernetes_master_version GKE control-plane version as of the last apply: the REGULAR release channel upgrades it past kubernetes_version, which is only a minimum; the bastion's kubectl follows it (null when Kubernetes is disabled).
vpn_public_ip Public IP of the VPN host (null when disabled).
vpn_instance_id Server-assigned ID of the VPN host instance (null when disabled; changes when the instance is replaced).
vpn_type VPN flavour on the VPN host: openvpn or tailscale (null when the VPN is disabled).
vpn_port UDP port the VPN host listens on: vpn_port for OpenVPN, 41641 for Tailscale (null when the VPN is disabled).
kubernetes_external_secrets_gsa Google service account bound (Workload Identity) to external-secrets/external-secrets (null when Kubernetes is disabled).
kubernetes_external_dns_gsa Google service account bound (Workload Identity) to external-dns/external-dns (null when Kubernetes is disabled).
kubernetes_velero_gsa Google service account bound (Workload Identity) to velero/velero (null until the velero platform item is installed, and when Kubernetes is disabled).
kubernetes_velero_bucket GCS bucket for Velero backups (null until the velero platform item is installed, and when Kubernetes is disabled).
fips_mode Whether the environment was built in FIPS 140 mode.
kubernetes_master_cidr GKE control-plane range (outside network_cidr): routed through the VPN so the private API endpoint is reachable (null when Kubernetes is disabled).

Gotchas

  • The project must exist and billing must be enabled; cloudseed does not create projects or org policies.
  • The Service Usage and Cloud Resource Manager APIs must already be enabled in the project that owns the credentials (the service account's project, or the gcloud quota project for ADC): cloudseed enables the other APIs through them.
  • OS Login (enable_os_login=true) is automatic but needs the gcloud CLI logged in (gcloud auth login): setup registers the environment's key with that Google account, uses the account's POSIX username as the login user (not ssh_username) and grants it roles/compute.osAdminLogin on the bastion and VPN host plus roles/iam.serviceAccountUser on their service accounts. Users outside the project's organization also need roles/compute.osLoginExternalUser (granted at the organization).
  • The OS Login key lives on the Google account, not in the project. cloudseed removes it again - after a full destroy, and after a setup that rotated the key or turned OS Login off - only when cloudseed added it (a key that was already registered, e.g. your own --ssh-public-key, is never removed) and no other environment logs in with it; when it cannot, it prints the command. Manual cleanup: gcloud compute os-login ssh-keys list and gcloud compute os-login ssh-keys remove --key <fingerprint>.
  • A key registered with an expiry (outside cloudseed) that has expired or expires within the hour is registered again without one: cloudseed then owns it and removes it on destroy. A later expiry is only warned about (SSH stops working then).
  • The _Default log retention and the Data Access audit config (allServices) are project-wide: let one environment per project manage them (--var enable_project_baseline=false for the others). A destroy keeps both, no longer managed: the retention stays at the value cloudseed set (Google never restores an earlier value; reset it with gcloud logging buckets update _Default --location=global --retention-days=30 --project <project>), and the allServices audit config stays on for the whole project. A setup or apply that would delete them (enable_project_baseline=false, enable_data_access_audit_logs=false) keeps them the same way: they are only dropped from the state, and the run prints how to change them by hand.
  • Not every region has a -a zone: the default is <region>-b in us-east1 and europe-west1; pass --zone for another zone of the region.
  • The default network is left in place (importing it is out of scope); recommend deleting it manually for a clean project.
  • Labels on every resource: project, environment, owner, managedby, cloudseedenv, cloudseedenvid (reconcile reads them) plus --tag K=V.
  • Credentials: gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS. Never handle key files yourself.