This document demonstrates how to use the Cloud Client Libraries for Python for Compute Engine. It describes how to authorize requests and how to create, list, and delete instances. This exercise discusses how to use the google-api-python-client library to access Compute Engine resources. You can run this sample from your local machine or on a VM instance, provided that you have authorized the sample correctly.
For a full list of available client libraries, including other Google client libraries and third-party open source libraries, see the client libraries page.
To view the full code example with all of the necessary imports, visit the GoogleCloudPlatform/python-docs-samples GitHub page.
Objectives
- Perform OAuth 2.0 authorization using the oauth2client library
- Create an instance using the google-python-client library
- List instances using the google-python-client library
- Delete an instance using the google-python-client library
Costs
This tutorial uses billable components of Google Cloud including Compute Engine.
New Google Cloud users might be eligible for a free trial.Before you begin
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Install the Cloud SDK.
- After the SDK is installed, run
gcloud auth application-default login
. - Install the
google-api-python-client
library. Typically, you can run:
$ pip install --upgrade google-api-python-client
For more information about how to install this library, see the installation instructions. You also need to have Python 2.7 or 3.3+ to run the Cloud Client Libraries for Python.
- Enable the Cloud Storage API.
- Create a Cloud Storage bucket and note the bucket name for later.
Authorizing requests
This sample uses OAuth 2.0 authorization. There are many ways to authorize
requests using OAuth 2.0, but for the example use
application default credentials.
This lets you reuse the credentials from the gcloud
tool if you are
running the sample on a local workstation or reuse credentials from a service
account if you are running the sample from within Compute Engine
or App Engine. You should have installed and authorized the gcloud
tool in
the Before you begin section.
Application default credentials are provided in Google API Client Libraries automatically. You just have to build and initialize the API:
compute = googleapiclient.discovery.build('compute', 'v1')
For example, the following snippet is the main method of this sample, which builds and initializes the API and then makes some calls to create, list, and delete an instance:
Listing instances
Using the Cloud Client Libraries for Python, you can list instances by using the
compute.instances().list
method. You need to provide the project ID and
the zone for which you want to list instances. For example:
Adding an instance
To add an instance, use the instances().insert
method and specify the
properties of the new instance. These properties are specified in the request
body; for details about each property
see the API reference for instances.insert
.
At a minimum, your request must provide values for the following properties when you create a new instance:
- Instance name
- Root persistent disk
- Machine type
- Zone
- Network Interfaces
This sample starts an instance with the following properties in a zone of your choice:
- Machine type: e2-standard-2
- Root persistent disk: a new persistent disk based on the latest Debian 8 image
The Compute Engine default service account with the following scopes:
https://www.googleapis.com/auth/devstorage.read_write
, so the instance can read and write files in Cloud Storagehttps://www.googleapis.com/auth/logging.write
, so the instances logs can upload to Cloud Logging
Metadata to specify commands that the instance should execute upon startup
The following sections describe the instance creation parameters.
Root persistent disks
All instances must boot from a root persistent disk. The root persistent disk contains all of the necessary files required for starting an instance. When you create a root persistent disk you must select a public image or a custom image to apply to the disk. In the example above, you created a new root persistent disk based on Debian 8 at the same time as the instance. However, it is also possible to create a disk beforehand and attach it to the instance.
Instance metadata
When you create your instance, you might want to include instance metadata
such as a startup script, configuration variables,
and SSH keys. In the example above, you used the metadata
field in your
request body to specify a startup script for the
instance and some configuration variables as key/values pairs. The startup
script, listed below, shows how to read these variables and use them to apply
text to an image and upload it to Cloud Storage.
Deleting an Instance
To delete an instance, you need to call the instances().delete
method
and provide the name, zone, and project ID of the instance to delete. Because
you set the autoDelete
parameter for the boot disk it is also deleted
when the instance is deleted. This setting is off by default but is useful when
your use case calls for disks and instances to be deleted together.
Running the sample
You can run the full sample by downloading the code and running it on the
command line. Make sure to download the create_instance.py
file and the
startup-script.sh
file. To run the sample:
python create_instance.py --name [INSTANCE_NAME] --zone [ZONE] [PROJECT_ID] [CLOUD_STORAGE_BUCKET]
where:
[INSTANCE_NAME]
is the name of the instance to create.[ZONE]
is the desired zone for this request.[PROJECT_ID]
is our project ID.[CLOUD_STORAGE_BUCKET]
is the name of the bucket you initially set up but without thegs://
prefix.
For example:
python python-example.py --name example-instance --zone us-central1-a example-project my-gcs-bucket
Waiting for operations to complete
Requests to the Compute Engine API that modify resources such as instances immediately return a response acknowledging your request. The acknowledgement lets you check the status of the requested operation. Operations can take a few minutes to complete, so it's often easier to wait for the operation to complete before continuing. This helper method waits until the operation completes before returning:
Cleaning up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.
Delete your Cloud Storage bucket
To delete a Cloud Storage bucket:
- In the Cloud Console, go to the Cloud Storage Browser page.
- Click the checkbox for the bucket you want to delete.
- To delete the bucket, click Delete delete.
What's next
- Download and view the full code sample. The full sample includes a small example of using all of these methods together. Feel free to download it, change it, and run it to suit your needs.
- Review the API reference to learn how to perform other tasks with the API.