Repository: ansible/ansible-modules-core

Issue:
Bad documentation example in gce module
This is the example I'm following, but I end up with different results. You can see below most of the playbook works out fine except for the part when Ansible comes in to do it's magic. For some reason the host cannot be found.

┌─┤[james@xps13-nocentre-net:~/workspace/github/ansible][3.18.8-201.fc21.x86_64 10:51:10]├────── ── ─ 
└[feature/elk] $ ansible-playbook playbooks/plays/gce/elk.yml -i inventory/hosts_production                                                                                                            

```
PLAY [Google Cloud Procurement] *********************************************** 

TASK: [gce] ******************************************************************* 
ok: [localhost -> 127.0.0.1]

TASK: [set_fact public_ip={{gce.instance_data[0].public_ip}}] ***************** 
ok: [localhost]

TASK: [set_fact private_ip={{gce.instance_data[0].private_ip}}] *************** 
ok: [localhost]

TASK: [set_fact ansible_ssh_host={{public_ip}}] ******************************* 
ok: [localhost]

TASK: [debug msg="{{gce}}"] *************************************************** 
ok: [localhost] => {
    "msg": "{u'instance_data': [{u'status': u'RUNNING', u'name': u'elk-stage-uscentral1a-kernelfire-com', u'zone': u'us-central1-a', u'tags': [], u'image': None, u'disks': [u'elk-stage-uscentral1a-kernelfire-com', u'elk-data-stage-uscentral1a-kernelfire-com'], u'public_ip': u'130.211.122.65', u'private_ip': u'10.240.178.66', u'machine_type': u'n1-standard-4', u'metadata': {}, u'network': u'default'}], u'name': u'elk-stage-uscentral1a-kernelfire-com', u'zone': u'us-central1-a', u'changed': False, u'state': u'present', 'invocation': {'module_name': u'gce', 'module_args': ''}}"
}

TASK: [Wait for SSH to come up] *********************************************** 
ok: [localhost -> 127.0.0.1] => (item={u'status': u'RUNNING', u'network': u'default', u'zone': u'us-central1-a', u'tags': [], u'image': None, u'disks': [u'elk-stage-uscentral1a-kernelfire-com', u'elk-data-stage-uscentral1a-kernelfire-com'], u'public_ip': u'130.211.122.65', u'private_ip': u'10.240.178.66', u'machine_type': u'n1-standard-4', u'metadata': {}, u'name': u'elk-stage-uscentral1a-kernelfire-com'})

TASK: [gce_pd] **************************************************************** 
ok: [localhost -> 127.0.0.1]

TASK: [set_fact gce_pd_name={{gce_pd.name}}] ********************************** 
ok: [localhost]

TASK: [debug msg="{{gce_pd}}"] ************************************************ 
ok: [localhost] => {
    "msg": "{u'size_gb': 100, u'name': u'elk-data-stage-uscentral1a-kernelfire-com', u'zone': u'us-central1-a', u'changed': False, u'state': u'present', u'attached_to_instance': u'elk-stage-uscentral1a-kernelfire-com', 'invocation': {'module_name': u'gce_pd', 'module_args': ''}, u'disk_type': u'pd-ssd', u'attached_mode': u'READ_WRITE'}"
}

TASK: [debug msg="{{gce_pd_name}}"] ******************************************* 
ok: [localhost] => {
    "msg": "elk-data-stage-uscentral1a-kernelfire-com"
}

PLAY [Ansible Provisioning] *************************************************** 
skipping: no hosts matched

PLAY RECAP ******************************************************************** 
localhost                  : ok=10   changed=0    unreachable=0    failed=0   
```

============= PLAYBOOK ==============

```
- name: Google Cloud Procurement
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
  - local_action:
      module: gce
      image: centos-6
      machine_type: n1-standard-4
      name: elk-stage-uscentral1a-kernelfire-com
      persistent_boot_disk: true
      project_id: cf-stage
      zone: us-central1-a
    register: gce
  - set_fact: public_ip={{gce.instance_data[0].public_ip}}
  - set_fact: private_ip={{gce.instance_data[0].private_ip}}
  - set_fact: ansible_ssh_host={{public_ip}}
  - debug: msg="{{gce}}"

  - name: Wait for SSH to come up
    local_action: wait_for host={{item.public_ip}} port=22 delay=10 timeout=60 state=started
    with_items: "{{gce.instance_data}}"

  - local_action:
      module: gce_pd
      disk_type: pd-ssd
      instance_name: "{{gce.instance_data[0].name}}"
      mode: READ_WRITE
      name: elk-data-stage-uscentral1a-kernelfire-com
      project_id: cf-stage
      size_gb: 100
      zone: us-central1-a
    register: gce_pd
  - set_fact: gce_pd_name={{gce_pd.name}}
  - debug: msg="{{gce_pd}}"
  - debug: msg="{{gce_pd_name}}"

- name: Ansible Provisioning
  hosts: launched
  sudo: true
  roles:
  - { role: elasticsearch, tags: [ 'extended', 'elasticsearch' ] }
  - { role: redis, tags: [ 'extended', 'redis' ] }
  - { role: logstash, tags: [ 'extended', 'logstash' ] }
  - { role: kibana, tags: [ 'extended', 'kibana' ] }
```

Any ideas?



Discussion:
you might want to include an "add_hosts" task to put the new hosts into the 'launched' group

@erjohnso, ping. This issue is still waiting on your response.
[click here for bot help](https://github.com/jctanner/ansibullbot/blob/ISSUE_TRIAGE_CLASS/ISSUE_HELP.md)

<!--- boilerplate: issue_renotify_maintainer --->

/cc @supertom

@supertom, ping. This issue is still waiting on your response.
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)

<!--- boilerplate: issue_renotify_maintainer --->

@supertom, ping. This issue is still waiting on your response.
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)

<!--- boilerplate: issue_renotify_maintainer --->


Resolving patch:
diff --git a/cloud/google/gce.py b/cloud/google/gce.py
--- a/cloud/google/gce.py
+++ b/cloud/google/gce.py
@@ -23,7 +23,7 @@
 short_description: create or terminate GCE instances
 description:
      - Creates or terminates Google Compute Engine (GCE) instances.  See
-       U(https://cloud.google.com/products/compute-engine) for an overview.
+       U(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.
 options:
@@ -89,7 +89,8 @@
     default: null
   name:
     description:
-      - identifier when working with a single instance
+      - identifier when working with a single instance.  Will be deprecated in a future release.
+        Please 'instance_names' instead.
     required: false
   network:
     description:
@@ -164,96 +165,107 @@
     - "apache-libcloud >= 0.13.3, >= 0.17.0 if using JSON credentials,
       >= 0.20.0 if using preemptible option"
 notes:
-  - Either I(name) or I(instance_names) is required.
-author: "Eric Johnson (@erjohnso) <erjohnso@google.com>"
+  - Either I(instance_names) or I(name) is required.
+  - JSON credentials strongly preferred.
+author: "Eric Johnson (@erjohnso) <erjohnso@google.com>, Tom Melendez (@supertom) <supertom@google.com>"
 '''
 
 EXAMPLES = '''
-# Basic provisioning example.  Create a single Debian 7 instance in the
-# us-central1-a Zone of n1-standard-1 machine type.
-- local_action:
-    module: gce
-    name: test-instance
-    zone: us-central1-a
-    machine_type: n1-standard-1
-    image: debian-7
-
-# Example using defaults and with metadata to create a single 'foo' instance
-- local_action:
-    module: gce
-    name: foo
-    metadata: '{"db":"postgres", "group":"qa", "id":500}'
-
-
-# Launch instances from a control node, runs some tasks on the new instances,
-# and then terminate them
-# This example uses JSON credentials with the credentials_file parameter
-# rather than the deprecated pem_file option with PEM formatted credentials.
-
-- name: Create a sandbox instance
+# 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: "your-sa@your-project-name.iam.gserviceaccount.com"
+      credentials_file: "/path/to/your-key.json"
+      project_id: "your-project-name"
+
+# 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: "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:
-    names: foo,bar
-    machine_type: n1-standard-1
-    image: debian-6
-    zone: us-central1-a
-    service_account_email: unique-email@developer.gserviceaccount.com
-    credentials_file: /path/to/json_file
-    project_id: project-id
+    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: Launch instances
-      local_action: gce instance_names={{names}} machine_type={{machine_type}}
-                    image={{image}} zone={{zone}}
-                    service_account_email={{ service_account_email }}
-                    credentials_file={{ credentials_file }}
-                    project_id={{ project_id }}
+    - 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: Wait for SSH to come up
-      local_action: wait_for host={{item.public_ip}} port=22 delay=10
-                    timeout=60 state=started
-      with_items: {{gce.instance_data}}
-
-- name: Configure instance(s)
-  hosts: launched
-  become: True
-  roles:
-    - my_awesome_role
-    - my_awesome_tasks
-
-- name: Terminate instances
-  hosts: localhost
-  connection: local
-  tasks:
-    - name: Terminate instances that were previously launched
-      local_action:
-        module: gce
-        state: 'absent'
-        instance_names: {{gce.instance_names}}
-
-# The deprecated PEM file credentials can be used as follows
-- name: Create a sandbox instance with PEM credentials
-  hosts: localhost
-  vars:
-    names: foo,bar
-    machine_type: n1-standard-1
-    image: debian-6
-    zone: us-central1-a
-    service_account_email: unique-email@developer.gserviceaccount.com
-    pem_file: /path/to/pem_file
-    project_id: project-id
-  tasks:
-    - name: Launch instances
-      local_action: gce instance_names={{names}} machine_type={{machine_type}}
-                    image={{image}} zone={{zone}}
-                    service_account_email={{ service_account_email }}
-                    pem_file={{ pem_file }}
-                    project_id={{ project_id }}
-      register: gce
-    - name: Wait for SSH to come up
-      local_action: wait_for host={{item.public_ip}} port=22 delay=10
-                    timeout=60 state=started
-      with_items: {{gce.instance_data}}
 
+    - 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
 '''
 
 import socket


Test patch: