Compute Engine client libraries

Stay organized with collections Save and categorize content based on your preferences.

This page shows how to get started with the Cloud Client Libraries for the Compute Engine API. Read more about the client libraries for Cloud APIs, including the older Google API Client Libraries, in Client Libraries Explained.


To follow step-by-step guidance for this task directly in the Google Cloud console, click Guide me:

Guide me


Install the client library

C#

For more information, see Setting Up a C# Development Environment.

Install the Google.Cloud.Compute.V1 package from NuGet.

Go

For more information, see Setting Up a Go Development Environment.

go get cloud.google.com/go/compute/apiv1

Java

For more information, see Setting Up a Java Development Environment.

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-compute</artifactId>
  <version>1.13.0</version>
</dependency>

If you are using Gradle, add the following to your dependencies:

implementation 'com.google.cloud:google-cloud-compute:1.15.0'

If you are using sbt, add the following to your dependencies:

libraryDependencies += "com.google.cloud" % "google-cloud-compute" % "1.15.0"

The older version of the Cloud Client Libraries for Java for Compute Engine is available as version 0.120.x or earlier in the Maven artifact. Versions 0.120.x and earlier of this library are forward-incompatible with later versions.

Node.js

For more information, see Setting Up a Node.js Development Environment.

npm install @google-cloud/compute

The older version of the Cloud Client Libraries for Node.js for Compute Engine is available as version 2.5.x or earlier in the npm package. Versions 2.5.x and earlier of this library are forward-incompatible with later versions.

PHP

For more information, see Using PHP on Google Cloud.

composer require google/cloud-compute

Python

For more information, see Setting Up a Python Development Environment.

pip install --upgrade google-cloud-compute

Ruby

For more information, see Setting Up a Ruby Development Environment.

gem install google-cloud-compute-v1

Set up authentication

When you use client libraries, you use Application Default Credentials (ADC) to authenticate. For information about setting up ADC, see Provide credentials for Application Default Credentials. For information about using ADC with client libraries, see Authenticate using client libraries.

Use the client library

The following example shows how to use the client library to list instances in a particular zone. For more examples, see Using client libraries.

C#

For more information, see the Compute Engine C# API reference documentation.


using Google.Cloud.Compute.V1;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class ListZoneInstancesAsyncSample
{
    public async Task<IList<Instance>> ListZoneInstancesAsync(
        // TODO(developer): Set your own default values for these parameters or pass different values when calling this method.
        string projectId = "your-project-id", 
        string zone = "us-central1-a")
    {
        // 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 the given zone in the specified project.
        await foreach(var instance in client.ListAsync(projectId, zone))
        {
            // The result is an Instance collection.
            Console.WriteLine($"Instance: {instance.Name}");
            allInstances.Add(instance);
        }

        return allInstances;
    }
}

Go

For more information, see the Compute Engine Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	"google.golang.org/api/iterator"
	computepb "google.golang.org/genproto/googleapis/cloud/compute/v1"
)

// listInstances prints a list of instances created in given project in given zone.
func listInstances(w io.Writer, projectID, zone string) error {
	// projectID := "your_project_id"
	// zone := "europe-central2-b"
	ctx := context.Background()
	instancesClient, err := compute.NewInstancesRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewInstancesRESTClient: %v", err)
	}
	defer instancesClient.Close()

	req := &computepb.ListInstancesRequest{
		Project: projectID,
		Zone:    zone,
	}

	it := instancesClient.List(ctx, req)
	fmt.Fprintf(w, "Instances found in zone %s:\n", zone)
	for {
		instance, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "- %s %s\n", instance.GetName(), instance.GetMachineType())
	}
	return nil
}

Java

For more information, see the Compute Engine Java API reference documentation.


import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.InstancesClient;
import java.io.IOException;

public class ListInstance {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample
    String project = "your-project-id";
    String zone = "zone-name";
    listInstances(project, zone);
  }

  // List all instances in the given zone in the specified project ID.
  public static void listInstances(String project, String zone) 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()) {
      // Set the project and zone to retrieve instances present in the zone.
      System.out.printf("Listing instances from %s in %s:", project, zone);
      for (Instance zoneInstance : instancesClient.list(project, zone).iterateAll()) {
        System.out.println(zoneInstance.getName());
      }
      System.out.println("####### Listing instances complete #######");
    }
  }
}

Node.js

For more information, see the Compute Engine Node.js API reference documentation.

/**
 * TODO(developer): Uncomment and replace these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const zone = 'europe-central2-b'

const compute = require('@google-cloud/compute');

// List all instances in the given zone in the specified project.
async function listInstances() {
  const instancesClient = new compute.InstancesClient();

  const [instanceList] = await instancesClient.list({
    project: projectId,
    zone,
  });

  console.log(`Instances found in zone ${zone}:`);

  for (const instance of instanceList) {
    console.log(` - ${instance.name} (${instance.machineType})`);
  }
}

listInstances();

PHP

For more information, see the Compute Engine PHP API reference documentation.

use Google\Cloud\Compute\V1\InstancesClient;

/**
 * List all instances for a particular Cloud project and zone.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $zone Zone to list instances for (like "us-central1-a").
 *
 * @throws \Google\ApiCore\ApiException if the remote call fails.
 */
function list_instances(string $projectId, string $zone)
{
    // List Compute Engine instances using InstancesClient.
    $instancesClient = new InstancesClient();
    $instancesList = $instancesClient->list($projectId, $zone);

    printf('Instances for %s (%s)' . PHP_EOL, $projectId, $zone);
    foreach ($instancesList as $instance) {
        printf(' - %s' . PHP_EOL, $instance->getName());
    }
}

Python

For more information, see the Compute Engine Python API reference documentation.

from typing import Iterable

from google.cloud import compute_v1


def list_instances(project_id: str, zone: str) -> Iterable[compute_v1.Instance]:
    """
    List all instances in the given zone in the specified project.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone you want to use. For example: “us-west3-b”
    Returns:
        An iterable collection of Instance objects.
    """
    instance_client = compute_v1.InstancesClient()
    instance_list = instance_client.list(project=project_id, zone=zone)

    print(f"Instances found in zone {zone}:")
    for instance in instance_list:
        print(f" - {instance.name} ({instance.machine_type})")

    return instance_list

Ruby

For more information, see the Compute Engine Ruby API reference documentation.


require "google/cloud/compute/v1"

# Lists all instances in the given zone in the specified project.
#
# @param [String] project project ID or project number of the Cloud project you want to use.
# @param [String] zone name of the zone you want to use. For example: "us-west3-b"
# @return [Array<::Google::Cloud::Compute::V1::Instance>] Array of instances.
def list_instances project:, zone:
  # 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 the given zone in the specified project.
  instance_list = client.list project: project, zone: zone

  puts "Instances found in zone #{zone}:"
  instances = []
  instance_list.each do |instance|
    puts " - #{instance.name} (#{instance.machine_type})"
    instances << instance
  end
  instances
end

Additional resources

Older client libraries

Cloud Client Libraries use our latest client library model and are the recommended option for accessing Cloud APIs programmatically.

For cases where you can't use Cloud Client Libraries, the following Google API Client Libraries are available:

Language Library Resources
Go Google API Go Client Library Documentation
Java Google API Java Client Library Documentation
JavaScript Google API JavaScript Client Library Documentation
.NET Google API .NET Client Library Documentation
Node.js Google API Node.js Client Library Documentation
Objective-C Google API Objective-C Client Library Documentation
PHP Google API PHP Client Library Documentation
Python Google API Python Client Library Documentation
Ruby Google API Ruby Client Library Documentation
Dart Google API Dart Client Library Documentation

Third-party Compute Engine API client libraries

libcloud

libcloud is a Python library used for interacting with multiple cloud service providers through a single unified API.

The Apache libcloud API project has received support and updates for Compute Engine since July 2013. It supports a broad set of Compute Engine features including instances, disks, networks, and load balancers. The getting started demo provides a code example of how to use libcloud and Compute Engine together.

jclouds

jclouds is an open source library that allows you to use Java and Clojure across multiple Cloud providers.

The jclouds cloud API supports Compute Engine and lets you manage resources such as virtual machines, disks, and networks. As of version 1.9, Compute Engine was promoted to the jclouds core.

fog.io

fog.io is an open source Ruby library that lets you interact with multiple cloud services through one API.

The fog.io cloud API has had support for Compute Engine since version 1.11.0 in May 2013. It supports instance operations such as create and delete, along with management operations for other resources like disks, networks, and load balancers.