gce – create or terminate GCE instances¶
DEPRECATED¶
| Removed in Ansible: | |
|---|---|
| version: 2.12 | |
| Why: | Updated modules released with increased functionality | 
| Alternative: | Use gcp_compute_instance instead. | 
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¶
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 
                    -
                                                                 | path to the JSON file associated with the service account email | |
| disk_auto_delete 
                    boolean
                                                                 | 
 | if set boot disk will be removed after instance destruction | 
| disk_size 
                    -
                                                                 | Default: 10 | The size of the boot disk created for this instance (in GB) | 
| disks 
                    -
                                                                 | 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 
                    -
                                                                 | 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 
                    boolean
                                                                 | 
 | set to  yesif 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 
                    -
                                                                 | can be used with 'name', specifies the number of nodes to provision using 'name' as a base name | |
| pem_file 
                    -
                                                                 | path to the pem file associated with the service account email This option is deprecated. Use 'credentials_file'. | |
| persistent_boot_disk 
                    boolean
                                                                 | 
 | if set, create the instance with a persistent boot disk | 
| preemptible 
                    boolean
                                                                 | 
 | if set to  yes, instances will be preemptible and time-limited. (requires libcloud >= 0.20.0) | 
| project_id 
                    -
                                                                 | your GCE project ID | |
| service_account_email 
                    -
                                                                 | service account email | |
| service_account_permissions 
                    -
                                                                 | 
 | service account permissions (see https://cloud.google.com/sdk/gcloud/reference/compute/instances/create, --scopes section for detailed information) | 
| state 
                    -
                                                                 | 
 | desired state of the resource | 
| subnetwork 
                    -
                                                                 | 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. | 
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: "your-sa@your-project-name.iam.gserviceaccount.com"
      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: "your-sa@your-project-name.iam.gserviceaccount.com"
      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: "your-sa@your-project-name.iam.gserviceaccount.com"
      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: "your-sa@your-project-name.iam.gserviceaccount.com"
    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 will be removed in version 2.12. [deprecated]
- For more information see DEPRECATED.
Authors¶
- Eric Johnson (@erjohnso) <erjohnso@google.com>
- Tom Melendez (@supertom) <supertom@google.com>
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
