gce - create or terminate GCE instances

New in version 1.4.

Synopsis

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6
  • apache-libcloud >= 0.13.3, >= 0.17.0 if using JSON credentials, >= 0.20.0 if using preemptible option

Parameters

Parameter Choices/Defaults Comments
credentials_file
(added in 2.1.0)
path to the JSON file associated with the service account email
disk_auto_delete
bool

(added in 1.9)
    Choices:
  • no
  • yes ←
if set boot disk will be removed after instance destruction
disk_size
(added in 2.3)
 Default:
10
The size of the boot disk created for this instance (in GB)
disks
(added in 1.7)
a list of persistent disks to attach to the instance; a string value gives the name of the disk; alternatively, a dictionary value can define 'name' and 'mode' ('READ_ONLY' or 'READ_WRITE'). The first entry will be the boot disk (which must be READ_WRITE).
external_ip
(added in 1.9)
 Default:
ephemeral
type of external ip, ephemeral by default; alternatively, a fixed gce ip or ip name can be given. Specify 'none' if no external ip is desired.
external_projects
(added in 2.4)
A list of other projects (accessible with the provisioning credentials) to be searched for the image.
image Default:
debian-8
image string to use for the instance (default will follow latest stable debian image)
image_family
(added in 2.4)
image family from which to select the image. The most recent non-deprecated image in the family will be used.
instance_names
a comma-separated list of instance names to create or destroy
ip_forward
bool

(added in 1.9)
    Choices:
  • no ←
  • yes
set to yes if the instance can forward ip packets (useful for gateways)
machine_type Default:
n1-standard-1
machine type to use for the instance, use 'n1-standard-1' by default
metadata
a hash/dictionary of custom data for the instance; '{"key":"value", ...}'
name
either a name of a single instance or when used with 'num_instances', the base name of a cluster of nodes

aliases: base_name
network Default:
default
name of the network, 'default' will be used if not specified
num_instances
(added in 2.3)
can be used with 'name', specifies the number of nodes to provision using 'name' as a base name
pem_file
(added in 1.5.1)
path to the pem file associated with the service account email This option is deprecated. Use 'credentials_file'.
persistent_boot_disk
bool
    Choices:
  • no ←
  • yes
if set, create the instance with a persistent boot disk
preemptible
bool

(added in 2.1)
    Choices:
  • no ←
  • yes
if set to yes, instances will be preemptible and time-limited. (requires libcloud >= 0.20.0)
project_id
(added in 1.5.1)
your GCE project ID
service_account_email
(added in 1.5.1)
service account email
service_account_permissions
(added in 2.0)
    Choices:
  • bigquery
  • cloud-platform
  • compute-ro
  • compute-rw
  • useraccounts-ro
  • useraccounts-rw
  • datastore
  • logging-write
  • monitoring
  • sql-admin
  • storage-full
  • storage-ro
  • storage-rw
  • taskqueue
  • userinfo-email
service account permissions (see https://cloud.google.com/sdk/gcloud/reference/compute/instances/create, --scopes section for detailed information)
state
    Choices:
  • active
  • present ←
  • absent
  • deleted
  • started
  • stopped
  • terminated
desired state of the resource
subnetwork
(added in 2.2)
name of the subnetwork in which the instance should be created
tags
a comma-separated list of tags to associate with the instance
zone
required
 Default:
us-central1-a
the GCE zone to use. The list of available zones is at https://cloud.google.com/compute/docs/regions-zones/regions-zones#available.

Notes

Note

  • Either instance_names or name is required.
  • JSON credentials strongly preferred.

Examples

# Basic provisioning example.  Create a single Debian 8 instance in the
# us-central1-a Zone of the n1-standard-1 machine type.
# Create multiple instances by specifying multiple names, separated by
# commas in the instance_names field
# (e.g. my-test-instance1,my-test-instance2)
  - gce:
      instance_names: my-test-instance1
      zone: us-central1-a
      machine_type: n1-standard-1
      image: debian-8
      state: present
      service_account_email: "[email protected]"
      credentials_file: "/path/to/your-key.json"
      project_id: "your-project-name"
      disk_size: 32

# Create a single instance of an image from the "my-base-image" image family
# in the us-central1-a Zone of the n1-standard-1 machine type.
# This image family is in the "my-other-project" GCP project.
  - gce:
      instance_names: my-test-instance1
      zone: us-central1-a
      machine_type: n1-standard-1
      image_family: my-base-image
      external_projects:
        - my-other-project
      state: present
      service_account_email: "[email protected]"
      credentials_file: "/path/to/your-key.json"
      project_id: "your-project-name"
      disk_size: 32

# Create a single Debian 8 instance in the us-central1-a Zone
# Use existing disks, custom network/subnetwork, set service account permissions
# add tags and metadata.
  - gce:
      instance_names: my-test-instance
      zone: us-central1-a
      machine_type: n1-standard-1
      state: present
      metadata: '{"db":"postgres", "group":"qa", "id":500}'
      tags:
        - http-server
        - my-other-tag
      disks:
        - name: disk-2
          mode: READ_WRITE
        - name: disk-3
          mode: READ_ONLY
      disk_auto_delete: false
      network: foobar-network
      subnetwork: foobar-subnetwork-1
      preemptible: true
      ip_forward: true
      service_account_permissions:
        - storage-full
        - taskqueue
        - bigquery
        - https://www.googleapis.com/auth/ndev.clouddns.readwrite
      service_account_email: "[email protected]"
      credentials_file: "/path/to/your-key.json"
      project_id: "your-project-name"

---
# Example Playbook
- name: Compute Engine Instance Examples
  hosts: localhost
  vars:
    service_account_email: "[email protected]"
    credentials_file: "/path/to/your-key.json"
    project_id: "your-project-name"
  tasks:
    - name: create multiple instances
      # Basic provisioning example.  Create multiple Debian 8 instances in the
      # us-central1-a Zone of n1-standard-1 machine type.
      gce:
        instance_names: test1,test2,test3
        zone: us-central1-a
        machine_type: n1-standard-1
        image: debian-8
        state: present
        service_account_email: "{{ service_account_email }}"
        credentials_file: "{{ credentials_file }}"
        project_id: "{{ project_id }}"
        metadata : '{ "startup-script" : "apt-get update" }'
      register: gce

    - name: Save host data
      add_host:
        hostname: "{{ item.public_ip }}"
        groupname: gce_instances_ips
      with_items: "{{ gce.instance_data }}"

    - name: Wait for SSH for instances
      wait_for:
        delay: 1
        host: "{{ item.public_ip }}"
        port: 22
        state: started
        timeout: 30
      with_items: "{{ gce.instance_data }}"

    - name: Configure Hosts
      hosts: gce_instances_ips
      become: yes
      become_method: sudo
      roles:
        - my-role-one
        - my-role-two
      tags:
        - config

    - name: delete test-instances
      # Basic termination of instance.
      gce:
        service_account_email: "{{ service_account_email }}"
        credentials_file: "{{ credentials_file }}"
        project_id: "{{ project_id }}"
        instance_names: "{{ gce.instance_names }}"
        zone: us-central1-a
        state: absent
      tags:
        - delete

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

Hint

If you notice any issues in this documentation you can edit this document to improve it.