Create an instance in a specific subnet

By default, every instance has a single network interface that determines the VPC network that the instance uses. You can create an instance with multiple network interfaces , but each interface must connect to a different VPC network. Each network must have at least one subnet, which defines the range of IPv4 or IPv6 addresses that can be assigned to the instance.

For more information, see the following:

By default, Google Cloud creates an auto mode VPC network called default for each project. To use a different network or a subnet that you manually created in an auto mode or custom mode VPC network, you must specify the subnet when you create the instance and configure the network interface.

Before you begin

If you haven't already, set up authentication . Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
  gcloud init
  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
  
  Note:If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update .
2. Set a default region and zone .
REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create an instance with a specific subnet, ask your administrator to grant you the Compute Instance Admin (v1) ( roles/compute.instanceAdmin.v1 ) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations .

This predefined role contains the permissions required to create an instance with a specific subnet. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to create an instance with a specific subnet:

compute.instances.create on the project
To specify a subnet for your instance: compute.subnetworks.use on the project or on the chosen subnet
To assign an external IP address to the instance when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet

You might also be able to get these permissions with custom roles or other predefined roles .

Requirements

When you create an instance in a subnet, consider these rules:

If you don't specify a network or subnet, Compute Engine uses the default VPC network and the auto subnet that's in the same region as the instance.
If you don't specify a network, Compute Engine infers the network from the subnet specified.
If you specify a network, you must specify a subnet and it must belong to the same network. Otherwise, instance creation fails.

You must create the subnet that you want to use before you create the instance. For more information, see Create and manage VPC networks .

Create an instance in a specific subnet

To create an instance in a specific subnet, follow these steps:

Console

In the Google Cloud console, go to the Create an instancepage.

Go to Create an instance

If prompted, select your project and click Continue.

The Create an instancepage appears and displays the Machine configurationpane.
In the Machine configurationpane, do the following:
1. In the Namefield, specify a name for your instance. For more information, see Resource naming convention .
2. Optional: In the Zonefield, select a zone for this instance.
  
  The default selection is Any. If you don't change this default selection, then Google automatically chooses a zone for you based on machine type and availability.
3. Select the machine family for your instance. The Google Cloud console then displays the machine series that are available for your selected machine family. The following machine family options are available:
  - General purpose
  - Compute optimized
  - Memory optimized
  - Storage optimized
  - GPUs
4. In the Seriescolumn, select the machine series for your instance.
  
  If you selected GPUsas the machine family in the previous step, then select the GPU typethat you want. The machine series is then automatically selected for the selected GPU type.
5. In the Machine typesection, select the machine type for your instance.
In the navigation menu, click Networking. In the Networkingpane that appears, do the following:
1. To permit HTTP or HTTPS traffic to the instance, go to the Firewallsection and select Allow HTTP trafficor Allow HTTPS traffic.
  
  The Compute Engine adds a network tag to your instance and creates the corresponding ingress firewall rule that allows all incoming traffic on tcp:80 (HTTP) or tcp:443 (HTTPS). The network tag associates the firewall rule with the instance. For more information, see Firewall rules overview in the Cloud Next Generation Firewall documentation.
2. To specify the network interface details, go to the Network interfacessection and click Add a network interface.
  
  In the New network interfacesection that appears, do the following:
  1. In the Networkfield, select the VPC network that contains the subnet you created.
  2. In the Subnetworklist, select the subnet for the instance to use.
  3. In the IP stack typefield, select the IP stack type for the network interface.
  4. To confirm the network interface details, click Done.
Optional: Specify other configuration options. For more information, see Configuration options during instance creation .
To create and start the instance, click Create.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Using the Google Cloud CLI, follow the same instructions to create an instance from a public image or a snapshot , and include the networking flags shown in this section when you run the gcloud compute instances create command :
```
gcloud compute instances create INSTANCE_NAME 
\
    --zone= ZONE 
\
    --machine-type= MACHINE_TYPE 
\
    --create-disk=boot=yes,image=projects/ IMAGE_PROJECT 
/global/images/ IMAGE 
,size= SIZE 
\
    --network= NETWORK_NAME 
\
    --subnet= SUBNET_NAME 
\
    --stack-type= STACK_TYPE 
\
    --private-network-ip= INTERNAL_IPV4_ADDRESS 
\
    --address= EXTERNAL_IPV4_ADDRESS 
\
    --nic-type=GVNIC
```
Replace the following:
- INSTANCE_NAME : the name of the compute instance
- ZONE : the zone where the instance is created, such as europe-west1-b . The instance's region is inferred from the zone.
- MACHINE_TYPE : Optional: the machine type to use for the instance.
- IMAGE_PROJECT : Optional: the image project that contains the image
- IMAGE : Optional: specify one of the following:
  - A specific version of the OS image—for example, rocky-linux-9-optimized-gcp-v20240717 .
  - An image family , which must be formatted as family/ IMAGE_FAMILY . This creates the instance from the most recent, non-deprecated OS image. For example, if you specify family/rocky-linux-9-optimized-gcp , then Compute Engine creates an instance using the latest version of the OS image in the Rocky Linux 9 optimized for Google Cloud image family. For more information about using image families, see Image families best practices .
- SIZE : Optional: the size of the new disk. The value must be a whole number. The default unit of measurement is GiB.
- NETWORK_NAME : Optional: name of the network
- SUBNET_NAME : name of the subnet to use with the instance.
  
  To view a list of subnets in the network, use the gcloud compute networks subnets list command .
- STACK_TYPE : Optional: the stack type for the network interface. STACK_TYPE must be one of: IPV4_ONLY , IPV4_IPV6 , or IPV6_ONLY ( Preview ). The default value is IPV4_ONLY .
- INTERNAL_IPV4_ADDRESS : Optional: the internal IPv4 address that you want the compute instance to use in the target subnet. Omit this flag if you don't need a specific IP address.
  
  To specify an internal IPv6 address, use the flag --internal-ipv6-address instead.
- EXTERNAL_IPV4_ADDRESS : Optional: the static external IPv4 address to use with the network interface. You must have previously reserved an external IPv4 address . Do one of the following:
  - Specify a valid IPv4 address from the subnet.
  - Use the flag --network-interface=no-address instead if you don't want the network interface to have an external IP address.
  - Specify address='' if you want the interface to receive an ephemeral external IP address.
  To specify an external IPv6 address, use the flag --external-ipv6-address instead.

Terraform

To create an instance in a specific subnet, you can use the google_compute_instance resource .

 # Create a VM in a custom VPC network and subnet

resource "google_compute_instance" "custom_subnet" {
  name         = "my-vm-instance"
  tags         = ["allow-ssh"]
  zone         = "europe-west1-b"
  machine_type = "e2-small"
  network_interface {
    network    = google_compute_network.custom.id
    subnetwork = google_compute_subnetwork.custom.id
  }
  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands .

To generate the Terraform code, you can use the Equivalent codecomponent in the Google Cloud console.

In the Google Cloud console, go to the VM instancespage.
Go to VM Instances
Click Create instance.
Specify the parameters you want.
At the top or bottom of the page, click Equivalent code, and then click the Terraformtab to view the Terraform code.

Go

Before trying this sample, follow the Go setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine Go API reference documentation .

To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 compute 
  
 "cloud.google.com/go/compute/apiv1" 
  
 computepb 
  
 "cloud.google.com/go/compute/apiv1/computepb" 
  
 "google.golang.org/protobuf/proto" 
 ) 
 // createInstanceWithSubnet creates a new VM instance with Debian 10 operating system in specified network and subnetwork. 
 func 
  
 createInstanceWithSubnet 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 zone 
 , 
  
 instanceName 
 , 
  
 networkLink 
 , 
  
 subnetworkLink 
  
 string 
 ) 
  
 error 
  
 { 
  
 // projectID := "your_project_id" 
  
 // zone := "europe-central2-b" 
  
 // instanceName := "your_instance_name" 
  
 // networkLink := "global/networks/default" 
  
 // subnetworkLink := "regions/region/subnetworks/subnetwork_name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 instancesClient 
 , 
  
 err 
  
 := 
  
 compute 
 . 
  NewInstancesRESTClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewInstancesRESTClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 instancesClient 
 . 
 Close 
 () 
  
 imagesClient 
 , 
  
 err 
  
 := 
  
 compute 
 . 
  NewImagesRESTClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewImagesRESTClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 imagesClient 
 . 
 Close 
 () 
  
 // List of public operating system (OS) images: https://cloud.google.com/compute/docs/images/os-details. 
  
 newestDebianReq 
  
 := 
  
& computepb 
 . 
 GetFromFamilyImageRequest 
 { 
  
 Project 
 : 
  
 "debian-cloud" 
 , 
  
 Family 
 : 
  
 "debian-12" 
 , 
  
 } 
  
 newestDebian 
 , 
  
 err 
  
 := 
  
 imagesClient 
 . 
  GetFromFamily 
 
 ( 
 ctx 
 , 
  
 newestDebianReq 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "unable to get image from family: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 req 
  
 := 
  
& computepb 
 . 
 InsertInstanceRequest 
 { 
  
 Project 
 : 
  
 projectID 
 , 
  
 Zone 
 : 
  
 zone 
 , 
  
 InstanceResource 
 : 
  
& computepb 
 . 
 Instance 
 { 
  
 Name 
 : 
  
 proto 
 . 
 String 
 ( 
 instanceName 
 ), 
  
 Disks 
 : 
  
 [] 
 * 
 computepb 
 . 
 AttachedDisk 
 { 
  
 { 
  
 InitializeParams 
 : 
  
& computepb 
 . 
 AttachedDiskInitializeParams 
 { 
  
 DiskSizeGb 
 : 
  
 proto 
 . 
 Int64 
 ( 
 10 
 ), 
  
 SourceImage 
 : 
  
 newestDebian 
 . 
 SelfLink 
 , 
  
 DiskType 
 : 
  
 proto 
 . 
 String 
 ( 
 fmt 
 . 
 Sprintf 
 ( 
 "zones/%s/diskTypes/pd-standard" 
 , 
  
 zone 
 )), 
  
 }, 
  
 AutoDelete 
 : 
  
 proto 
 . 
 Bool 
 ( 
 true 
 ), 
  
 Boot 
 : 
  
 proto 
 . 
 Bool 
 ( 
 true 
 ), 
  
 Type 
 : 
  
 proto 
 . 
 String 
 ( 
 computepb 
 . 
  AttachedDisk_PERSISTENT 
 
 . 
 String 
 ()), 
  
 }, 
  
 }, 
  
 MachineType 
 : 
  
 proto 
 . 
 String 
 ( 
 fmt 
 . 
 Sprintf 
 ( 
 "zones/%s/machineTypes/n1-standard-1" 
 , 
  
 zone 
 )), 
  
 NetworkInterfaces 
 : 
  
 [] 
 * 
 computepb 
 . 
 NetworkInterface 
 { 
  
 { 
  
 Name 
 : 
  
 proto 
 . 
 String 
 ( 
 networkLink 
 ), 
  
 Subnetwork 
 : 
  
 proto 
 . 
 String 
 ( 
 subnetworkLink 
 ), 
  
 }, 
  
 }, 
  
 }, 
  
 } 
  
 op 
 , 
  
 err 
  
 := 
  
 instancesClient 
 . 
 Insert 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "unable to create instance: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 if 
  
 err 
  
 = 
  
 op 
 . 
 Wait 
 ( 
 ctx 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "unable to wait for the operation: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Instance created\n" 
 ) 
  
 return 
  
 nil 
 }

Java

Before trying this sample, follow the Java setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine Java API reference documentation .

To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.api.gax.longrunning. OperationFuture 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. AttachedDisk 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. AttachedDisk 
.Type 
 ; 
 import 
  
 com.google.cloud.compute.v1. AttachedDiskInitializeParams 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. Image 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. ImagesClient 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. InsertInstanceRequest 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. Instance 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. InstancesClient 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. NetworkInterface 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. Operation 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.Vector 
 ; 
 import 
  
 java.util.concurrent.ExecutionException 
 ; 
 import 
  
 java.util.concurrent.TimeUnit 
 ; 
 import 
  
 java.util.concurrent.TimeoutException 
 ; 
 public 
  
 class 
 CreateInstancesAdvanced 
  
 { 
  
 /** 
 * Create an AttachedDisk object to be used in VM instance creation. Uses an image as the source 
 * for the new disk. 
 * 
 * @param diskType the type of disk you want to create. This value uses the following format: 
 * "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)". For example: 
 * "zones/us-west3-b/diskTypes/pd-ssd" 
 * @param diskSizeGb size of the new disk in gigabytes 
 * @param boot boolean flag indicating whether this disk should be used as a boot disk of an 
 * instance 
 * @param sourceImage source image to use when creating this disk. You must have read access to 
 * this disk. This can be one of the publicly available images or an image from one of your 
 * projects. This value uses the following format: 
 * "projects/{project_name}/global/images/{image_name}" 
 * @return AttachedDisk object configured to be created using the specified image. 
 */ 
  
 private 
  
 static 
  
  AttachedDisk 
 
  
 diskFromImage 
 ( 
 String 
  
 diskType 
 , 
  
 int 
  
 diskSizeGb 
 , 
  
 boolean 
  
 boot 
 , 
  
 String 
  
 sourceImage 
 ) 
  
 { 
  
  AttachedDisk 
 
  
 disk 
  
 = 
  
  AttachedDisk 
 
 . 
 newBuilder 
 () 
  
 . 
 setBoot 
 ( 
 boot 
 ) 
  
 // Remember to set auto_delete to True if you want the disk to be deleted when 
  
 // you delete your VM instance. 
  
 . 
 setAutoDelete 
 ( 
 true 
 ) 
  
 . 
 setType 
 ( 
 Type 
 . 
 PERSISTENT 
 . 
 toString 
 ()) 
  
 . 
  setInitializeParams 
 
 ( 
  
  AttachedDiskInitializeParams 
 
 . 
 newBuilder 
 () 
  
 . 
 setSourceImage 
 ( 
 sourceImage 
 ) 
  
 . 
 setDiskSizeGb 
 ( 
 diskSizeGb 
 ) 
  
 . 
 setDiskType 
 ( 
 diskType 
 ) 
  
 . 
 build 
 ()) 
  
 . 
 build 
 (); 
  
 return 
  
 disk 
 ; 
  
 } 
  
 /** 
 * Send an instance creation request to the Compute Engine API and wait for it to complete. 
 * 
 * @param project project ID or project number of the Cloud project you want to use. 
 * @param zone name of the zone to create the instance in. For example: "us-west3-b" 
 * @param instanceName name of the new virtual machine (VM) instance. 
 * @param disks a list of compute_v1.AttachedDisk objects describing the disks you want to attach 
 * to your new instance. 
 * @param machineType machine type of the VM being created. This value uses the following format: 
 * "zones/{zone}/machineTypes/{type_name}". 
 * For example: "zones/europe-west3-c/machineTypes/f1-micro" 
 * @param network name of the network you want the new instance to use. For example: 
 * "global/networks/default" represents the network named "default", which is created 
 * automatically for each project. 
 * @param subnetwork name of the subnetwork you want the new instance to use. This value uses the 
 * following format: "regions/{region}/subnetworks/{subnetwork_name}" 
 * @return Instance object. 
 */ 
  
 private 
  
 static 
  
  Instance 
 
  
 createWithDisks 
 ( 
 String 
  
 project 
 , 
  
 String 
  
 zone 
 , 
  
 String 
  
 instanceName 
 , 
  
 Vector<AttachedDisk> 
  
 disks 
 , 
  
 String 
  
 machineType 
 , 
  
 String 
  
 network 
 , 
  
 String 
  
 subnetwork 
 ) 
  
 throws 
  
 IOException 
 , 
  
 InterruptedException 
 , 
  
 ExecutionException 
 , 
  
 TimeoutException 
  
 { 
  
 try 
  
 ( 
  InstancesClient 
 
  
 instancesClient 
  
 = 
  
  InstancesClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // Use the network interface provided in the networkName argument. 
  
  NetworkInterface 
 
  
 networkInterface 
 ; 
  
 if 
  
 ( 
 subnetwork 
  
 != 
  
 null 
 ) 
  
 { 
  
 networkInterface 
  
 = 
  
  NetworkInterface 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 network 
 ). 
 setSubnetwork 
 ( 
 subnetwork 
 ) 
  
 . 
 build 
 (); 
  
 } 
  
 else 
  
 { 
  
 networkInterface 
  
 = 
  
  NetworkInterface 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 network 
 ). 
 build 
 (); 
  
 } 
  
 machineType 
  
 = 
  
 String 
 . 
 format 
 ( 
 "zones/%s/machineTypes/%s" 
 , 
  
 zone 
 , 
  
 machineType 
 ); 
  
 // Bind `instanceName`, `machineType`, `disk`, and `networkInterface` to an instance. 
  
  Instance 
 
  
 instanceResource 
  
 = 
  
  Instance 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 instanceName 
 ) 
  
 . 
 setMachineType 
 ( 
 machineType 
 ) 
  
 . 
 addAllDisks 
 ( 
 disks 
 ) 
  
 . 
 addNetworkInterfaces 
 ( 
 networkInterface 
 ) 
  
 . 
 build 
 (); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Creating instance: %s at %s " 
 , 
  
 instanceName 
 , 
  
 zone 
 ); 
  
 // Insert the instance in the specified project and zone. 
  
  InsertInstanceRequest 
 
  
 insertInstanceRequest 
  
 = 
  
  InsertInstanceRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setProject 
 ( 
 project 
 ) 
  
 . 
 setZone 
 ( 
 zone 
 ) 
  
 . 
 setInstanceResource 
 ( 
 instanceResource 
 ). 
 build 
 (); 
  
 OperationFuture<Operation 
 , 
  
 Operation 
>  
 operation 
  
 = 
  
 instancesClient 
 . 
 insertAsync 
 ( 
  
 insertInstanceRequest 
 ); 
  
 // Wait for the operation to complete. 
  
  Operation 
 
  
 response 
  
 = 
  
 operation 
 . 
 get 
 ( 
 3 
 , 
  
 TimeUnit 
 . 
 MINUTES 
 ); 
  
 if 
  
 ( 
 response 
 . 
  hasError 
 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Instance creation failed ! ! " 
  
 + 
  
 response 
 ); 
  
 return 
  
 null 
 ; 
  
 } 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Operation Status: " 
  
 + 
  
 response 
 . 
  getStatus 
 
 ()); 
  
 return 
  
 instancesClient 
 . 
 get 
 ( 
 project 
 , 
  
 zone 
 , 
  
 instanceName 
 ); 
  
 } 
  
 }

Node.js

Before trying this sample, follow the Node.js setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine Node.js API reference documentation .

To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  /** 
 * TODO(developer): Uncomment and replace these variables before running the sample. 
 */ 
 // const projectId = 'YOUR_PROJECT_ID'; 
 // const zone = 'europe-central2-b'; 
 // const instanceName = 'YOUR_INSTANCE_NAME'; 
 // const networkLink = 'global/networks/default'; 
 // const subnetworkLink = 'regions/europe-central2/subnetworks/default'; 
 const 
  
 compute 
  
 = 
  
 require 
 ( 
 ' @google-cloud/compute 
' 
 ); 
 // Creates a new VM instance with Debian 10 operating system in specified network and subnetwork. 
 async 
  
 function 
  
 createInstanceWithSubnet 
 () 
  
 { 
  
 const 
  
 instancesClient 
  
 = 
  
 new 
  
 compute 
 . 
  InstancesClient 
 
 (); 
  
 const 
  
 imagesClient 
  
 = 
  
 new 
  
 compute 
 . 
  ImagesClient 
 
 (); 
  
 // List of public operating system (OS) images: https://cloud.google.com/compute/docs/images/os-details. 
  
 const 
  
 [ 
 newestDebian 
 ] 
  
 = 
  
 await 
  
 imagesClient 
 . 
 getFromFamily 
 ({ 
  
 project 
 : 
  
 'debian-cloud' 
 , 
  
 family 
 : 
  
 'debian-11' 
 , 
  
 }); 
  
 const 
  
 [ 
 response 
 ] 
  
 = 
  
 await 
  
 instancesClient 
 . 
 insert 
 ({ 
  
 project 
 : 
  
 projectId 
 , 
  
 zone 
 , 
  
 instanceResource 
 : 
  
 { 
  
 name 
 : 
  
 instanceName 
 , 
  
 disks 
 : 
  
 [ 
  
 { 
  
 initializeParams 
 : 
  
 { 
  
 diskSizeGb 
 : 
  
 '10' 
 , 
  
 sourceImage 
 : 
  
 newestDebian 
 . 
 selfLink 
 , 
  
 diskType 
 : 
  
 `zones/ 
 ${ 
 zone 
 } 
 /diskTypes/pd-standard` 
 , 
  
 }, 
  
 autoDelete 
 : 
  
 true 
 , 
  
 boot 
 : 
  
 true 
 , 
  
 type 
 : 
  
 'PERSISTENT' 
 , 
  
 }, 
  
 ], 
  
 machineType 
 : 
  
 `zones/ 
 ${ 
 zone 
 } 
 /machineTypes/n1-standard-1` 
 , 
  
 networkInterfaces 
 : 
  
 [ 
  
 { 
  
 name 
 : 
  
 networkLink 
 , 
  
 subnetwork 
 : 
  
 subnetworkLink 
 , 
  
 }, 
  
 ], 
  
 }, 
  
 }); 
  
 let 
  
 operation 
  
 = 
  
 response 
 . 
 latestResponse 
 ; 
  
 const 
  
 operationsClient 
  
 = 
  
 new 
  
 compute 
 . 
  ZoneOperationsClient 
 
 (); 
  
 // Wait for the create operation to complete. 
  
 while 
  
 ( 
 operation 
 . 
 status 
  
 !== 
  
 'DONE' 
 ) 
  
 { 
  
 [ 
 operation 
 ] 
  
 = 
  
 await 
  
 operationsClient 
 . 
 wait 
 ({ 
  
 operation 
 : 
  
 operation 
 . 
 name 
 , 
  
 project 
 : 
  
 projectId 
 , 
  
 zone 
 : 
  
 operation 
 . 
 zone 
 . 
 split 
 ( 
 '/' 
 ). 
 pop 
 (), 
  
 }); 
  
 } 
  
 console 
 . 
 log 
 ( 
 'Instance created.' 
 ); 
 } 
 createInstanceWithSubnet 
 ();

from __future__ import annotations import re import sys from typing import Any import warnings from google.api_core.extended_operation import ExtendedOperation from google.cloud import compute_v1 def get_image_from_family ( project : str , family : str ) - > compute_v1 . Image : """ Retrieve the newest image that is part of a given family in a project. Args: project: project ID or project number of the Cloud project you want to get image from. family: name of the image family you want to get image from. Returns: An Image object. """ image_client = compute_v1 . ImagesClient () # List of public operating system (OS) images: https://cloud.google.com/compute/docs/images/os-details newest_image = image_client . get_from_family ( project = project , family = family ) return newest_image def disk_from_image ( disk_type : str , disk_size_gb : int , boot : bool , source_image : str , auto_delete : bool = True , ) - > compute_v1 . AttachedDisk : """ Create an AttachedDisk object to be used in VM instance creation. Uses an image as the source for the new disk. Args: disk_type: the type of disk you want to create. This value uses the following format: "zones/{zone}/diskTypes/(pd-standard|pd-ssd|pd-balanced|pd-extreme)". For example: "zones/us-west3-b/diskTypes/pd-ssd" disk_size_gb: size of the new disk in gigabytes boot: boolean flag indicating whether this disk should be used as a boot disk of an instance source_image: source image to use when creating this disk. You must have read access to this disk. This can be one of the publicly available images or an image from one of your projects. This value uses the following format: "projects/{project_name}/global/images/{image_name}" auto_delete: boolean flag indicating whether this disk should be deleted with the VM that uses it Returns: AttachedDisk object configured to be created using the specified image. """ boot_disk = compute_v1 . AttachedDisk () initialize_params = compute_v1 . AttachedDiskInitializeParams () initialize_params . source_image = source_image initialize_params . disk_size_gb = disk_size_gb initialize_params . disk_type = disk_type boot_disk . initialize_params = initialize_params # Remember to set auto_delete to True if you want the disk to be deleted when you delete # your VM instance. boot_disk . auto_delete = auto_delete boot_disk . boot = boot return boot_disk def wait_for_extended_operation ( operation : ExtendedOperation , verbose_name : str = "operation" , timeout : int = 300 ) - > Any : """ Waits for the extended (long-running) operation to complete. If the operation is successful, it will return its result. If the operation ends with an error, an exception will be raised. If there were any warnings during the execution of the operation they will be printed to sys.stderr. Args: operation: a long-running operation you want to wait on. verbose_name: (optional) a more verbose name of the operation, used only during error and warning reporting. timeout: how long (in seconds) to wait for operation to finish. If None, wait indefinitely. Returns: Whatever the operation.result() returns. Raises: This method will raise the exception received from `operation.exception()` or RuntimeError if there is no exception set, but there is an `error_code` set for the `operation`. In case of an operation taking longer than `timeout` seconds to complete, a `concurrent.futures.TimeoutError` will be raised. """ result = operation . result ( timeout = timeout ) if operation . error_code : print ( f "Error during { verbose_name } : [Code: { operation . error_code } ]: { operation . error_message } " , file = sys . stderr , flush = True , ) print ( f "Operation ID: { operation . name } " , file = sys . stderr , flush = True ) raise operation . exception () or RuntimeError ( operation . error_message ) if operation . warnings : print ( f "Warnings during { verbose_name } : \n " , file = sys . stderr , flush = True ) for warning in operation . warnings : print ( f " - { warning . code } : { warning . message } " , file = sys . stderr , flush = True ) return result def create_instance ( project_id : str , zone : str , instance_name : str , disks : list [ compute_v1 . AttachedDisk ], machine_type : str = "n1-standard-1" , network_link : str = "global/networks/default" , subnetwork_link : str = None , internal_ip : str = None , external_access : bool = False , external_ipv4 : str = None , accelerators : list [ compute_v1 . AcceleratorConfig ] = None , preemptible : bool = False , spot : bool = False , instance_termination_action : str = "STOP" , custom_hostname : str = None , delete_protection : bool = False , ) - > compute_v1 . Instance : """ Send an instance creation request to the Compute Engine API and wait for it to complete. Args: project_id: project ID or project number of the Cloud project you want to use. zone: name of the zone to create the instance in. For example: "us-west3-b" instance_name: name of the new virtual machine (VM) instance. disks: a list of compute_v1.AttachedDisk objects describing the disks you want to attach to your new instance. machine_type: machine type of the VM being created. This value uses the following format: "zones/{zone}/machineTypes/{type_name}". For example: "zones/europe-west3-c/machineTypes/f1-micro" network_link: name of the network you want the new instance to use. For example: "global/networks/default" represents the network named "default", which is created automatically for each project. subnetwork_link: name of the subnetwork you want the new instance to use. This value uses the following format: "regions/{region}/subnetworks/{subnetwork_name}" internal_ip: internal IP address you want to assign to the new instance. By default, a free address from the pool of available internal IP addresses of used subnet will be used. external_access: boolean flag indicating if the instance should have an external IPv4 address assigned. external_ipv4: external IPv4 address to be assigned to this instance. If you specify an external IP address, it must live in the same region as the zone of the instance. This setting requires `external_access` to be set to True to work. accelerators: a list of AcceleratorConfig objects describing the accelerators that will be attached to the new instance. preemptible: boolean value indicating if the new instance should be preemptible or not. Preemptible VMs have been deprecated and you should now use Spot VMs. spot: boolean value indicating if the new instance should be a Spot VM or not. instance_termination_action: What action should be taken once a Spot VM is terminated. Possible values: "STOP", "DELETE" custom_hostname: Custom hostname of the new VM instance. Custom hostnames must conform to RFC 1035 requirements for valid hostnames. delete_protection: boolean value indicating if the new virtual machine should be protected against deletion or not. Returns: Instance object. """ instance_client = compute_v1 . InstancesClient () # Use the network interface provided in the network_link argument. network_interface = compute_v1 . NetworkInterface () network_interface . network = network_link if subnetwork_link : network_interface . subnetwork = subnetwork_link if internal_ip : network_interface . network_i_p = internal_ip if external_access : access = compute_v1 . AccessConfig () access . type_ = compute_v1 . AccessConfig . Type . ONE_TO_ONE_NAT . name access . name = "External NAT" access . network_tier = access . NetworkTier . PREMIUM . name if external_ipv4 : access . nat_i_p = external_ipv4 network_interface . access_configs = [ access ] # Collect information into the Instance object. instance = compute_v1 . Instance () instance . network_interfaces = [ network_interface ] instance . name = instance_name instance . disks = disks if re . match ( r "^zones/[a-z\d\-]+/machineTypes/[a-z\d\-]+$" , machine_type ): instance . machine_type = machine_type else : instance . machine_type = f "zones/ { zone } /machineTypes/ { machine_type } " instance . scheduling = compute_v1 . Scheduling () if accelerators : instance . guest_accelerators = accelerators instance . scheduling . on_host_maintenance = ( compute_v1 . Scheduling . OnHostMaintenance . TERMINATE . name ) if preemptible : # Set the preemptible setting warnings . warn ( "Preemptible VMs are being replaced by Spot VMs." , DeprecationWarning ) instance . scheduling = compute_v1 . Scheduling () instance . scheduling . preemptible = True if spot : # Set the Spot VM setting instance . scheduling . provisioning_model = ( compute_v1 . Scheduling . ProvisioningModel . SPOT . name ) instance . scheduling . instance_termination_action = instance_termination_action if custom_hostname is not None : # Set the custom hostname for the instance instance . hostname = custom_hostname if delete_protection : # Set the delete protection bit instance . deletion_protection = True # Prepare the request to insert an instance. request = compute_v1 . InsertInstanceRequest () request . zone = zone request . project = project_id request . instance_resource = instance # Wait for the create operation to complete. print ( f "Creating the { instance_name } instance in { zone } ..." ) operation = instance_client . insert ( request = request ) wait_for_extended_operation ( operation , "instance creation" ) print ( f "Instance { instance_name } created." ) return instance_client . get ( project = project_id , zone = zone , instance = instance_name ) def create_with_subnet ( project_id : str , zone : str , instance_name : str , network_link : str , subnet_link : str ) - > compute_v1 . Instance : """ Create a new VM instance with Debian 10 operating system in specified network and subnetwork. Args: project_id: project ID or project number of the Cloud project you want to use. zone: name of the zone to create the instance in. For example: "us-west3-b" instance_name: name of the new virtual machine (VM) instance. network_link: name of the network you want the new instance to use. For example: "global/networks/default" represents the network named "default", which is created automatically for each project. subnetwork_link: name of the subnetwork you want the new instance to use. This value uses the following format: "regions/{region}/subnetworks/{subnetwork_name}" Returns: Instance object. """ newest_debian = get_image_from_family ( project = "debian-cloud" , family = "debian-12" ) disk_type = f "zones/ { zone } /diskTypes/pd-standard" disks = [ disk_from_image ( disk_type , 10 , True , newest_debian . self_link )] instance = create_instance ( project_id , zone , instance_name , disks , network_link = network_link , subnetwork_link = subnet_link , ) return instance

POST https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID /zones/ ZONE /instances { "machineType":"zones/ MACHINE_TYPE_ZONE /machineTypes/ MACHINE_TYPE ", "name":" VM_NAME ", "disks":[ { "initializeParams":{ "sourceImage":"projects/ IMAGE_PROJECT /global/images/ IMAGE " }, "boot":true } ], "networkInterfaces":[ { "network":"global/networks/ NETWORK_NAME ", "subnetwork":"regions/ REGION /subnetworks/ SUBNET_NAME ", "stackType":" STACK_TYPE " } ], "shieldedInstanceConfig":{ "enableSecureBoot":" ENABLE_SECURE_BOOT " } }

What's next?

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-09-02 UTC.

Create an instance in a specific subnet Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

Required roles

Required permissions

Requirements

Create an instance in a specific subnet

Console

gcloud

Terraform

Go

Java

Node.js

Python

REST

What's next?

Create an instance in a specific subnet