Google Compute Engine Driver Documentation

Google Compute Engine gives users the ability to run large-scale workloads on virtual machines hosted on Google’s infrastructure. It is a part of Google Cloud Platform.

Google Compute Engine features:

High-performance virtual machines
Minute-level billing (10-minute minimum)
Fast VM provisioning
Persistent block storage (SSD and standard)
Native Load Balancing

Connecting to Google Compute Engine

Libcloud supports three different methods for authenticating: Service Account, Installed Application and Internal Authentication.

Which one should I use?

Service Accounts are generally better suited for automated systems, cron jobs, etc. They should be used when access to the application/script is limited and needs to be able to run with limited intervention.
Installed Application authentication is often the better choice when creating an application that may be used by third-parties interactively. For example, a desktop application for managing VMs that would be used by many different people with different Google accounts.
If you are running your code on an instance inside Google Compute Engine, the GCE driver will consult the internal metadata service to obtain an authorization token. The only value required for this type of authorization is your Project ID.

Once you have set up the authentication as described below, you pass the authentication information to the driver as described in Examples. Also bear in mind that large clock drift (difference in time) between authenticating host and google will cause authentication to fail.

Service Account

To set up Service Account authentication, you will need to download the corresponding private key file in either the new JSON (preferred) format, or the legacy P12 format.

Go to Google Cloud Console (https://console.cloud.google.com/) and create a new project (https://console.cloud.google.com/projectcreate) or re-use an existing one.

../../_images/create_service_account.png

Select the existing or newly created project and go to IAM & Admin -> Service Accounts -> Create service account to create a new service account. Select “Furnish a new private key” to create and download new private key you will use to authenticate.
1. If you opt for the new preferred JSON format, download the file and save it to a secure location.
2. If you opt to use the legacy P12 format:
  
  Convert the private key to a .pem file using the following: openssl pkcs12 -in YOURPRIVKEY.p12 -nodes -nocerts | openssl rsa -out PRIV.pem
  
  Move the .pem file to a safe location

You will need the Service Account’s “Email Address” and the path to the key file for authentication.

You will also need your “Project ID” (a string, not a numerical value) that can be found by clicking on the “Overview” link on the left sidebar.

You will also need to have billing information associated and enabled for that project. If billing is not yet enabled for that project an error message similar to the one below will be printed when you first run the code which uses GCE driver:

libcloud.common.google.GoogleBaseError: {u'domain': u'usageLimits', u'message': u'Access Not Configured. Compute Engine API has not been used in project 1029894677594 before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/compute.googleapis.com/overview?project=1029894677594 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.', u'reason': u'accessNotConfigured', u'extendedHelp': u'https://console.developers.google.com/apis/api/compute.googleapis.com/overview?project=YYYYYYYY'}

You can simply follow the link in the error message to configure and enable billing.

Installed Application

To set up Installed Account authentication:

Go to the Google Developers Console
Select your project
In the left sidebar, go to “APIs & auth”
Click on “Credentials” then “Create New Client ID”
Select “Installed application” and “Other” then click “Create Client ID”
For authentication, you will need the “Client ID” and the “Client Secret”
You will also need your “Project ID” (a string, not a numerical value) that can be found by clicking on the “Overview” link on the left sidebar.

Internal Authentication

To use GCE’s internal metadata service to authenticate, simply specify your Project ID and let the driver handle the rest. See the 5. Using GCE Internal Authorization example below.

Accessing Google Cloud services from your Libcloud nodes

In order for nodes created with libcloud to be able to access or manage other Google Cloud Platform services, you will need to specify a list of Service Account Scopes. By default libcloud will create nodes that only allow read-only access to Google Cloud Storage. A few of the examples below illustrate how to use Service Account Scopes.

Examples

Keep in mind that a lot of the driver methods depend on the zone / location being set.

For that reason, you are advised to pass datacenter argument to the driver constructor. This value should contain a name of the zone where you want your operations to be performed (e.g. us-east1-b).

Some of the methods allow this value to be overridden on per method invocation basis - either by specifying zone or location method argument.

Additional example code can be found in the “demos” directory of Libcloud here: https://github.com/apache/libcloud/blob/trunk/demos/gce_demo.py

1. Getting Driver with Service Account authentication

With local key file:

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

ComputeEngine = get_driver(Provider.GCE)
# Note that the 'PEM file' argument can either be the JSON format or
# the P12 format.
driver = ComputeEngine(
    "your_service_account_email",
    "path_to_pem_file",
    project="your_project_id",
    datacenter="us-central1-a",
)

With Service Account credentials as dict:

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

credentials = {
    "type": "service_account",
    "project_id": "my_project",
    "private_key": "-----BEGIN PRIVATE KEY-----\nmy_private_key_data\n"
    "-----END PRIVATE KEY-----\n",
    "client_email": "my_email",
}

ComputeEngine = get_driver(Provider.GCE)
driver = ComputeEngine("your_service_account_email", credentials, project="your_project_id")

2. Getting Driver with Installed Application authentication

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

ComputeEngine = get_driver(Provider.GCE)
driver = ComputeEngine(
    "your_client_id",
    "your_client_secret",
    datacenter="us-central1-a",
    project="your_project_id",
)

3. Getting Driver using a default Datacenter (Zone)

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

ComputeEngine = get_driver(Provider.GCE)
# Datacenter is set to 'us-central1-a' as an example, but can be set to any
# zone, like 'us-central1-b' or 'europe-west1-a'
driver = ComputeEngine(
    "your_service_account_email",
    "path_to_pem_file",
    datacenter="us-central1-a",
    project="your_project_id",
)

4. Specifying Service Account Scopes

# See previous examples for connecting and creating the driver
# ...
driver = None

# Define common example attributes
s = "n1-standard-1"
i = "debian-7"
z = "us-central1-a"

# Service Account Scopes require a list of dictionaries. Each dictionary
# can have an optional 'email' address specifying the Service Account
# address, and list of 'scopes'. The default Service Account Scopes for
# new nodes will effectively use:

sa_scopes = [{"email": "default", "scopes": ["storage-ro"]}]

# The expected scenario will likely use the default Service Account email
# address, but allow users to override the default list of scopes.
# For example, create a new node with full access to Google Cloud Storage
# and Google Compute Engine:
sa_scopes = [{"scopes": ["compute", "storage-full"]}]
node_1 = driver.create_node("n1", s, i, z, ex_service_accounts=sa_scopes)

# See Google's documentation for Accessing other Google Cloud services from
# your Google Compute Engine instances at,
# https://cloud.google.com/compute/docs/authentication

5. Using GCE Internal Authorization

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

# This example assumes you are running on an instance within Google
# Compute Engine. As such, the only value you need to specify is
# the Project ID. The GCE driver will the consult GCE's internal
# metadata service for an authorization token.
#
# You must still place placeholder empty strings for user_id / key
# due to the nature of the driver's __init__() params.
ComputeEngine = get_driver(Provider.GCE)
driver = ComputeEngine("", "", project="your_project_id", datacenter="us-central1-a")

6. Using deploy_node() functionality

import os

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
from libcloud.compute.deployment import ScriptDeployment

# Path to the private SSH key file used to authenticate
PRIVATE_SSH_KEY_PATH = os.path.expanduser("~/.ssh/id_rsa_gce")

# Path to the public SSH key file which will be installed on the server for
# the root user
PUBLIC_SSH_KEY_PATH = os.path.expanduser("~/.ssh/id_rsa_gce.pub")

with open(PUBLIC_SSH_KEY_PATH) as fp:
    PUBLIC_SSH_KEY_CONTENT = fp.read().strip()

# GCE authentication related info
SERVICE_ACCOUNT_USERNAME = "<username>@<project id>.iam.gserviceaccount.com"
SERVICE_ACCOUNT_CREDENTIALS_JSON_FILE_PATH = "/path/to/sac.json"

PROJECT_ID = "my-gcp-project"

Driver = get_driver(Provider.GCE)
driver = Driver(
    SERVICE_ACCOUNT_USERNAME,
    SERVICE_ACCOUNT_CREDENTIALS_JSON_FILE_PATH,
    project=PROJECT_ID,
    datacenter="us-central1-a",
)

step = ScriptDeployment("echo whoami ; date ; ls -la")

images = driver.list_images()
sizes = driver.list_sizes()

image = [i for i in images if i.name == "ubuntu-1604-xenial-v20191217"][0]
size = [s for s in sizes if s.name == "e2-micro"][0]

print("Using image: %s" % (image))
print("Using size: %s" % (size))

# NOTE: We specify which public key is installed on the instance using
# metadata functionality.
# Keep in mind that this step is only needed if you want to install a specific
# key which is used to run the deployment script.
# If you are using a VM image with a public SSH key already pre-baked in or if
# you use project wide ssh-keys GCP functionality, you can remove ex_metadata
# argument, but you still need to make sure the private key you use inside this
# script matches the one which is installed / available on the server.
ex_metadata = metadata = {
    "items": [{"key": "ssh-keys", "value": "root: %s" % (PUBLIC_SSH_KEY_CONTENT)}]
}

# deploy_node takes the same base keyword arguments as create_node.
node = driver.deploy_node(
    name="libcloud-deploy-demo-1",
    image=image,
    size=size,
    ex_metadata=metadata,
    deploy=step,
    ssh_key=PRIVATE_SSH_KEY_PATH,
)

print("")
print("Node: %s" % (node))
print("")
print("stdout: %s" % (step.stdout))
print("stderr: %s" % (step.stderr))
print("exit_code: %s" % (step.exit_status))

API Docs

class libcloud.compute.drivers.gce.GCENodeDriver(user_id, key=None, datacenter=None, project=None, auth_type=None, scopes=None, credential_file=None, **kwargs)[source]

GCE Node Driver class.

This is the primary driver for interacting with Google Compute Engine. It contains all of the standard libcloud methods, plus additional ex_* methods for more features.

Note that many methods allow either objects or strings (or lists of objects/strings). In most cases, passing strings instead of objects will result in additional GCE API calls.

Parameters:

user_id (str) – The email address (for service accounts) or Client ID (for installed apps) to be used for authentication.
key (str) – The RSA Key (for service accounts) or file path containing key or Client Secret (for installed apps) to be used for authentication.
datacenter (str) – The name of the datacenter (zone) used for operations.
project (str) – Your GCE project name. (required)
auth_type (str) – Accepted values are “SA” or “IA” or “GCE” (“Service Account” or “Installed Application” or “GCE” if libcloud is being used on a GCE instance with service account enabled). If not supplied, auth_type will be guessed based on value of user_id or if the code is being executed in a GCE instance.
scopes (list) – List of authorization URLs. Default is empty and grants read/write to Compute, Storage, DNS.
credential_file (str) – Path to file for caching authentication information used by GCEConnection.

attach_volume(node, volume, device=None, ex_mode=None, ex_boot=False, ex_type=None, ex_source=None, ex_auto_delete=None, ex_initialize_params=None, ex_licenses=None, ex_interface=None)[source]

Attach a volume to a node.

If volume is None, an ex_source URL must be provided.

Parameters:

node (Node or None) – The node to attach the volume to
volume (StorageVolume or None) – The volume to attach.
device (str) – The device name to attach the volume as. Defaults to volume name.
ex_mode (str) – Either ‘READ_WRITE’ or ‘READ_ONLY’
ex_boot (bool) – If true, disk will be attached as a boot disk
ex_type (str) – Specify either ‘PERSISTENT’ (default) or ‘SCRATCH’.
ex_source (str or None) – URL (full or partial) of disk source. Must be present if not using an existing StorageVolume.
ex_auto_delete (bool or None) – If set, the disk will be auto-deleted if the parent node/instance is deleted.
ex_initialize_params (dict or None) – Allow user to pass in full JSON struct of initializeParams as documented in GCE’s API.
ex_licenses (list of str) – List of strings representing licenses associated with the volume/disk.
ex_interface (str or None) – User can specify either ‘SCSI’ (default) or ‘NVME’.

Returns:

True if successful

Return type:

bool

connectionCls: alias of GCEConnection

copy_image(source_region: str, node_image: NodeImage, name: str, description: str | None = None) → NodeImage

Copies an image from a source region to the current region.

Parameters:

source_region (str) – Region to copy the node from.
node_image (NodeImage:) – NodeImage to copy.
name (str) – name for new image.
description – description for new image.

Return type:

NodeImage:

Returns:

NodeImage instance on success.

create_image(node: Node, name: str, description: str | None = None) → List[NodeImage]

Creates an image from a node object.

Parameters:

node (Node) – Node to run the task on.
name (description) – name for new image.
description – description for new image.

Return type:

NodeImage:

Returns:

NodeImage instance on success.

create_key_pair(name: str) → KeyPair

Create a new key pair object.

Parameters:: name (str) – Key pair name.
Return type:: KeyPair object

create_node(name, size, image, location=None, ex_network='default', ex_subnetwork=None, ex_tags=None, ex_metadata=None, ex_boot_disk=None, use_existing_disk=True, external_ip='ephemeral', internal_ip=None, ex_disk_type='pd-standard', ex_disk_auto_delete=True, ex_service_accounts=None, description=None, ex_can_ip_forward=None, ex_disks_gce_struct=None, ex_nic_gce_struct=None, ex_on_host_maintenance=None, ex_automatic_restart=None, ex_preemptible=None, ex_image_family=None, ex_labels=None, ex_accelerator_type=None, ex_accelerator_count=None, ex_disk_size=None)[source]

Create a new node and return a node object for the node.

Parameters:

name (str) – The name of the node to create.
size (str or GCENodeSize) – The machine type to use.
image (str or GCENodeImage or None) – The image to use to create the node (or, if attaching a persistent disk, the image used to create the disk)
location (str or NodeLocation or GCEZone or None) – The location (zone) to create the node in.
ex_network (str or GCENetwork) – The network to associate with the node.
ex_subnetwork (str or GCESubnetwork) – The subnetwork to associate with the node.
ex_tags (list of str or None) – A list of tags to associate with the node.
ex_metadata (dict or None) – Metadata dictionary for instance.
ex_boot_disk (StorageVolume or str or None) – The boot disk to attach to the instance.
use_existing_disk (bool) – If True and if an existing disk with the same name/location is found, use that disk instead of creating a new one.
external_ip (GCEAddress or str or None) – The external IP address to use. If ‘ephemeral’ (default), a new non-static address will be used. If ‘None’, then no external address will be used. To use an existing static IP address, a GCEAddress object should be passed in.
internal_ip (GCEAddress or str or None) – The private IP address to use.
ex_disk_type (str or GCEDiskType) – Specify a pd-standard (default) disk or pd-ssd for an SSD disk.
ex_disk_auto_delete (bool) – Indicate that the boot disk should be deleted when the Node is deleted. Set to True by default.
ex_service_accounts (list) – Specify a list of serviceAccounts when creating the instance. The format is a list of dictionaries containing email and list of scopes, e.g. [{‘email’:’default’, ‘scopes’:[‘compute’, …]}, …] Scopes can either be full URLs or short names. If not provided, use the ‘default’ service account email and a scope of ‘devstorage.read_only’. Also accepts the aliases defined in ‘gcloud compute’.
description (str or None) – The description of the node (instance).
ex_can_ip_forward (bool or None) – Set to True to allow this node to send/receive non-matching src/dst packets.
ex_disks_gce_struct (list or None) – Support for passing in the GCE-specific formatted disks[] structure. No attempt is made to ensure proper formatting of the disks[] structure. Using this structure obviates the need of using other disk params like ‘ex_boot_disk’, etc. See the GCE docs for specific details.
ex_nic_gce_struct (list or None) – Support passing in the GCE-specific formatted networkInterfaces[] structure. No attempt is made to ensure proper formatting of the networkInterfaces[] data. Using this structure obviates the need of using ‘external_ip’ and ‘ex_network’. See the GCE docs for details.
ex_on_host_maintenance (str or None) – Defines whether node should be terminated or migrated when host machine goes down. Acceptable values are: ‘MIGRATE’ or ‘TERMINATE’ (If not supplied, value will be reset to GCE default value for the instance type.)
ex_automatic_restart (bool or None) – Defines whether the instance should be automatically restarted when it is terminated by Compute Engine. (If not supplied, value will be set to the GCE default value for the instance type.)
ex_preemptible (bool or None) – Defines whether the instance is preemptible. (If not supplied, the instance will not be preemptible)
ex_image_family (str or None) – Determine image from an ‘Image Family’ instead of by name. ‘image’ should be None to use this keyword.
ex_labels (dict or None) – Labels dictionary for instance.
ex_accelerator_type (str or None) – Defines the accelerator to use with this node. Must set ‘ex_on_host_maintenance’ to ‘TERMINATE’. Must include a count of accelerators to use in ‘ex_accelerator_count’.
ex_accelerator_count (int or None) – The number of ‘ex_accelerator_type’ accelerators to attach to the node.
ex_disk_size (int or None) – Defines size of the boot disk. Integer in gigabytes.

Returns:

A Node object for the new node.

Return type:

Node

create_volume(size, name, location=None, snapshot=None, image=None, use_existing=True, ex_disk_type='pd-standard', ex_image_family=None)[source]

Create a volume (disk).

Parameters:

size (int or str or None) – Size of volume to create (in GB). Can be None if image or snapshot is supplied.
name (str) – Name of volume to create
location (str or GCEZone or NodeLocation or None) – Location (zone) to create the volume in
snapshot (GCESnapshot or str or None) – Snapshot to create image from
image (GCENodeImage or str or None) – Image to create disk from.
use_existing (bool) – If True and a disk with the given name already exists, return an object for that disk instead of attempting to create a new disk.
ex_disk_type (str or GCEDiskType) – Specify a pd-standard (default) disk or pd-ssd for an SSD disk.
ex_image_family (str or None) – Determine image from an ‘Image Family’ instead of by name. ‘image’ should be None to use this keyword.

Returns:

Storage Volume object

Return type:

StorageVolume

create_volume_snapshot(volume, name)[source]

Create a snapshot of the provided Volume.

Parameters:: volume (StorageVolume) – A StorageVolume object
Returns:: A GCE Snapshot object
Return type:: GCESnapshot

delete_image(node_image: NodeImage) → bool

Deletes a node image from a provider.

Parameters:: node_image (NodeImage) – Node image object.
Returns:: True if delete_image was successful, False otherwise.
Return type:: bool

delete_key_pair(key_pair: KeyPair) → bool

Delete an existing key pair.

Parameters:: key_pair (KeyPair) – Key pair object.
Return type:: bool

deploy_node(deploy: Deployment, ssh_username: str = 'root', ssh_alternate_usernames: List[str] | None = None, ssh_port: int = 22, ssh_timeout: int = 10, ssh_key: T_Ssh_key | None = None, ssh_key_password: str | None = None, auth: T_Auth | None = None, timeout: int = 300, max_tries: int = 3, ssh_interface: str = 'public_ips', at_exit_func: Callable | None = None, wait_period: int = 5, **create_node_kwargs) → Node

Create a new node, and start deployment.

In order to be able to SSH into a created node access credentials are required.

A user can pass either a NodeAuthPassword or NodeAuthSSHKey to the auth argument. If the create_node implementation supports that kind if credential (as declared in self.features['create_node']) then it is passed on to create_node. Otherwise it is not passed on to create_node and it is only used for authentication.

If the auth parameter is not supplied but the driver declares it supports generates_password then the password returned by create_node will be used to SSH into the server.

Finally, if the ssh_key_file is supplied that key will be used to SSH into the server.

This function may raise a DeploymentException, if a create_node call was successful, but there is a later error (like SSH failing or timing out). This exception includes a Node object which you may want to destroy if incomplete deployments are not desirable.

>>> from libcloud.compute.drivers.dummy import DummyNodeDriver
>>> from libcloud.compute.deployment import ScriptDeployment
>>> from libcloud.compute.deployment import MultiStepDeployment
>>> from libcloud.compute.base import NodeAuthSSHKey
>>> driver = DummyNodeDriver(0)
>>> key = NodeAuthSSHKey('...') # read from file
>>> script = ScriptDeployment("yum -y install emacs strace tcpdump")
>>> msd = MultiStepDeployment([key, script])
>>> def d():
...     try:
...         driver.deploy_node(deploy=msd)
...     except NotImplementedError:
...         print ("not implemented for dummy driver")
>>> d()
not implemented for dummy driver

Deploy node is typically not overridden in subclasses. The existing implementation should be able to handle most such.

Parameters:

deploy (Deployment) – Deployment to run once machine is online and available to SSH.
ssh_username (str) – Optional name of the account which is used when connecting to SSH server (default is root)
ssh_alternate_usernames (list) – Optional list of ssh usernames to try to connect with if using the default one fails
ssh_port (int) – Optional SSH server port (default is 22)
ssh_timeout (float) – Optional SSH connection timeout in seconds (default is 10)
auth (NodeAuthSSHKey or NodeAuthPassword) – Initial authentication information for the node (optional)
ssh_key (str or list of str) – A path (or paths) to an SSH private key with which to attempt to authenticate. (optional)
ssh_key_password (str) – Optional password used for encrypted keys.
timeout (int) – How many seconds to wait before timing out. (default is 600)
max_tries (int) – How many times to retry if a deployment fails before giving up (default is 3)
ssh_interface (str) – The interface to wait for. Default is ‘public_ips’, other option is ‘private_ips’.
at_exit_func (func) –
Optional atexit handler function which will be registered and called with created node if user cancels the deploy process (e.g. CTRL+C), after the node has been created, but before the deploy process has finished.

This method gets passed in two keyword arguments:
- driver -> node driver in question
- node -> created Node object
Keep in mind that this function will only be called in such scenario. In case the method finishes (this includes throwing an exception), at exit handler function won’t be called.
wait_period (int) – How many seconds to wait between each iteration while waiting for node to transition into running state and have IP assigned. (default is 5)

destroy_node(node, destroy_boot_disk=False, ex_sync=True)[source]

Destroy a node.

Parameters:

node (Node) – Node object to destroy
destroy_boot_disk (bool) – If true, also destroy the node’s boot disk. (Note that this keyword is not accessible from the node’s .destroy() method.)
ex_sync (bool) – If true, do not return until destroyed or timeout

Returns:

True if successful

Return type:

bool

destroy_volume(volume)[source]

Destroy a volume.

Parameters:: volume (StorageVolume) – Volume object to destroy
Returns:: True if successful
Return type:: bool

destroy_volume_snapshot(snapshot)[source]

Destroy a snapshot.

Parameters:: snapshot (GCESnapshot) – Snapshot object to destroy
Returns:: True if successful
Return type:: bool

detach_volume(volume, ex_node=None)[source]

Detach a volume from a node.

Parameters:

volume (StorageVolume) – Volume object to detach
ex_node (Node) – Node object to detach volume from (required)

Returns:

True if successful

Return type:

bool

ex_add_access_config(node, name, nic, nat_ip=None, config_type=None)[source]

Add a network interface access configuration to a node.

Parameters:

node (str) – The existing target Node (instance) that will receive the new access config.
name – Name of the new access config.
nat_ip (str or None) – The external existing static IP Address to use for the access config. If not provided, an ephemeral IP address will be allocated.
config_type (str or None) – The type of access config to create. Currently the only supported type is ‘ONE_TO_ONE_NAT’.

Returns:

True if successful

Return type:

bool

ex_copy_image(name, url, description=None, family=None, guest_os_features=None)[source]

Copy an image to your image collection.

Parameters:

name (str) – The name of the image
url (str) – The URL to the image. The URL can start with gs://
description (str) – The description of the image
family (str) – The family of the image
guest_os_features (list of str or None) – The features of the guest operating system.

Returns:

NodeImage object based on provided information or None if an image with that name is not found.

Return type:

NodeImage or None

ex_create_address(name, region=None, address=None, description=None, address_type='EXTERNAL', subnetwork=None)[source]

Create a static address in a region, or a global address.

Parameters:

name (str) – Name of static address
region (str or GCERegion) – Name of region for the address (e.g. ‘us-central1’) Use ‘global’ to create a global address.
address (str or None) – Ephemeral IP address to promote to a static one (e.g. ‘xxx.xxx.xxx.xxx’)
description (str) – Optional descriptive comment.
address_type – Optional The type of address to reserve, either INTERNAL or EXTERNAL. If unspecified, defaults to EXTERNAL.
subnetwork – Optional The URL of the subnetwork in which to reserve the address. If an IP address is specified, it must be within the subnetwork’s IP range. This field can only be used with INTERNAL type with GCE_ENDPOINT/DNS_RESOLVER purposes.

Returns:

Static Address object

Return type:

GCEAddress

ex_create_autoscaler(name, zone, instance_group, policy, description=None)[source]

Create an Autoscaler for an Instance Group.

Parameters:

name (str) – The name of the Autoscaler
zone (str or GCEZone) – The zone to which the Instance Group belongs
instance_group – An Instance Group Manager object.
policy – A dict containing policy configuration. See the API documentation for Autoscalers for more details.

Type:

GCEInstanceGroupManager

Type:

dict

Returns:

An Autoscaler object.

Return type:

GCEAutoscaler

ex_create_backend(instance_group, balancing_mode='UTILIZATION', max_utilization=None, max_rate=None, max_rate_per_instance=None, capacity_scaler=1, description=None)[source]

Helper Object to create a backend.

Parameters:

instance_group – The Instance Group for this Backend.
balancing_mode (str) – Specifies the balancing mode for this backend. For global HTTP(S) load balancing, the valid values are UTILIZATION (default) and RATE. For global SSL load balancing, the valid values are UTILIZATION (default) and CONNECTION.
max_utilization (float) – Used when balancingMode is UTILIZATION. This ratio defines the CPU utilization target for the group. The default is 0.8. Valid range is [0.0, 1.0].
max_rate (int) – The max requests per second (RPS) of the group. Can be used with either RATE or UTILIZATION balancing modes, but required if RATE mode. For RATE mode, either maxRate or maxRatePerInstance must be set.
max_rate_per_instance (float) – The max requests per second (RPS) that a single backend instance can handle. This is used to calculate the capacity of the group. Can be used in either balancing mode. For RATE mode, either maxRate or maxRatePerInstance must be set.
capacity_scaler (float) – A multiplier applied to the group’s maximum servicing capacity (based on UTILIZATION, RATE, or CONNECTION). Default value is 1, which means the group will serve up to 100% of its configured capacity (depending on balancingMode). A setting of 0 means the group is completely drained, offering 0% of its available capacity. Valid range is [0.0,1.0].
description (str) – An optional description of this resource. Provide this property when you create the resource.

Returns:

A GCEBackend object.

Return type:

class:: GCEBackend

ex_create_backendservice(name, healthchecks, backends=[], protocol=None, description=None, timeout_sec=None, enable_cdn=False, port=None, port_name=None)[source]

Create a global Backend Service.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

name (str) – Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
healthchecks (list of (str or GCEHealthCheck)) – A list of HTTP Health Checks to use for this service. There must be at least one.
backends (list of :class GCEBackend or list of dict) – The list of backends that serve this BackendService.
timeout_sec (integer) – How many seconds to wait for the backend before considering it a failed request. Default is 30 seconds.
enable_cdn (bool) – If true, enable Cloud CDN for this BackendService. When the load balancing scheme is INTERNAL, this field is not used.
port (integer) – Deprecated in favor of port_name. The TCP port to connect on the backend. The default value is 80. This cannot be used for internal load balancing.
port_name (str) – Name of backend port. The same name should appear in the instance groups referenced by this service.
protocol (str) – The protocol this Backend Service uses to communicate with backends. Possible values are HTTP, HTTPS, HTTP2, TCP and SSL.

Returns:

A Backend Service object.

Return type:

GCEBackendService

ex_create_firewall(name, allowed=None, denied=None, network='default', target_ranges=None, direction='INGRESS', priority=1000, source_service_accounts=None, target_service_accounts=None, source_ranges=None, source_tags=None, target_tags=None, description=None)[source]

Create a firewall rule on a network. Rules can be for Ingress or Egress, and they may Allow or Deny traffic. They are also applied in order based on action (Deny, Allow) and Priority. Rules can be applied using various Source and Target filters.

Firewall rules should be supplied in the “allowed” or “denied” field. This is a list of dictionaries formatted like so (“ports” is optional):

[{“IPProtocol”: “<protocol string or number>”,
“ports”: “<port_numbers or ranges>”}]

For example, to allow tcp on port 8080 and udp on all ports, ‘allowed’ would be:

[{"IPProtocol": "tcp",
  "ports": ["8080"]},
 {"IPProtocol": "udp"}]

Note that valid inputs vary by direction (INGRESS vs EGRESS), action (allow/deny), and source/target filters (tag vs range etc).

See Firewall Reference for more information.

Parameters:

name (str) – Name of the firewall to be created
description (str) – Optional description of the rule.
direction (str) – Direction of the FW rule - “INGRESS” or “EGRESS” Defaults to ‘INGRESS’.
priority (int) – Priority integer of the rule - lower is applied first. Defaults to 1000
allowed (list of dict) – List of dictionaries with rules for type INGRESS
denied (list of dict) – List of dictionaries with rules for type EGRESS
network (str or GCENetwork) – The network that the firewall applies to.
source_ranges (list of str) – A list of IP ranges in CIDR format that the firewall should apply to. Defaults to [‘0.0.0.0/0’]
source_service_accounts (list of str) – A list of source service accounts the rules apply to.
source_tags (list of str) – A list of source instance tags the rules apply to.
target_tags (list of str) – A list of target instance tags the rules apply to.
target_service_accounts (list of str) – A list of target service accounts the rules apply to.
target_ranges (list of str) – A list of IP ranges in CIDR format that the EGRESS type rule should apply to. Defaults to [‘0.0.0.0/0’]

Returns:

Firewall object

Return type:

GCEFirewall

ex_create_forwarding_rule(name, target=None, region=None, protocol='tcp', port_range=None, address=None, description=None, global_rule=False, targetpool=None, lb_scheme=None)[source]

Create a forwarding rule.

Parameters:

name (str) – Name of forwarding rule to be created
target (str or GCETargetHttpProxy or GCETargetInstance or GCETargetPool) – The target of this forwarding rule. For global forwarding rules this must be a global TargetHttpProxy. For regional rules this may be either a TargetPool or TargetInstance. If passed a string instead of the object, it will be the name of a TargetHttpProxy for global rules or a TargetPool for regional rules. A TargetInstance must be passed by object. (required)
region (str or GCERegion) – Region to create the forwarding rule in. Defaults to self.region. Ignored if global_rule is True.
protocol (str) – Should be ‘tcp’ or ‘udp’
port_range (str) – Single port number or range separated by a dash. Examples: ‘80’, ‘5000-5999’. Required for global forwarding rules, optional for regional rules.
address (str or GCEAddress) – Optional static address for forwarding rule. Must be in same region.
description (str or None) – The description of the forwarding rule. Defaults to None.
targetpool (str or GCETargetPool) – Deprecated parameter for backwards compatibility. Use target instead.
lb_scheme (str or None) – Load balancing scheme, can be ‘EXTERNAL’ or ‘INTERNAL’. Defaults to ‘EXTERNAL’.

Returns:

Forwarding Rule object

Return type:

GCEForwardingRule

ex_create_healthcheck(name, host=None, path=None, port=None, interval=None, timeout=None, unhealthy_threshold=None, healthy_threshold=None, description=None)[source]

Create an Http Health Check.

Parameters:

name (str) – Name of health check
host (str) – Hostname of health check request. Defaults to empty and public IP is used instead.
path (str) – The request path for the check. Defaults to /.
port (int) – The TCP port number for the check. Defaults to 80.
interval (int) – How often (in seconds) to check. Defaults to 5.
timeout (int) – How long to wait before failing. Defaults to 5.
unhealthy_threshold (int) – How many failures before marking unhealthy. Defaults to 2.
healthy_threshold (int) – How many successes before marking as healthy. Defaults to 2.
description (str or None) – The description of the check. Defaults to None.

Returns:

Health Check object

Return type:

GCEHealthCheck

ex_create_image(name, volume, description=None, family=None, guest_os_features=None, use_existing=True, wait_for_completion=True, ex_licenses=None, ex_labels=None)[source]

Create an image from the provided volume.

Parameters:

name (str) – The name of the image to create.
volume (str or StorageVolume) – The volume to use to create the image, or the Google Cloud Storage URI
description (str) – Description of the new Image
family (str) – The name of the image family to which this image belongs. If you create resources by specifying an image family instead of a specific image name, the resource uses the latest non-deprecated image that is set with that family name.
guest_os_features (list of str or None) – Features of the guest operating system, valid for bootable images only.
ex_licenses (list of str) – List of strings representing licenses to be associated with the image.
ex_labels (dict or None) – Labels dictionary for image.
use_existing (bool) – If True and an image with the given name already exists, return an object for that image instead of attempting to create a new image.
wait_for_completion (bool) – If True, wait until the new image is created before returning a new NodeImage Otherwise, return a new NodeImage instance, and let the user track the creation progress

Returns:

A GCENodeImage object for the new image

Return type:

GCENodeImage

ex_create_instancegroup(name, zone, description=None, network=None, subnetwork=None, named_ports=None)[source]

Creates an instance group in the specified project using the parameters that are included in the request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

name (str) – Required. The name of the instance group. The name must be 1-63 characters long, and comply with RFC1035.
zone (GCEZone) – The URL of the zone where the instance group is located.
description (str) – An optional description of this resource. Provide this property when you create the resource.
network (GCENetwork) – The URL of the network to which all instances in the instance group belong.
subnetwork (GCESubnetwork) – The URL of the subnetwork to which all instances in the instance group belong.
named_ports (list of {‘name’: str, ‘port`: int}) – Assigns a name to a port number. For example: {name: “http”, port: 80} This allows the system to reference ports by the assigned name instead of a port number. Named ports can also contain multiple ports. For example: [{name: “http”, port: 80},{name: “http”, port: 8080}] Named ports apply to all instances in this instance group.

Returns:

GCEInstanceGroup object.

Return type:

GCEInstanceGroup

ex_create_instancegroupmanager(name, zone, template, size, base_instance_name=None, description=None)[source]

Create a Managed Instance Group.

Parameters:

name (str) – Name of the Instance Group.
zone (str or GCEZone or None) – The zone to which the Instance Group belongs
template (str or GCEInstanceTemplate) – The Instance Template. Should be an instance of GCEInstanceTemplate or a string.
base_instance_name (str) – The prefix for each instance created. If None, Instance Group name will be used.
description (str) – User-supplied text about the Instance Group.

Returns:

An Instance Group Manager object.

Return type:

GCEInstanceGroupManager

ex_create_instancetemplate(name, size, source=None, image=None, disk_type='pd-standard', disk_auto_delete=True, network='default', subnetwork=None, can_ip_forward=None, external_ip='ephemeral', internal_ip=None, service_accounts=None, on_host_maintenance=None, automatic_restart=None, preemptible=None, tags=None, metadata=None, description=None, disks_gce_struct=None, nic_gce_struct=None)[source]

Creates an instance template in the specified project using the data that is included in the request. If you are creating a new template to update an existing instance group, your new instance template must use the same network or, if applicable, the same subnetwork as the original template.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

name (str) – The name of the node to create.
size (str or GCENodeSize) – The machine type to use.
image (str or GCENodeImage or None) – The image to use to create the node (or, if attaching a persistent disk, the image used to create the disk)
network (str or GCENetwork) – The network to associate with the template.
subnetwork (str or GCESubnetwork) – The subnetwork to associate with the node.
tags (list of str or None) – A list of tags to associate with the node.
metadata (dict or None) – Metadata dictionary for instance.
external_ip (GCEAddress or str or None) – The external IP address to use. If ‘ephemeral’ (default), a new non-static address will be used. If ‘None’, then no external address will be used. To use an existing static IP address, a GCEAddress object should be passed in.
internal_ip (GCEAddress or str or None) – The private IP address to use.
disk_type (str or GCEDiskType) – Specify a pd-standard (default) disk or pd-ssd for an SSD disk.
disk_auto_delete (bool) – Indicate that the boot disk should be deleted when the Node is deleted. Set to True by default.
service_accounts (list) – Specify a list of serviceAccounts when creating the instance. The format is a list of dictionaries containing email and list of scopes, e.g. [{‘email’:’default’, ‘scopes’:[‘compute’, …]}, …] Scopes can either be full URLs or short names. If not provided, use the ‘default’ service account email and a scope of ‘devstorage.read_only’. Also accepts the aliases defined in ‘gcloud compute’.
description (str or None) – The description of the node (instance).
can_ip_forward (bool or None) – Set to True to allow this node to send/receive non-matching src/dst packets.
disks_gce_struct (list or None) – Support for passing in the GCE-specific formatted disks[] structure. No attempt is made to ensure proper formatting of the disks[] structure. Using this structure obviates the need of using other disk params like ‘ex_boot_disk’, etc. See the GCE docs for specific details.
nic_gce_struct (list or None) – Support passing in the GCE-specific formatted networkInterfaces[] structure. No attempt is made to ensure proper formatting of the networkInterfaces[] data. Using this structure obviates the need of using ‘external_ip’ and ‘ex_network’. See the GCE docs for details.
on_host_maintenance – Defines whether node should be terminated or migrated when host machine goes down. Acceptable values are: ‘MIGRATE’ or ‘TERMINATE’ (If not supplied, value will be reset to GCE default value for the instance type.)
automatic_restart (bool or None) – Defines whether the instance should be automatically restarted when it is terminated by Compute Engine. (If not supplied, value will be set to the GCE default value for the instance type.)
preemptible (bool or None) – Defines whether the instance is preemptible. (If not supplied, the instance will not be preemptible)

Returns:

An Instance Template object.

Return type:

GCEInstanceTemplate

ex_create_multiple_nodes(base_name, size, image, number, location=None, ex_network='default', ex_subnetwork=None, ex_tags=None, ex_metadata=None, ignore_errors=True, use_existing_disk=True, poll_interval=2, external_ip='ephemeral', internal_ip=None, ex_disk_type='pd-standard', ex_disk_auto_delete=True, ex_service_accounts=None, timeout=180, description=None, ex_can_ip_forward=None, ex_disks_gce_struct=None, ex_nic_gce_struct=None, ex_on_host_maintenance=None, ex_automatic_restart=None, ex_image_family=None, ex_preemptible=None, ex_labels=None, ex_disk_size=None)[source]

Create multiple nodes and return a list of Node objects.

Nodes will be named with the base name and a number. For example, if the base name is ‘libcloud’ and you create 3 nodes, they will be named:

libcloud-000
libcloud-001
libcloud-002

Parameters:

base_name (str) – The base name of the nodes to create.
size (str or GCENodeSize) – The machine type to use.
image (str or GCENodeImage) – The image to use to create the nodes.
number (int) – The number of nodes to create.
location (str or NodeLocation or GCEZone or None) – The location (zone) to create the nodes in.
ex_network (str or GCENetwork) – The network to associate with the nodes.
ex_tags (list of str or None) – A list of tags to associate with the nodes.
ex_metadata (dict or None) – Metadata dictionary for instances.
ignore_errors (bool) – If True, don’t raise Exceptions if one or more nodes fails.
use_existing_disk (bool) – If True and if an existing disk with the same name/location is found, use that disk instead of creating a new one.
poll_interval (int) – Number of seconds between status checks.
external_ip (str or None) – The external IP address to use. If ‘ephemeral’ (default), a new non-static address will be used. If ‘None’, then no external address will be used. (Static addresses are not supported for multiple node creation.)
internal_ip (GCEAddress or str or None) – The private IP address to use.
ex_disk_type (str or GCEDiskType) – Specify a pd-standard (default) disk or pd-ssd for an SSD disk.
ex_disk_auto_delete (bool) – Indicate that the boot disk should be deleted when the Node is deleted. Set to True by default.
ex_service_accounts (list) – Specify a list of serviceAccounts when creating the instance. The format is a list of dictionaries containing email and list of scopes, e.g. [{‘email’:’default’, ‘scopes’:[‘compute’, …]}, …] Scopes can either be full URLs or short names. If not provided, use the ‘default’ service account email and a scope of ‘devstorage.read_only’. Also accepts the aliases defined in ‘gcloud compute’.
timeout (int) – The number of seconds to wait for all nodes to be created before timing out.
description (str or None) – The description of the node (instance).
ex_can_ip_forward (bool or None) – Set to True to allow this node to send/receive non-matching src/dst packets.
ex_preemptible (bool or None) – Defines whether the instance is preemptible. (If not supplied, the instance will not be preemptible)
ex_disks_gce_struct (list or None) – Support for passing in the GCE-specific formatted disks[] structure. No attempt is made to ensure proper formatting of the disks[] structure. Using this structure obviates the need of using other disk params like ‘ex_boot_disk’, etc. See the GCE docs for specific details.
ex_nic_gce_struct (list or None) – Support passing in the GCE-specific formatted networkInterfaces[] structure. No attempt is made to ensure proper formatting of the networkInterfaces[] data. Using this structure obviates the need of using ‘external_ip’ and ‘ex_network’. See the GCE docs for details.
ex_on_host_maintenance (str or None) – Defines whether node should be terminated or migrated when host machine goes down. Acceptable values are: ‘MIGRATE’ or ‘TERMINATE’ (If not supplied, value will be reset to GCE default value for the instance type.)
ex_automatic_restart (bool or None) – Defines whether the instance should be automatically restarted when it is terminated by Compute Engine. (If not supplied, value will be set to the GCE default value for the instance type.)
ex_image_family (str or None) – Determine image from an ‘Image Family’ instead of by name. ‘image’ should be None to use this keyword.
ex_labels (dict) – Label dict for node.
ex_disk_size (int or None) – Defines size of the boot disk. Integer in gigabytes.

Returns:

A list of Node objects for the new nodes.

Return type:

list of Node

ex_create_network(name, cidr, description=None, mode='legacy', routing_mode=None)[source]

Create a network. In November 2015, Google introduced Subnetworks and suggests using networks with ‘auto’ generated subnetworks. See, the subnet docs for more details. Note that libcloud follows the usability pattern from the Cloud SDK (e.g. ‘gcloud compute’ command-line utility) and uses ‘mode’ to specify ‘auto’, ‘custom’, or ‘legacy’.

Parameters:

name (str) – Name of network to be created
cidr (str or None) – Address range of network in CIDR format.
description (str or None) – Custom description for the network.
mode (str) – Create a ‘auto’, ‘custom’, or ‘legacy’ network.
routing_mode (str or None) – Create network with ‘Global’ or ‘Regional’ routing mode for BGP advertisements. Defaults to ‘Regional’

Returns:

Network object

Return type:

GCENetwork

ex_create_route(name, dest_range, priority=500, network='default', tags=None, next_hop=None, description=None)[source]

Create a route.

Parameters:

name (str) – Name of route to be created
dest_range (str) – Address range of route in CIDR format.
priority (int) – Priority value, lower values take precedence
network (str or GCENetwork) – The network the route belongs to. Can be either the full URL of the network, the name of the network or a libcloud object.
tags (list of str or None) – List of instance-tags for routing, empty for all nodes
next_hop (str, Node, or None) – Next traffic hop. Use None for the default Internet gateway, or specify an instance or IP address.
description (str or None) – Custom description for the route.

Returns:

Route object

Return type:

GCERoute

ex_create_sslcertificate(name, certificate=None, private_key=None, description=None)[source]

Creates a SslCertificate resource in the specified project using the data included in the request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

name (str) – Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
certificate (str) – A string containing local certificate file in PEM format. The certificate chain must be no greater than 5 certs long. The chain must include at least one intermediate cert.
private_key (str) – A string containing a write-only private key in PEM format. Only insert RPCs will include this field.
description (str) – An optional description of this resource. Provide this property when you create the resource.

Returns:

GCESslCertificate object.

Return type:

GCESslCertificate

ex_create_subnetwork(name, cidr=None, network=None, region=None, description=None, privateipgoogleaccess=None, secondaryipranges=None)[source]

Create a subnetwork.

Parameters:

name (str) – Name of subnetwork to be created
cidr (str) – Address range of network in CIDR format.
network (str or GCENetwork) – The network name or object this subnet belongs to.
region (str or GCERegion) – The region the subnetwork belongs to.
description (str or None) – Custom description for the network.
privateipgoogleaccess (bool` or ``None) – Allow access to Google services without assigned external IP addresses.
secondaryipranges (list of dict or None) – List of dicts of secondary or “alias” IP ranges for this subnetwork in [{“rangeName”: “second1”, “ipCidrRange”: “192.168.168.0/24”}, {k:v, k:v}] format.

Returns:

Subnetwork object

Return type:

GCESubnetwork

ex_create_targethttpproxy(name, urlmap)[source]

Create a target HTTP proxy.

Parameters:

name (str) – Name of target HTTP proxy
urlmap – URL map defining the mapping from URl to the backendservice.

Returns:

Target Pool object

Return type:

GCETargetPool

ex_create_targethttpsproxy(name, urlmap, sslcertificates, description=None)[source]

Creates a TargetHttpsProxy resource in the specified project using the data included in the request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

name (str) – Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
sslcertificates (list of GCESslcertificates) – URLs to SslCertificate resources that are used to authenticate connections between users and the load balancer. Currently, exactly one SSL certificate must be specified.
urlmap (GCEUrlMap) – A fully-qualified or valid partial URL to the UrlMap resource that defines the mapping from URL to the BackendService.
description (str) – An optional description of this resource. Provide this property when you create the resource.

Returns:

GCETargetHttpsProxy object.

Return type:

GCETargetHttpsProxy

ex_create_targetinstance(name, zone=None, node=None, description=None, nat_policy='NO_NAT')[source]

Create a target instance.

Parameters:

name (str) – Name of target instance
region (str or GCEZone or None) – Zone to create the target pool in. Defaults to self.zone
node (str or Node) – The actual instance to be used as the traffic target.
description (str or None) – A text description for the target instance
nat_policy (str) – The NAT option for how IPs are NAT’d to the node.

Returns:

Target Instance object

Return type:

GCETargetInstance

ex_create_targetpool(name, region=None, healthchecks=None, nodes=None, session_affinity=None, backup_pool=None, failover_ratio=None)[source]

Create a target pool.

Parameters:

name (str) – Name of target pool
region (str or GCERegion or None) – Region to create the target pool in. Defaults to self.region
healthchecks (list of str or GCEHealthCheck) – Optional list of health checks to attach
nodes (list of str or Node) – Optional list of nodes to attach to the pool
session_affinity (str) – Optional algorithm to use for session affinity.
backup_pool (GCETargetPool or None) – Optional backup targetpool to take over traffic if the failover_ratio is exceeded.
failover_ratio (GCETargetPool or None) – The percentage of healthy VMs must fall at or below this value before traffic will be sent to the backup_pool.

Returns:

Target Pool object

Return type:

GCETargetPool

ex_create_urlmap(name, default_service)[source]

Create a URL Map.

Parameters:

name (str) – Name of the URL Map.
default_service (str or GCEBackendService) – Default backend service for the map.

Returns:

URL Map object

Return type:

GCEUrlMap

ex_delete_access_config(node, name, nic)[source]

Delete a network interface access configuration from a node.

Parameters:

node (Node) – The existing target Node (instance) for the request.
name (str) – Name of the access config.
nic (str) – Name of the network interface.

Returns:

True if successful

Return type:

bool

ex_delete_image(image)[source]

Delete a specific image resource.

Parameters:: image (str or GCENodeImage) – Image object to delete
Returns:: True if successful
Return type:: bool

ex_deprecate_image(image, replacement, state=None, deprecated=None, obsolete=None, deleted=None)[source]

Deprecate a specific image resource.

Parameters:

image (str or :class: GCENodeImage) – Image object to deprecate
replacement (str or :class: GCENodeImage) – Image object to use as a replacement
state (str) – State of the image
deprecated (str or None) – RFC3339 timestamp to mark DEPRECATED
obsolete (str or None) – RFC3339 timestamp to mark OBSOLETE
deleted (str or None) – RFC3339 timestamp to mark DELETED

Returns:

True if successful

Return type:

bool

ex_destroy_address(address)[source]

Destroy a static address.

Parameters:: address (str or GCEAddress) – Address object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_autoscaler(autoscaler)[source]

Destroy an Autoscaler.

Parameters:: autoscaler (GCEAutoscaler) – Autoscaler object to destroy.
Returns:: True if successful
Return type:: bool

ex_destroy_backendservice(backendservice)[source]

Destroy a Backend Service.

Parameters:: backendservice (GCEBackendService) – BackendService object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_firewall(firewall)[source]

Destroy a firewall.

Parameters:: firewall (GCEFirewall) – Firewall object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_forwarding_rule(forwarding_rule)[source]

Destroy a forwarding rule.

Parameters:: forwarding_rule (GCEForwardingRule) – Forwarding Rule object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_healthcheck(healthcheck)[source]

Destroy a healthcheck.

Parameters:: healthcheck (GCEHealthCheck) – Health check object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_instancegroup(instancegroup)[source]

Deletes the specified instance group. The instances in the group are not deleted. Note that instance group must not belong to a backend service. Read Deleting an instance group for more information.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:: instancegroup (GCEInstanceGroup) – The name of the instance group to delete.
Returns:: Return True if successful.
Return type:: bool

ex_destroy_instancegroupmanager(manager)[source]

Destroy a managed instance group. This will destroy all instances that belong to the instance group.

Parameters:: manager (GCEInstanceGroup) – InstanceGroup object to destroy.
Returns:: True if successful
Return type:: bool

ex_destroy_instancetemplate(instancetemplate)[source]

Deletes the specified instance template. If you delete an instance template that is being referenced from another instance group, the instance group will not be able to create or recreate virtual machine instances. Deleting an instance template is permanent and cannot be undone.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:: instancetemplate (str) – The name of the instance template to delete.
Return instanceTemplate:: Return True if successful.
Rtype instanceTemplate:: ``bool``

ex_destroy_multiple_nodes(node_list, ignore_errors=True, destroy_boot_disk=False, poll_interval=2, timeout=180)[source]

Destroy multiple nodes at once.

Parameters:

node_list (list of Node) – List of nodes to destroy
ignore_errors (bool) – If true, don’t raise an exception if one or more nodes fails to be destroyed.
destroy_boot_disk (bool) – If true, also destroy the nodes’ boot disks.
poll_interval (int) – Number of seconds between status checks.
timeout (int) – Number of seconds to wait for all nodes to be destroyed.

Returns:

A list of boolean values. One for each node. True means that the node was successfully destroyed.

Return type:

list of bool

ex_destroy_network(network)[source]

Destroy a network.

Parameters:: network (GCENetwork) – Network object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_route(route)[source]

Destroy a route.

Parameters:: route (GCERoute) – Route object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_sslcertificate(sslcertificate)[source]

Deletes the specified SslCertificate resource.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:: sslcertificate (str) – Name of the SslCertificate resource to delete.
Return sslCertificate:: Return True if successful.
Rtype sslCertificate:: ``bool``

ex_destroy_subnetwork(name, region=None)[source]

Delete a Subnetwork object based on name and region.

Parameters:

name (str or GCESubnetwork) – The name, URL or object of the subnetwork
region (str or GCERegion or None) – The region object, name, or URL of the subnetwork

Returns:

True if successful

Return type:

bool

ex_destroy_targethttpproxy(targethttpproxy)[source]

Destroy a target HTTP proxy.

Parameters:: targethttpproxy (GCETargetHttpProxy) – TargetHttpProxy object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_targethttpsproxy(targethttpsproxy)[source]

Deletes the specified TargetHttpsProxy resource.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:: targethttpsproxy (str) – Name of the TargetHttpsProxy resource to delete.
Return targetHttpsProxy:: Return True if successful.
Rtype targetHttpsProxy:: ``bool``

ex_destroy_targetinstance(targetinstance)[source]

Destroy a target instance.

Parameters:: targetinstance (GCETargetInstance) – TargetInstance object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_targetpool(targetpool)[source]

Destroy a target pool.

Parameters:: targetpool (GCETargetPool) – TargetPool object to destroy
Returns:: True if successful
Return type:: bool

ex_destroy_urlmap(urlmap)[source]

Destroy a URL map.

Parameters:: urlmap (GCEUrlMap) – UrlMap object to destroy
Returns:: True if successful
Return type:: bool

ex_get_accelerator_type(name, zone=None)[source]

Return an AcceleratorType object based on a name and zone.

Parameters:

name (str) – The name of the AcceleratorType
zone (GCEZone) – The zone to search for the AcceleratorType in.

Returns:

An AcceleratorType object for the name

Return type:

GCEAcceleratorType

ex_get_address(name, region=None)[source]

Return an Address object based on an address name and optional region.

Parameters:

name (str) – The name of the address
region (str GCERegion or None) – The region to search for the address in (set to ‘all’ to search all regions)

Returns:

An Address object for the address

Return type:

GCEAddress

ex_get_autoscaler(name, zone=None)[source]

Return an Autoscaler object based on a name and optional zone.

Parameters:

name (str) – The name of the Autoscaler.
zone (str or GCEZone or None) – The zone to search for the Autoscaler. Set to ‘all’ to search all zones.

Returns:

An Autoscaler object.

Return type:

GCEAutoscaler

ex_get_backendservice(name)[source]

Return a Backend Service object based on name

Parameters:: name (str) – The name of the backend service
Returns:: A BackendService object for the backend service
Return type:: GCEBackendService

ex_get_disktype(name, zone=None)[source]

Return a DiskType object based on a name and optional zone.

Parameters:

name (str) – The name of the DiskType
zone (str GCEZone or None) – The zone to search for the DiskType in (set to ‘all’ to search all zones)

Returns:

A DiskType object for the name

Return type:

GCEDiskType

ex_get_firewall(name)[source]

Return a Firewall object based on the firewall name.

Parameters:: name (str) – The name of the firewall
Returns:: A GCEFirewall object
Return type:: GCEFirewall

ex_get_forwarding_rule(name, region=None, global_rule=False)[source]

Return a Forwarding Rule object based on the forwarding rule name.

Parameters:

name (str) – The name of the forwarding rule
region (str or None) – The region to search for the rule in (set to ‘all’ to search all regions).
global_rule (bool) – Set to True to get a global forwarding rule. Region will be ignored if True.

Returns:

A GCEForwardingRule object

Return type:

GCEForwardingRule

ex_get_healthcheck(name)[source]

Return a HealthCheck object based on the healthcheck name.

Parameters:: name (str) – The name of the healthcheck
Returns:: A GCEHealthCheck object
Return type:: GCEHealthCheck

ex_get_image(partial_name, ex_project_list=None, ex_standard_projects=True)[source]

Return an GCENodeImage object based on the name or link provided.

Parameters:

partial_name (str) – The name, partial name, or full path of a GCE image.
ex_project_list (str or list of str or None) – The name of the project to list for images. Examples include: ‘debian-cloud’.
ex_standard_projects (bool) – If true, check in standard projects if the image is not found.

Returns:

GCENodeImage object based on provided information or None if an image with that name is not found.

Return type:

GCENodeImage or raise ResourceNotFoundError

ex_get_image_from_family(image_family, ex_project_list=None, ex_standard_projects=True)[source]

Return an GCENodeImage object based on an image family name.

Parameters:

image_family (str) – The name of the ‘Image Family’ to return the latest image from.
ex_project_list (list of str, or None) – The name of the project to list for images. Examples include: ‘debian-cloud’.
ex_standard_projects (bool) – If true, check in standard projects if the image is not found.

Returns:

GCENodeImage object based on provided information or ResourceNotFoundError if the image family is not found.

Return type:

GCENodeImage or raise ResourceNotFoundError

ex_get_instancegroup(name, zone=None)[source]

Returns the specified Instance Group. Get a list of available instance groups by making a list() request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Parameters:

name (str) – The name of the instance group.
zone (str) – The name of the zone where the instance group is located.

Returns:

GCEInstanceGroup object.

Return type:

GCEInstanceGroup

ex_get_instancegroupmanager(name, zone=None)[source]

Return a InstanceGroupManager object based on a name and optional zone.

Parameters:

name (str) – The name of the Instance Group Manager.
zone (str or GCEZone or None) – The zone to search for the Instance Group Manager. Set to ‘all’ to search all zones.

Returns:

An Instance Group Manager object.

Return type:

GCEInstanceGroupManager

ex_get_instancetemplate(name)[source]

Return an InstanceTemplate object based on a name and optional zone.

Parameters:: name (str) – The name of the Instance Template.
Returns:: An Instance Template object.
Return type:: GCEInstanceTemplate

ex_get_license(project, name)[source]

Return a License object for specified project and name.

Parameters:

project (str) – The project to reference when looking up the license.
name (str) – The name of the License

Returns:

A License object for the name

Return type:

GCELicense

ex_get_network(name)[source]

Return a Network object based on a network name.

Parameters:: name (str) – The name or URL of the network
Returns:: A Network object for the network
Return type:: GCENetwork

ex_get_node(name, zone=None)[source]

Return a Node object based on a node name and optional zone.

Parameters:

name (str) – The name of the node
zone (str or GCEZone or NodeLocation or None) – The zone to search for the node in. If set to ‘all’, search all zones for the instance.

Returns:

A Node object for the node

Return type:

Node

ex_get_project()[source]

Return a Project object with project-wide information.

Returns:: A GCEProject object
Return type:: GCEProject

ex_get_region(name)[source]

Return a Region object based on the region name.

Parameters:: name (str) – The name of the region.
Returns:: A GCERegion object for the region
Return type:: GCERegion

ex_get_route(name)[source]

Return a Route object based on a route name.

Parameters:: name (str) – The name of the route
Returns:: A Route object for the named route
Return type:: GCERoute

ex_get_serial_output(node)[source]

Fetch the console/serial port output from the node.

Parameters:: node (Node) – The existing target Node (instance) for the request.
Returns:: A string containing serial port output of the node.
Return type:: str

ex_get_size(name, zone=None)[source]

Return a size object based on a machine type name and zone.

Parameters:

name (str) – The name of the node
zone (str or GCEZone or NodeLocation or None) – The zone to search for the machine type in

Returns:

A GCENodeSize object for the machine type

Return type:

GCENodeSize

ex_get_snapshot(name)[source]

Return a Snapshot object based on snapshot name.

Parameters:: name (str) – The name of the snapshot
Returns:: A GCESnapshot object for the snapshot
Return type:: GCESnapshot

ex_get_sslcertificate(name)[source]

Returns the specified SslCertificate resource. Get a list of available SSL certificates by making a list() request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Parameters:: name (str) – Name of the SslCertificate resource to return.
Returns:: GCESslCertificate object.
Return type:: GCESslCertificate

ex_get_subnetwork(name, region=None)[source]

Return a Subnetwork object based on name and region.

Parameters:

name (str) – The name or URL of the subnetwork
region (str or GCERegion or None) – The region of the subnetwork

Returns:

A Subnetwork object

Return type:

GCESubnetwork

ex_get_targethttpproxy(name)[source]

Return a Target HTTP Proxy object based on its name.

Parameters:: name (str) – The name of the target HTTP proxy.
Returns:: A Target HTTP Proxy object for the pool
Return type:: GCETargetHttpProxy

ex_get_targethttpsproxy(name)[source]

Returns the specified TargetHttpsProxy resource. Get a list of available target HTTPS proxies by making a list() request.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Parameters:: name (str) – Name of the TargetHttpsProxy resource to return.
Returns:: GCETargetHttpsProxy object.
Return type:: GCETargetHttpsProxy

ex_get_targetinstance(name, zone=None)[source]

Return a TargetInstance object based on a name and optional zone.

Parameters:

name (str) – The name of the target instance
zone (str or GCEZone or None) – The zone to search for the target instance in (set to ‘all’ to search all zones).

Returns:

A TargetInstance object for the instance

Return type:

GCETargetInstance

ex_get_targetpool(name, region=None)[source]

Return a TargetPool object based on a name and optional region.

Parameters:

name (str) – The name of the target pool
region (str or GCERegion or None) – The region to search for the target pool in (set to ‘all’ to search all regions).

Returns:

A TargetPool object for the pool

Return type:

GCETargetPool

ex_get_urlmap(name)[source]

Return a URL Map object based on name

Parameters:: name (str) – The name of the url map
Returns:: A URL Map object for the backend service
Return type:: GCEUrlMap

ex_get_volume(name, zone=None, use_cache=False)[source]

Return a Volume object based on a volume name and optional zone.

To improve performance, we request all disks and allow the user to consult the cache dictionary rather than making an API call.

Parameters:

name (str) – The name of the volume
zone (str or GCEZone or NodeLocation or None) – The zone to search for the volume in (set to ‘all’ to search all zones)
use_cache (bool) – Search for the volume in the existing cache of volumes. If True, we omit the API call and search self.volumes_dict. If False, a call to disks/aggregatedList is made prior to searching self._ex_volume_dict.

Returns:

A StorageVolume object for the volume

Return type:

StorageVolume

ex_get_zone(name)[source]

Return a Zone object based on the zone name.

Parameters:: name (str) – The name of the zone.
Returns:: A GCEZone object for the zone or None if not found
Return type:: GCEZone or None

ex_instancegroup_add_instances(instancegroup, node_list)[source]

Adds a list of instances to the specified instance group. All of the instances in the instance group must be in the same network/subnetwork. Read Adding instances for more information.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

instancegroup (:class:GCEInstanceGroup) – The Instance Group where you are adding instances.
node_list (list of Node or list of GCENode) – List of nodes to add.

Returns:

Return True if successful.

Return type:

bool

ex_instancegroup_list_instances(instancegroup)[source]

Lists the instances in the specified instance group.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Parameters:: instancegroup (GCEInstanceGroup) – The Instance Group where from which you want to generate a list of included instances.
Returns:: List of GCENode objects.
Return type:: list of GCENode objects.

ex_instancegroup_remove_instances(instancegroup, node_list)[source]

Removes one or more instances from the specified instance group, but does not delete those instances.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

instancegroup (:class:GCEInstanceGroup) – The Instance Group where the specified instances will be removed.
node_list (list of Node or list of GCENode) – List of nodes to add.

Returns:

True if successful.

Return type:

bool

ex_instancegroup_set_named_ports(instancegroup, named_ports=[])[source]

Sets the named ports for the specified instance group.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

instancegroup (GCEInstanceGroup) – The Instance Group where where the named ports are updated.
named_ports (list of {‘name’: str, ‘port`: int}) – Assigns a name to a port number. For example: {name: “http”, port: 80} This allows the system to reference ports by the assigned name instead of a port number. Named ports can also contain multiple ports. For example: [{name: “http”, port: 80},{name: “http”, port: 8080}] Named ports apply to all instances in this instance group.

Returns:

Return True if successful.

Return type:

bool

ex_instancegroupmanager_delete_instances(manager, node_list)[source]

Remove instances from GCEInstanceGroupManager and destroy the instance

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

manager (str or :class: GCEInstanceGroupManager) – Required. The name of the managed instance group. The name must be 1-63 characters long, and comply with RFC1035.
node_list (list of Node) – list of Node objects to delete.

Returns:

True if successful

Return type:

bool

ex_instancegroupmanager_list_managed_instances(manager)[source]

Lists all of the instances in the Managed Instance Group.

Each instance in the list has a currentAction, which indicates the action that the managed instance group is performing on the instance. For example, if the group is still creating an instance, the currentAction is ‘CREATING’. Note that ‘instanceStatus’ might not be available, for example, if currentAction is ‘CREATING’ or ‘RECREATING’. If a previous action failed, the list displays the errors for that failed action.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

‘currentAction’ values are one of:: ‘ABANDONING’, ‘CREATING’, ‘DELETING’, ‘NONE’, ‘RECREATING’, ‘REFRESHING’, ‘RESTARTING’

Parameters:: manager (GCEInstanceGroupManager) – Instance Group Manager to operate on.
Returns:: list of dict containing ‘name’, ‘zone’, ‘lastAttempt’, ‘currentAction’, ‘instance’ and ‘instanceStatus’.
Return type:: list

ex_instancegroupmanager_recreate_instances(manager, instances=None)[source]

Schedules a group action to recreate the specified instances in the managed instance group. The instances are deleted and recreated using the current instance template for the managed instance group. This operation is marked as DONE when the action is scheduled even if the instances have not yet been recreated. You must separately verify the status of the recreating action with the listmanagedinstances method or querying the managed instance group directly.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

manager (str or :class: GCEInstanceGroupManager) – Required. The name of the managed instance group. The name must be 1-63 characters long, and comply with RFC1035.
instances (list of :class: Node, list of instance names (only), list of instance URIs, or None.) – list of Node objects to be recreated. If equal to None, all instances in the managed instance group are recreated.

Returns:

Dictionary containing instance URI and currentAction. See ex_instancegroupmanager_list_managed_instances for more details.

Return type:

dict

ex_instancegroupmanager_resize(manager, size)[source]

Set the Instance Template for this Instance Group.

Parameters:

manager (GCEInstanceGroupManager) – Instance Group Manager to operate on.
size (int) – New size of Managed Instance Group.

Returns:

True if successful

Return type:

bool

ex_instancegroupmanager_set_autohealingpolicies(manager, healthcheck, initialdelaysec)[source]

Set the Autohealing Policies for this Instance Group.

Parameters:

healthcheck (GCEHealthCheck) – Healthcheck to add
initialdelaysec (int) – The time to allow an instance to boot and applications to fully start before the first health check

Returns:

True if successful

Return type:

bool

ex_instancegroupmanager_set_instancetemplate(manager, instancetemplate)[source]

Set the Instance Template for this Instance Group. Existing VMs are not recreated by setting a new InstanceTemplate.

Parameters:

manager (GCEInstanceGroupManager) – Instance Group Manager to operate on.
instancetemplate (GCEInstanceTemplate) – Instance Template to set.

Returns:

True if successful

Return type:

bool

ex_list(list_fn, **kwargs)[source]

Wrap a list method in a GCEList iterator.

>>> for sublist in driver.ex_list(driver.ex_list_urlmaps).page(1):
...   sublist
...
[<GCEUrlMap id="..." name="cli-map">]
[<GCEUrlMap id="..." name="lc-map">]
[<GCEUrlMap id="..." name="web-map">]

Parameters:: list_fn (instancemethod) – A bound list method from GCENodeDriver.
Returns:: An iterator that returns sublists from list_fn.
Return type:: GCEList

ex_list_addresses(region=None)[source]

Return a list of static addresses for a region, ‘global’, or all.

Parameters:: region (str or None) – The region to return addresses from. For example: ‘us-central1’. If None, will return addresses from region of self.zone. If ‘all’, will return all addresses. If ‘global’, it will return addresses in the global namespace.
Returns:: A list of static address objects.
Return type:: list of GCEAddress

ex_list_autoscalers(zone=None)[source]

Return the list of AutoScalers.

Parameters:: zone (str or None) – The zone to return InstanceGroupManagers from. For example: ‘us-central1-a’. If None, will return InstanceGroupManagers from self.zone. If ‘all’, will return all InstanceGroupManagers.
Returns:: A list of AutoScaler Objects
Return type:: list of GCEAutoScaler

ex_list_backendservices()[source]

Return a list of backend services.

Returns:: A list of backend service objects.
Return type:: list of GCEBackendService

ex_list_disktypes(zone=None)[source]

Return a list of DiskTypes for a zone or all.

Parameters:: zone (str or None) – The zone to return DiskTypes from. For example: ‘us-central1-a’. If None, will return DiskTypes from self.zone. If ‘all’, will return all DiskTypes.
Returns:: A list of static DiskType objects.
Return type:: list of GCEDiskType

ex_list_firewalls()[source]

Return the list of firewalls.

Returns:: A list of firewall objects.
Return type:: list of GCEFirewall

ex_list_forwarding_rules(region=None, global_rules=False)[source]

Return the list of forwarding rules for a region or all.

Parameters:

region (str or GCERegion or None) – The region to return forwarding rules from. For example: ‘us-central1’. If None, will return forwarding rules from the region of self.region (which is based on self.zone). If ‘all’, will return forwarding rules for all regions, which does not include the global forwarding rules.
global_rules (bool) – List global forwarding rules instead of per-region rules. Setting True will cause ‘region’ parameter to be ignored.

Returns:

A list of forwarding rule objects.

Return type:

list of GCEForwardingRule

ex_list_healthchecks()[source]

Return the list of health checks.

Returns:: A list of health check objects.
Return type:: list of GCEHealthCheck

ex_list_instancegroupmanagers(zone=None)[source]

Return a list of Instance Group Managers.

Parameters:: zone (str or None) – The zone to return InstanceGroupManagers from. For example: ‘us-central1-a’. If None, will return InstanceGroupManagers from self.zone. If ‘all’, will return all InstanceGroupManagers.
Returns:: A list of instance group mgr objects.
Return type:: list of GCEInstanceGroupManagers

ex_list_instancegroups(zone)[source]

Retrieves the list of instance groups that are located in the specified project and zone.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Parameters:: zone (str) – The name of the zone where the instance group is located.
Returns:: A list of instance group mgr objects.
Return type:: list of GCEInstanceGroupManagers

ex_list_instancetemplates()[source]

Return the list of Instance Templates.

Returns:: A list of Instance Template Objects
Return type:: list of GCEInstanceTemplate

ex_list_networks()[source]

Return the list of networks.

Returns:: A list of network objects.
Return type:: list of GCENetwork

ex_list_project_images(ex_project=None, ex_include_deprecated=False)[source]

Return a list of image objects for a project. If no project is specified, only a list of ‘global’ images is returned.

Parameters:

ex_project (str, list of str, or None) – Optional alternate project name.
ex_include_deprecated (bool) – If True, even DEPRECATED images will be returned.

Returns:

List of GCENodeImage objects

Return type:

list of GCENodeImage

ex_list_regions()[source]

Return the list of regions.

Returns:: A list of region objects.
Return type:: list of GCERegion

ex_list_routes()[source]

Return the list of routes.

Returns:: A list of route objects.
Return type:: list of GCERoute

ex_list_snapshots()[source]

Return the list of disk snapshots in the project.

Returns:: A list of snapshot objects
Return type:: list of GCESnapshot

ex_list_sslcertificates()[source]

Retrieves the list of SslCertificate resources available to the specified project.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute * https://www.googleapis.com/auth/compute.readonly

Returns:: A list of SSLCertificate objects.
Return type:: list of GCESslCertificate

ex_list_subnetworks(region=None)[source]

Return the list of subnetworks.

Parameters:: region (str or GCERegion) – Region for the subnetwork. Specify ‘all’ to return the aggregated list of subnetworks.
Returns:: A list of subnetwork objects.
Return type:: list of GCESubnetwork

ex_list_targethttpproxies()[source]

Return the list of target HTTP proxies.

Returns:: A list of target http proxy objects
Return type:: list of GCETargetHttpProxy

ex_list_targethttpsproxies()[source]

Return the list of target HTTPs proxies.

Returns:: A list of target https proxy objects
Return type:: list of GCETargetHttpsProxy

ex_list_targetinstances(zone=None)[source]

Return the list of target instances.

Returns:: A list of target instance objects
Return type:: list of GCETargetInstance

ex_list_targetpools(region=None)[source]

Return the list of target pools.

Returns:: A list of target pool objects
Return type:: list of GCETargetPool

ex_list_urlmaps()[source]

Return the list of URL Maps in the project.

Returns:: A list of url map objects
Return type:: list of GCEUrlMap

ex_list_zones()[source]

Return the list of zones.

Returns:: A list of zone objects.
Return type:: list of GCEZone

ex_resize_volume(volume, size)[source]

Resize a volume to the specified size.

Parameters:

volume (StorageVolume) – Volume object to resize
size (int) – The size in GB of the volume to resize to.

Returns:

True if successful

Return type:

bool

ex_set_common_instance_metadata(metadata=None, force=False)[source]

Set common instance metadata for the project. Common uses are for setting ‘sshKeys’, or setting a project-wide ‘startup-script’ for all nodes (instances). Passing in None for the ‘metadata’ parameter will clear out all common instance metadata except for ‘sshKeys’. If you also want to update ‘sshKeys’, set the ‘force’ parameter to True.

Parameters:

metadata (dict or None) – Dictionary of metadata. Can be either a standard python dictionary, or the format expected by GCE (e.g. {‘items’: [{‘key’: k1, ‘value’: v1}, …}]
force (bool) – Force update of ‘sshKeys’. If force is False (the default), existing sshKeys will be retained. Setting force to True will either replace sshKeys if a new a new value is supplied, or deleted if no new value is supplied.

Returns:

True if successful

Return type:

bool

ex_set_image_labels(image, labels)[source]

Set labels for the specified image.

Parameters:

image (NodeImage) – The existing target Image for the request.
labels (dict or None) – Set (or clear with None) labels for this image.

Returns:

True if successful

Return type:

bool

ex_set_machine_type(node, machine_type='n1-standard-1')[source]

Set the machine type of the stopped instance. Can be the short-name, a full, or partial URL.

Parameters:

node (Node) – Target node object to change
machine_type (str) – Desired machine type

Returns:

True if successful

Return type:

bool

ex_set_node_labels(node, labels)[source]

Set labels for the specified node.

Parameters:

node (Node) – The existing target Node (instance) for the request.
labels (dict or None) – Set (or clear with None) labels for this node.

Returns:

True if successful

Return type:

bool

ex_set_node_metadata(node, metadata)[source]

Set metadata for the specified node.

Parameters:

node (Node) – The existing target Node (instance) for the request.
metadata (dict or None) – Set (or clear with None) metadata for this particular node.

Returns:

True if successful

Return type:

bool

ex_set_node_scheduling(node, on_host_maintenance=None, automatic_restart=None)[source]

Set the maintenance behavior for the node.

See Scheduling documentation for more info.

Parameters:

node (Node) – Node object
on_host_maintenance (str) – Defines whether node should be terminated or migrated when host machine goes down. Acceptable values are: ‘MIGRATE’ or ‘TERMINATE’ (If not supplied, value will be reset to GCE default value for the instance type.)
automatic_restart (bool) – Defines whether the instance should be automatically restarted when it is terminated by Compute Engine. (If not supplied, value will be set to the GCE default value for the instance type.)

Returns:

True if successful.

Return type:

bool

ex_set_node_tags(node, tags)[source]

Set the tags on a Node instance.

Note that this updates the node object directly.

Parameters:

node (Node) – Node object
tags (list of str) – List of tags to apply to the object

Returns:

True if successful

Return type:

bool

ex_set_usage_export_bucket(bucket, prefix=None)[source]

Used to retain Compute Engine resource usage, storing the CSV data in a Google Cloud Storage bucket. See the docs for more information. Please ensure you have followed the necessary setup steps prior to enabling this feature (e.g. bucket exists, ACLs are in place, etc.)

Parameters:

bucket (str) – Name of the Google Cloud Storage bucket. Specify the name in either ‘gs://<bucket_name>’ or the full URL ‘https://storage.googleapis.com/<bucket_name>’.
prefix (str or None) – Optional prefix string for all reports.

Returns:

True if successful

Return type:

bool

ex_set_volume_auto_delete(volume, node, auto_delete=True)[source]

Sets the auto-delete flag for a volume attached to a node.

Parameters:

volume (StorageVolume) – Volume object to auto-delete
ex_node (Node) – Node object to auto-delete volume from
auto_delete (bool (default True)) – Flag to set for the auto-delete value

Returns:

True if successful

Return type:

bool

ex_set_volume_labels(volume, labels)[source]

Set labels for the specified volume (disk).

Parameters:

volume (StorageVolume) – The existing target StorageVolume for the request.
labels (dict or None) – Set (or clear with None) labels for this image.

Returns:

True if successful

Return type:

bool

ex_targethttpsproxy_set_sslcertificates(targethttpsproxy, sslcertificates)[source]

Replaces SslCertificates for TargetHttpsProxy.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

targethttpsproxy (str) – Name of the TargetHttpsProxy resource to set an SslCertificates resource for.
sslcertificates (list of GCESslCertificates) – sslcertificates to set.

Returns:

True

Return type:

bool

ex_targethttpsproxy_set_urlmap(targethttpsproxy, urlmap)[source]

Changes the URL map for TargetHttpsProxy.

Scopes needed - one of the following: * https://www.googleapis.com/auth/cloud-platform * https://www.googleapis.com/auth/compute

Parameters:

targethttpsproxy (str) – Name of the TargetHttpsProxy resource whose URL map is to be set.
urlmap (GCEUrlMap) – urlmap to set.

Returns:

True

Return type:

bool

ex_targetpool_add_healthcheck(targetpool, healthcheck)[source]

Add a health check to a target pool.

Parameters:

targetpool (str or GCETargetPool) – The targetpool to add health check to
healthcheck (str or GCEHealthCheck) – The healthcheck to add

Returns:

True if successful

Return type:

bool

ex_targetpool_add_node(targetpool, node)[source]

Add a node to a target pool.

Parameters:

targetpool (str or GCETargetPool) – The targetpool to add node to
node (str or Node) – The node to add

Returns:

True if successful

Return type:

bool

ex_targetpool_get_health(targetpool, node=None)[source]

Return a hash of target pool instances and their health.

Parameters:

targetpool (GCETargetPool) – Targetpool containing healthchecked instances.
node (str, Node, or None) – Optional node to specify if only a specific node’s health status should be returned

Returns:

List of hashes of instances and their respective health, e.g. [{‘node’: Node, ‘health’: ‘UNHEALTHY’}, …]

Return type:

list of dict

ex_targetpool_remove_healthcheck(targetpool, healthcheck)[source]

Remove a health check from a target pool.

Parameters:

targetpool (str or GCETargetPool) – The targetpool to remove health check from
healthcheck (str or GCEHealthCheck) – The healthcheck to remove

Returns:

True if successful

Return type:

bool

ex_targetpool_remove_node(targetpool, node)[source]

Remove a node from a target pool.

Parameters:

targetpool (str or GCETargetPool) – The targetpool to remove node from
node (str or Node) – The node to remove

Returns:

True if successful

Return type:

bool

ex_targetpool_set_backup_targetpool(targetpool, backup_targetpool, failover_ratio=0.1)[source]

Set a backup targetpool.

Parameters:

targetpool (GCETargetPool) – The existing primary targetpool
backup_targetpool (GCETargetPool) – The existing targetpool to use for failover traffic.
failover_ratio (float) – The percentage of healthy VMs must fall at or below this value before traffic will be sent to the backup targetpool (default 0.10)

Returns:

True if successful

Return type:

bool

ex_update_autoscaler(autoscaler)[source]

Update an autoscaler with new values.

To update, change the attributes of the autoscaler object and pass the updated object to the method.

Parameters:: autoscaler (GCEAutoscaler) – An Autoscaler object with updated values.
Returns:: An Autoscaler object representing the new state.
Return type:: GCEAutoscaler`

ex_update_firewall(firewall)[source]

Update a firewall with new values.

To update, change the attributes of the firewall object and pass the updated object to the method.

Parameters:: firewall (GCEFirewall) – A firewall object with updated values.
Returns:: An object representing the new state of the firewall.
Return type:: GCEFirewall

ex_update_healthcheck(healthcheck)[source]

Update a health check with new values.

To update, change the attributes of the health check object and pass the updated object to the method.

Parameters:: healthcheck (GCEHealthCheck) – A healthcheck object with updated values.
Returns:: An object representing the new state of the health check.
Return type:: GCEHealthCheck

features: Dict[str, List[str]] = {'create_node': ['ssh_key']}

List of available features for a driver.

libcloud.compute.base.NodeDriver.create_node()
- ssh_key: Supports NodeAuthSSHKey as an authentication method for nodes.
- password: Supports NodeAuthPassword as an authentication method for nodes.
- generates_password: Returns a password attribute on the Node object returned from creation.

get_image(image_id: str) → NodeImage

Returns a single node image from a provider.

Parameters:: image_id (str) – Node to run the task on.

:rtype NodeImage: :return: NodeImage instance on success.

get_key_pair(name: str) → KeyPair

Retrieve a single key pair.

Parameters:: name (str) – Name of the key pair to retrieve.
Return type:: KeyPair

import_key_pair_from_file(name: str, key_file_path: str) → KeyPair

Import a new public key from string.

Parameters:

name (str) – Key pair name.
key_file_path (str) – Path to the public key file.

Return type:

KeyPair object

import_key_pair_from_string(name: str, key_material: str) → KeyPair

Import a new public key from string.

Parameters:

name (str) – Key pair name.
key_material (str) – Public key material.

Return type:

KeyPair object

list_images(ex_project=None, ex_include_deprecated=False)[source]

Return a list of image objects. If no project is specified, a list of all non-deprecated global and vendor images images is returned. By default, only non-deprecated images are returned.

Parameters:

ex_project (str, list of str, or None) – Optional alternate project name.
ex_include_deprecated (bool) – If True, even DEPRECATED images will be returned.

Returns:

List of GCENodeImage objects

Return type:

list of GCENodeImage

list_key_pairs() → List[KeyPair]

List all the available key pair objects.

Return type:: list of KeyPair objects

list_locations()[source]

Return a list of locations (zones).

The ex_list_zones method returns more comprehensive results, but this is here for compatibility.

Returns:: List of NodeLocation objects
Return type:: list of NodeLocation

list_nodes(ex_zone=None, ex_use_disk_cache=True)[source]

Return a list of nodes in the current zone or all zones.

Parameters:

ex_zone (str or GCEZone or NodeLocation or None) – Optional zone name or ‘all’
ex_use_disk_cache (bool) – Disk information for each node will retrieved from a dictionary rather than making a distinct API call for it.

Returns:

List of Node objects

Return type:

list of Node

list_sizes(location=None)[source]

Return a list of sizes (machineTypes) in a zone.

Parameters:: location (str or GCEZone or NodeLocation or None) – Location or Zone for sizes
Returns:: List of GCENodeSize objects
Return type:: list of GCENodeSize

list_volume_snapshots(volume)[source]

List snapshots created from the provided volume.

For GCE, snapshots are global, but while the volume they were created from still exists, the source disk for the snapshot is tracked.

Parameters:: volume (StorageVolume) – A StorageVolume object
Returns:: A list of Snapshot objects
Return type:: list of GCESnapshot

list_volumes(ex_zone=None)[source]

Return a list of volumes for a zone or all.

Will return list from provided zone, or from the default zone unless given the value of ‘all’.

Parameters:: ex_zone (str or GCEZone or NodeLocation or None) – The zone to return volumes from.
Returns:: A list of volume objects.
Return type:: list of StorageVolume

reboot_node(node)[source]

Reboot a node.

Parameters:: node (Node) – Node to be rebooted
Returns:: True if successful, False if not
Return type:: bool

start_node(node, ex_sync=True)[source]

Start a node that is stopped and in TERMINATED state.

Parameters:

node (Node) – Node object to start
sync (bool) – If true, do not return until destroyed or timeout

Returns:

True if successful

Return type:

bool

stop_node(node, ex_sync=True)[source]

Stop a running node.

Parameters:

node (Node) – Node object to stop
sync (bool) – If true, do not return until destroyed or timeout

Returns:

True if successful

Return type:

bool

wait_until_running(nodes: List[Node], wait_period: float = 5, timeout: int = 600, ssh_interface: str = 'public_ips', force_ipv4: bool = True, ex_list_nodes_kwargs: Dict | None = None) → List[Tuple[Node, List[str]]]

Block until the provided nodes are considered running.

Node is considered running when it’s state is “running” and when it has at least one IP address assigned.

Parameters:

nodes (list of Node) – List of nodes to wait for.
wait_period (int) – How many seconds to wait between each loop iteration. (default is 3)
timeout (int) – How many seconds to wait before giving up. (default is 600)
ssh_interface (str) – Which attribute on the node to use to obtain an IP address. Valid options: public_ips, private_ips. Default is public_ips.
force_ipv4 (bool) – Ignore IPv6 addresses (default is True).
ex_list_nodes_kwargs (dict) – Optional driver-specific keyword arguments which are passed to the list_nodes method.

Returns:

[(Node, ip_addresses)] list of tuple of Node instance and list of ip_address on success.

Return type:

list of tuple