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.

../../_images/gcp.png

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.

  1. Follow the instructions at https://developers.google.com/console/help/new/#serviceaccounts to create and download the private key.

    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

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

  3. 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.

Installed Application

To set up Installed Account authentication:

  1. Go to the Google Developers Console
  2. Select your project
  3. In the left sidebar, go to “APIs & auth”
  4. Click on “Credentials” then “Create New Client ID”
  5. Select “Installed application” and “Other” then click “Create Client ID”
  6. For authentication, you will need the “Client ID” and the “Client Secret”
  7. 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

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

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')

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',
                       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')

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, node_image, name, description=None)

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, name, description=None)

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)

Create a new key pair object.

Parameters:name (str) – Key pair name.
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', 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)[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.
  • 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.
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)

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)

Delete an existing key pair.

Parameters:key_pair (KeyPair) – Key pair object.
deploy_node(name, size, image, script, location=None, ex_network='default', ex_tags=None, ex_service_accounts=None)[source]

Create a new node and run a script on start-up.

Parameters:
  • name (str) – The name of the node to create.
  • size (str or GCENodeSize) – The machine type to use.
  • image (str or GCENodeImage) – The image to use to create the node.
  • script (str) – File path to start-up script
  • 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_tags (list of str or None) – A list of tags to associate with the node.
  • 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’.
Returns:

A Node object for the new node.

Return type:

Node

destroy_node(node, destroy_boot_disk=False)[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.)
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 – The URL to the image. The URL can start with gs://
  • urlstr
  • description (str) – The description of the image
  • family (str) – The family of the image
  • guest_os_features (list of dict 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)[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 or None) – Optional descriptive comment.
Returns:

Static Address object

Return type:

GCEAddress

ex_create_backendservice(name, healthchecks)[source]

Create a global backend service.

Parameters:
  • name (str) – Name of the backend service
  • healthchecks (list of (str or GCEHealthCheck)) – A list of HTTP Health Checks to use for this service. There must be at least one.
Returns:

A Backend Service object

Return type:

GCEBackendService

ex_create_firewall(name, allowed, network='default', source_ranges=None, source_tags=None, target_tags=None)[source]

Create a firewall on a network.

Firewall rules should be supplied in the “allowed” field. This is a list of dictionaries formated 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"}]

See Firewall Reference for more information.

Parameters:
  • name (str) – Name of the firewall to be created
  • allowed (list of dict) – List of dictionaries with rules
  • 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_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.
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)[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.
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)[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.
  • 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
Keywork guest_os_features:
 

Features of the guest operating system, valid for bootable images only. Possible values include ‘VIRTIO_SCSI_MULTIQUEUE’ if specified.

Returns:

A GCENodeImage object for the new image

Return type:

GCENodeImage

ex_create_multiple_nodes(base_name, size, image, number, location=None, ex_network='default', ex_tags=None, ex_metadata=None, ignore_errors=True, use_existing_disk=True, poll_interval=2, external_ip='ephemeral', 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)[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.)
  • 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_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.
Returns:

A list of Node objects for the new nodes.

Return type:

list of Node

ex_create_network(name, cidr, description=None, mode='legacy')[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.
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 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_subnetwork(name, cidr=None, network=None, region=None, description=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.
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_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 (str) – The existing target Node (instance) for the request.
  • name – 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_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_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_subnetwork(name, region=None)[source]

Delete a Subnetwork object based on name and region.

Parameters:
  • name (str or GCERegion or None) – The name, URL or object of the subnetwork
  • name – 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_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_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_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 – 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 – 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_license(project, name)[source]

Return a License object for specified project and name.

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

A DiskType object for the name

Return type:

GCEDiskType

ex_get_network(name)[source]

Return a Network object based on a network name.

Parameters:name (str) – The name 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_subnetwork(name, region=None)[source]

Return a Subnetwork object based on name and region.

Parameters:
  • name (str or GCERegion or None) – The name or URL of the subnetwork
  • name – 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_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)[source]

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

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)
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_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_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_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_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_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_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_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_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_start_node(node)[source]

Start a node that is stopped and in TERMINATED state.

Parameters:node (Node) – Node object to start
Returns:True if successful
Return type:bool
ex_stop_node(node)[source]

Stop a running node.

Parameters:node (Node) – Node object to stop
Returns:True if successful
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_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
get_image(image_id)

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)

Retrieve a single key pair.

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

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, key_material)

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 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)[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’
Returns:List of Node objects
Return type:list of Node
list_regions()

Method which returns a list of the available / supported regions.

Return type:list of str
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
wait_until_running(nodes, wait_period=3, timeout=600, ssh_interface='public_ips', force_ipv4=True, ex_list_nodes_kwargs=None)

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