Documentation

gce - create or terminate GCE instances

New in version 1.4.

Synopsis

  • Creates or terminates Google Compute Engine (GCE) instances. See https://cloud.google.com/compute for an overview. Full install/configuration instructions for the gce* modules can be found in the comments of ansible/test/gce_tests.py.

Requirements (on host that executes module)

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

Options

parameter required default choices comments
credentials_file
(added in 2.1.0)
no
path to the JSON file associated with the service account email
disk_auto_delete
(added in 1.9)
no true
if set boot disk will be removed after instance destruction
disk_size
(added in 2.3)
no 10
The size of the boot disk created for this instance (in GB)
disks
(added in 1.7)
no
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)
no 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.
image
no debian-8
image string to use for the instance (default will follow latest stable debian image)
instance_names
no
a comma-separated list of instance names to create or destroy
ip_forward
(added in 1.9)
no false
set to true if the instance can forward ip packets (useful for gateways)
machine_type
no n1-standard-1
machine type to use for the instance, use 'n1-standard-1' by default
metadata
no
a hash/dictionary of custom data for the instance; '{"key":"value", ...}'
name
no
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
no default
name of the network, 'default' will be used if not specified
num_instances
(added in 2.3)
no
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)
no
path to the pem file associated with the service account email This option is deprecated. Use 'credentials_file'.
persistent_boot_disk
no false
if set, create the instance with a persistent boot disk
preemptible
(added in 2.1)
no false
if set to true, instances will be preemptible and time-limited. (requires libcloud >= 0.20.0)
project_id
(added in 1.5.1)
no
your GCE project ID
service_account_email
(added in 1.5.1)
no
service account email
service_account_permissions
(added in 2.0)
no
  • 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
no present
  • active
  • present
  • absent
  • deleted
  • started
  • stopped
  • terminated
desired state of the resource
subnetwork
(added in 2.2)
no
name of the subnetwork in which the instance should be created
tags
no
a comma-separated list of tags to associate with the instance
zone
yes 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.

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, seperated 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 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
      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

Notes

Note

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

Status

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

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.