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=falseskips them). - Custom-mode VPC with two subnets carved from
network_cidr:publicandprivate(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, inzone(default<region>-a;<region>-bin us-east1 and europe-west1, which have no-azone; 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):_Defaultlog bucket retention set tolog_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 unlesskubernetes_public_endpoint=true, control plane inkubernetes_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 (viacloudseed platform install velero) velero, plus the Velero GCS bucket. kubectl needsgke-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, needsTS_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|remove|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 (notssh_username) and grants itroles/compute.osAdminLoginon the bastion and VPN host plusroles/iam.serviceAccountUseron their service accounts. Users outside the project's organization also needroles/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 listandgcloud 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
_Defaultlog retention and the Data Access audit config (allServices) are project-wide: let one environment per project manage them (--var enable_project_baseline=falsefor 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 withgcloud 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
-azone: the default is<region>-bin us-east1 and europe-west1; pass--zonefor 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 loginorGOOGLE_APPLICATION_CREDENTIALS. Never handle key files yourself.