List all VM instances

List all VM instances in a project, across all zones.

Explore further

For detailed documentation that includes this code sample, see the following:

Code sample

C#

Before trying this sample, follow the C# setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine C# 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 .

  using 
  
  Google.Cloud.Compute.V1 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 System.Collections.Generic 
 ; 
 using 
  
 System.Threading.Tasks 
 ; 
 public 
  
 class 
  
 ListAllInstancesAsyncSample 
 { 
  
 public 
  
 async 
  
 Task<IList<Instance> 
>  
 ListAllInstancesAsync 
 ( 
  
 // TODO(developer): Set your own default values for these parameters or pass different values when calling this method. 
  
 string 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ) 
  
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. 
  
  InstancesClient 
 
  
 client 
  
 = 
  
 await 
  
  InstancesClient 
 
 . 
  CreateAsync 
 
 (); 
  
 IList<Instance> 
  
 allInstances 
  
 = 
  
 new 
  
 List<Instance> 
 (); 
  
 // Make the request to list all VM instances in a project. 
  
 await 
  
 foreach 
  
 ( 
 var 
  
 instancesByZone 
  
 in 
  
 client 
 . 
  AggregatedListAsync 
 
 ( 
 projectId 
 )) 
  
 { 
  
 // The result contains a KeyValuePair collection, where the key is a zone and the value 
  
 // is a collection of instances in that zone. 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Instances for zone: {instancesByZone.Key}" 
 ); 
  
 foreach 
  
 ( 
 var 
  
 instance 
  
 in 
  
 instancesByZone 
 . 
 Value 
 . 
  Instances 
 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"-- Name: {instance.Name}" 
 ); 
  
 allInstances 
 . 
 Add 
 ( 
 instance 
 ); 
  
 } 
  
 } 
  
 return 
  
 allInstances 
 ; 
  
 } 
 }

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/api/iterator" 
  
 "google.golang.org/protobuf/proto" 
 ) 
 // listAllInstances prints all instances present in a project, grouped by their zone. 
 func 
  
 listAllInstances 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
  
 string 
 ) 
  
 error 
  
 { 
  
 // projectID := "your_project_id" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 instancesClient 
 , 
  
 err 
  
 := 
  
 compute 
 . 
  NewInstancesRESTClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "NewInstancesRESTClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 instancesClient 
 . 
 Close 
 () 
  
 // Use the `MaxResults` parameter to limit the number of results that the API returns per response page. 
  
 req 
  
 := 
  
& computepb 
 . 
 AggregatedListInstancesRequest 
 { 
  
 Project 
 : 
  
 projectID 
 , 
  
 MaxResults 
 : 
  
 proto 
 . 
 Uint32 
 ( 
 3 
 ), 
  
 } 
  
 it 
  
 := 
  
 instancesClient 
 . 
 AggregatedList 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Instances found:\n" 
 ) 
  
 // Despite using the `MaxResults` parameter, you don't need to handle the pagination 
  
 // yourself. The returned iterator object handles pagination 
  
 // automatically, returning separated pages as you iterate over the results. 
  
 for 
  
 { 
  
 pair 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 () 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
  Done 
 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 err 
  
 } 
  
 instances 
  
 := 
  
 pair 
 . 
 Value 
 . 
 Instances 
  
 if 
  
 len 
 ( 
 instances 
 ) 
 > 
 0 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "%s\n" 
 , 
  
 pair 
 . 
 Key 
 ) 
  
 for 
  
 _ 
 , 
  
 instance 
  
 := 
  
 range 
  
 instances 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "- %s %s\n" 
 , 
  
 instance 
 . 
 GetName 
 (), 
  
 instance 
 . 
 GetMachineType 
 ()) 
  
 } 
  
 } 
  
 } 
  
 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.cloud.compute.v1. AggregatedListInstancesRequest 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. Instance 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. InstancesClient 
 
 ; 
 import 
  
 com.google.cloud.compute.v1. InstancesClient 
.AggregatedListPagedResponse 
 ; 
 import 
  
 com.google.cloud.compute.v1. InstancesScopedList 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 ListAllInstances 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample 
  
 String 
  
 project 
  
 = 
  
 "your-project-id" 
 ; 
  
 listAllInstances 
 ( 
 project 
 ); 
  
 } 
  
 // List all instances in the specified project ID. 
  
 public 
  
 static 
  
 AggregatedListPagedResponse 
  
 listAllInstances 
 ( 
 String 
  
 project 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. After completing all of your requests, call 
  
 // the `instancesClient.close()` method on the client to 
  
 // safely clean up any remaining background resources. 
  
 try 
  
 ( 
  InstancesClient 
 
  
 instancesClient 
  
 = 
  
  InstancesClient 
 
 . 
 create 
 ()) 
  
 { 
  
 // Use the `setMaxResults` parameter to limit the number of results 
  
 // that the API returns per response page. 
  
  AggregatedListInstancesRequest 
 
  
 aggregatedListInstancesRequest 
  
 = 
  
  AggregatedListInstancesRequest 
 
  
 . 
 newBuilder 
 () 
  
 . 
 setProject 
 ( 
 project 
 ) 
  
 . 
 setMaxResults 
 ( 
 5 
 ) 
  
 . 
 build 
 (); 
  
  InstancesClient 
 
 . 
 AggregatedListPagedResponse 
  
 response 
  
 = 
  
 instancesClient 
  
 . 
 aggregatedList 
 ( 
 aggregatedListInstancesRequest 
 ); 
  
 // Despite using the `setMaxResults` parameter, you don't need to handle the pagination 
  
 // yourself. The returned `AggregatedListPager` object handles pagination 
  
 // automatically, requesting next pages as you iterate over the results. 
  
 for 
  
 ( 
 Map 
 . 
 Entry<String 
 , 
  
 InstancesScopedList 
>  
 zoneInstances 
  
 : 
  
 response 
 . 
 iterateAll 
 ()) 
  
 { 
  
 // Instances scoped by each zone 
  
 String 
  
 zone 
  
 = 
  
 zoneInstances 
 . 
 getKey 
 (); 
  
 if 
  
 ( 
 ! 
 zoneInstances 
 . 
 getValue 
 (). 
 getInstancesList 
 (). 
 isEmpty 
 ()) 
  
 { 
  
 // zoneInstances.getKey() returns the fully qualified address. 
  
 // Hence, strip it to get the zone name only 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Instances at %s: " 
 , 
  
 zone 
 . 
 substring 
 ( 
 zone 
 . 
 lastIndexOf 
 ( 
 '/' 
 ) 
  
 + 
  
 1 
 )); 
  
 for 
  
 ( 
 Instance 
  
 instance 
  
 : 
  
 zoneInstances 
 . 
 getValue 
 (). 
 getInstancesList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 instance 
 . 
 getName 
 ()); 
  
 } 
  
 } 
  
 } 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "####### Listing all instances complete #######" 
 ); 
  
 return 
  
 response 
 ; 
  
 } 
  
 } 
 }

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 
  
 compute 
  
 = 
  
 require 
 ( 
 ' @google-cloud/compute 
' 
 ); 
 // List all instances in the specified project. 
 async 
  
 function 
  
 listAllInstances 
 () 
  
 { 
  
 const 
  
 instancesClient 
  
 = 
  
 new 
  
 compute 
 . 
  InstancesClient 
 
 (); 
  
 //Use the `maxResults` parameter to limit the number of results that the API returns per response page. 
  
 const 
  
 aggListRequest 
  
 = 
  
 instancesClient 
 . 
 aggregatedListAsync 
 ({ 
  
 project 
 : 
  
 projectId 
 , 
  
 maxResults 
 : 
  
 5 
 , 
  
 }); 
  
 console 
 . 
 log 
 ( 
 'Instances found:' 
 ); 
  
 // Despite using the `maxResults` parameter, you don't need to handle the pagination 
  
 // yourself. The returned object handles pagination automatically, 
  
 // requesting next pages as you iterate over the results. 
  
 for 
  
 await 
  
 ( 
 const 
  
 [ 
 zone 
 , 
  
 instancesObject 
 ] 
  
 of 
  
 aggListRequest 
 ) 
  
 { 
  
 const 
  
 instances 
  
 = 
  
 instancesObject 
 . 
 instances 
 ; 
  
 if 
  
 ( 
 instances 
 && 
 instances 
 . 
 length 
 > 
 0 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 ` 
 ${ 
 zone 
 } 
 ` 
 ); 
  
 for 
  
 ( 
 const 
  
 instance 
  
 of 
  
 instances 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 ` - 
 ${ 
 instance 
 . 
 name 
 } 
 ( 
 ${ 
 instance 
 . 
 machineType 
 } 
 )` 
 ); 
  
 } 
  
 } 
  
 } 
 } 
 listAllInstances 
 ();

PHP

Before trying this sample, follow the PHP setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine PHP 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 .

  use Google\Cloud\Compute\V1\AggregatedListInstancesRequest; 
 use Google\Cloud\Compute\V1\Client\InstancesClient; 
 /** 
 * List all instances for a particular Cloud project. 
 * 
 * @param string $projectId Your Google Cloud project ID. 
 * 
 * @throws \Google\ApiCore\ApiException if the remote call fails. 
 */ 
 function list_all_instances(string $projectId) 
 { 
 // List Compute Engine instances using InstancesClient. 
 $instancesClient = new InstancesClient(); 
 $request = (new AggregatedListInstancesRequest()) 
 ->setProject($projectId); 
 $allInstances = $instancesClient->aggregatedList($request); 
 printf('All instances for %s' . PHP_EOL, $projectId); 
 foreach ($allInstances as $zone => $zoneInstances) { 
 $instances = $zoneInstances->getInstances(); 
 if (count($instances) > 0) { 
 printf('Zone - %s' . PHP_EOL, $zone); 
 foreach ($instances as $instance) { 
 printf(' - %s' . PHP_EOL, $instance->getName()); 
 } 
 } 
 } 
 }

Python

Before trying this sample, follow the Python setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine Python 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 .

  from 
  
 __future__ 
  
 import 
 annotations 
 from 
  
 collections 
  
 import 
 defaultdict 
 from 
  
 collections.abc 
  
 import 
 Iterable 
 from 
  
 google.cloud 
  
 import 
 compute_v1 
 def 
  
 list_all_instances 
 ( 
 project_id 
 : 
 str 
 , 
 ) 
 - 
> dict 
 [ 
 str 
 , 
 Iterable 
 [ 
 compute_v1 
 . 
 Instance 
 ]]: 
  
 """ 
 Returns a dictionary of all instances present in a project, grouped by their zone. 
 Args: 
 project_id: project ID or project number of the Cloud project you want to use. 
 Returns: 
 A dictionary with zone names as keys (in form of "zones/{zone_name}") and 
 iterable collections of Instance objects as values. 
 """ 
 instance_client 
 = 
 compute_v1 
 . 
 InstancesClient 
 () 
 request 
 = 
 compute_v1 
 . 
 AggregatedListInstancesRequest 
 () 
 request 
 . 
 project 
 = 
 project_id 
 # Use the `max_results` parameter to limit the number of results that the API returns per response page. 
 request 
 . 
 max_results 
 = 
 50 
 agg_list 
 = 
 instance_client 
 . 
 aggregated_list 
 ( 
 request 
 = 
 request 
 ) 
 all_instances 
 = 
 defaultdict 
 ( 
 list 
 ) 
 print 
 ( 
 "Instances found:" 
 ) 
 # Despite using the `max_results` parameter, you don't need to handle the pagination 
 # yourself. The returned `AggregatedListPager` object handles pagination 
 # automatically, returning separated pages as you iterate over the results. 
 for 
 zone 
 , 
 response 
 in 
 agg_list 
 : 
 if 
 response 
 . 
 instances 
 : 
 all_instances 
 [ 
 zone 
 ] 
 . 
 extend 
 ( 
 response 
 . 
 instances 
 ) 
 print 
 ( 
 f 
 " 
 { 
 zone 
 } 
 :" 
 ) 
 for 
 instance 
 in 
 response 
 . 
 instances 
 : 
 print 
 ( 
 f 
 " - 
 { 
 instance 
 . 
 name 
 } 
 ( 
 { 
 instance 
 . 
 machine_type 
 } 
 )" 
 ) 
 return 
 all_instances

Ruby

Before trying this sample, follow the Ruby setup instructions in the Compute Engine quickstart using client libraries . For more information, see the Compute Engine Ruby 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 .

  require 
  
 "google/cloud/compute/v1" 
 # Returns a dictionary of all instances present in a project, grouped by their zone. 
 # 
 # @param [String] project project ID or project number of the Cloud project you want to use. 
 # @return [Hash<String, Array<::Google::Cloud::Compute::V1::Instance>>] A hash with zone names 
 #   as keys (in form of "zones/{zone_name}") and arrays of instances as values. 
 def 
  
 list_all_instances 
  
 project 
 : 
  
 # Initialize client that will be used to send requests. This client only needs to be created 
  
 # once, and can be reused for multiple requests. 
  
 client 
  
 = 
  
 :: 
 Google 
 :: 
 Cloud 
 :: 
 Compute 
 :: 
 V1 
 :: 
 Instances 
 :: 
 Rest 
 :: 
 Client 
 . 
 new 
  
 # Send the request to list all VM instances in a project. 
  
 agg_list 
  
 = 
  
 client 
 . 
 aggregated_list 
  
 project 
 : 
  
 project 
  
 all_instances 
  
 = 
  
 {} 
  
 puts 
  
 "Instances found:" 
  
 # The result contains a Map collection, where the key is a zone and the value 
  
 # is a collection of instances in that zone. 
  
 agg_list 
 . 
 each 
  
 do 
  
 | 
 zone 
 , 
  
 list 
 | 
  
 next 
  
 if 
  
 list 
 . 
 instances 
 . 
 empty? 
  
 all_instances 
 [ 
 zone 
 ] 
  
 = 
  
 list 
 . 
 instances 
  
 puts 
  
 " 
 #{ 
 zone 
 } 
 :" 
  
 list 
 . 
 instances 
 . 
 each 
  
 do 
  
 | 
 instance 
 | 
  
 puts 
  
 " - 
 #{ 
 instance 
 . 
 name 
 } 
 ( 
 #{ 
 instance 
 . 
 machine_type 
 } 
 )" 
  
 end 
  
 end 
  
 all_instances 
 end

What's next

To search and filter code samples for other Google Cloud products, see the Google Cloud sample browser .

List all VM instances Stay organized with collections Save and categorize content based on your preferences.

Explore further

Code sample

C#

Go

Java

Node.js

PHP

Python

Ruby

What's next

List all VM instances