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

                                            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, Helping Testing PRs and Developing Modules.