gcloud compute instances create: Provision a VM

gcloud compute instances create launches one or more Compute Engine virtual machines from an image.

When a pipeline needs an ephemeral VM, whether a self-hosted runner or a load generator, this is the command that brings it up with the machine type and image you specify.

What it does

gcloud compute instances create provisions a VM in the named zone using a base image, machine type, network, and optional startup script. It returns once the instance is RUNNING and prints its internal and external IPs.

Common usage

Terminal

gcloud compute instances create runner-1 \
  --zone=us-central1-a \
  --machine-type=e2-standard-4 \
  --image-family=debian-12 --image-project=debian-cloud
# with a startup script and no external IP
gcloud compute instances create runner-1 \
  --zone=us-central1-a --no-address \
  --metadata-from-file=startup-script=./startup.sh \
  --quiet

Flags

Flag	What it does
--zone <zone>	Zone to create the instance in
--machine-type <type>	Machine type, e.g. e2-standard-4
--image-family / --image-project	Base image family and its project
--metadata-from-file=startup-script=<f>	Run a startup script at boot
--no-address	Do not assign an external IP
--service-account / --scopes	Identity and OAuth scopes for the VM
--quiet	Suppress interactive prompts in CI

In CI

Authenticate with Workload Identity Federation via google-github-actions/auth so the job uses a short-lived OIDC token instead of a JSON key. Add --quiet so any confirmation prompt does not stall the job, and prefer --no-address plus Cloud NAT to avoid handing public IPs to throwaway runners.

Common errors in CI

"Quota 'CPUS' exceeded" means the region is out of vCPU quota; pick a smaller machine type or another region. "The resource ... was not found" on the image means a wrong --image-family or --image-project pairing. "Required 'compute.instances.create' permission" means the service account lacks roles/compute.instanceAdmin.v1.