Repository: ansible/ansible

Issue:
Clarify generated documentation on route table removal in ec2_vpc_route_table.py

##### ISSUE TYPE
 - Documentation Report

##### COMPONENT NAME
modules/cloud/amazon/ec2_vpc_route_table.py

##### ANSIBLE VERSION
```
ansible 2.3.0 (devel 6b1586748f) last updated 2016/12/09 15:51:08 (GMT -400)
  config file = /etc/ansible/ansible.cfg
  configured module search path = Default w/o overrides
```

##### CONFIGURATION
Default w/AWS related environment variables set

##### OS / ENVIRONMENT
OS X 10.10.5 w/Python 2.7.11

##### SUMMARY
Trying to delete a VPC route table via "state:absent" when only specifying the vpc_id and route_table_id parameters fails to remove the route table.

As it turns out, you also need to specify the arguments "lookup: id" to the module invocation. Once this is done, the route table will be removed. The documentation doesn't specifically indicate this, so it would be good to add language showing the dependency.

##### STEPS TO REPRODUCE

Sample play that fails:

```
- name: Delete AZ1 private route table
  ec2_vpc_route_table:
    state: absent
    vpc_id: "{{ vpc_id }}"
    route_table_id: "{{ private_rt_az1_id }}"
```

Sample play that succeeds:

```
- name: Delete AZ1 private route table
  ec2_vpc_route_table:
    state: absent
    vpc_id: "{{ vpc_id }}"
    route_table_id: "{{ private_rt_az1_id }}"
    lookup: "id"
```

##### EXPECTED RESULTS

Route table is removed.

##### ACTUAL RESULTS

Route table is not removed.

Note that "changed" = "false"

```
TASK [aws-vpc-scenario2 : Delete AZ1 private route table] ******************************************************************************************************
task path: /Users/rcrelia/code/ansible/roles/aws-vpc-scenario2/tasks/delete.yml:82
Using module file /Users/rcrelia/ansible/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py
<localhost> ESTABLISH LOCAL CONNECTION FOR USER: rcrelia
<localhost> EXEC /bin/sh -c '( umask 77 && mkdir -p "` echo ~/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601 `" && echo ansible-tmp-1481726021.49-28159386640601="` echo ~/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601 `" ) && sleep 0'
<localhost> PUT /var/folders/pt/ltft6_rx1d79hkkzq6s56jnm0000gn/T/tmpptRzQx TO /Users/rcrelia/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601/ec2_vpc_route_table.py
<localhost> EXEC /bin/sh -c 'chmod u+x /Users/rcrelia/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601/ /Users/rcrelia/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601/ec2_vpc_route_table.py && sleep 0'
<localhost> EXEC /bin/sh -c 'python /Users/rcrelia/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601/ec2_vpc_route_table.py; rm -rf "/Users/rcrelia/.ansible/tmp/ansible-tmp-1481726021.49-28159386640601/" > /dev/null 2>&1 && sleep 0'
ok: [localhost] => {
    "changed": false,
    "invocation": {
        "module_args": {
            "aws_access_key": null,
            "aws_secret_key": null,
            "ec2_url": null,
            "lookup": "tag",
            "profile": null,
            "propagating_vgw_ids": null,
            "region": null,
            "route_table_id": "rtb-xxxxxxxx",
            "routes": [],
            "security_token": null,
            "state": "absent",
            "subnets": null,
            "tags": null,
            "validate_certs": true,
            "vpc_id": "vpc-xxxxxxxx"
        },
        "module_name": "ec2_vpc_route_table"
    }
}
```

Once the { lookup: "id" } parameter is specified in the ec2_vpc_route_table invocation, the route table deletion succeeds:

```
TASK [aws-vpc-scenario2 : Delete AZ1 private route table] ******************************************************************************************************
task path: /Users/rcrelia/code/ansible/roles/aws-vpc-scenario2/tasks/delete.yml:90
Using module file /Users/rcrelia/ansible/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py
<localhost> ESTABLISH LOCAL CONNECTION FOR USER: rcrelia
<localhost> EXEC /bin/sh -c '( umask 77 && mkdir -p "` echo ~/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792 `" && echo ansible-tmp-1481727942.24-177848199261792="` echo ~/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792 `" ) && sleep 0'
<localhost> PUT /var/folders/pt/ltft6_rx1d79hkkzq6s56jnm0000gn/T/tmpJz7NW1 TO /Users/rcrelia/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792/ec2_vpc_route_table.py
<localhost> EXEC /bin/sh -c 'chmod u+x /Users/rcrelia/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792/ /Users/rcrelia/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792/ec2_vpc_route_table.py && sleep 0'
<localhost> EXEC /bin/sh -c 'python /Users/rcrelia/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792/ec2_vpc_route_table.py; rm -rf "/Users/rcrelia/.ansible/tmp/ansible-tmp-1481727942.24-177848199261792/" > /dev/null 2>&1 && sleep 0'
changed: [localhost] => {
    "changed": true,
    "invocation": {
        "module_args": {
            "aws_access_key": null,
            "aws_secret_key": null,
            "ec2_url": null,
            "lookup": "id",
            "profile": null,
            "propagating_vgw_ids": null,
            "region": null,
            "route_table_id": "rtb-xxxxxxx",
            "routes": [],
            "security_token": null,
            "state": "absent",
            "subnets": null,
            "tags": null,
            "validate_certs": true,
            "vpc_id": "vpc-xxxxxxxx"
        },
        "module_name": "ec2_vpc_route_table"
    }
}
```




Discussion:
cc @erydo, @wimnat
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->

Resolving patch:
diff --git a/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py b/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py
--- a/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py
+++ b/lib/ansible/modules/cloud/amazon/ec2_vpc_route_table.py
@@ -30,7 +30,8 @@
     description:
       - "Look up route table by either tags or by route table ID. Non-unique tag lookup will fail.
         If no tags are specifed then no lookup for an existing route table is performed and a new
-        route table will be created. To change tags of a route table, you must look up by id."
+        route table will be created. To change tags of a route table or delete a route table,
+        you must look up by id."
     required: false
     default: tag
     choices: [ 'tag', 'id' ]
@@ -294,7 +295,7 @@ def get_route_table_by_tags(vpc_conn, vpc_id, tags):
         this_tags = get_resource_tags(vpc_conn, table.id)
         if tags_match(tags, this_tags):
             route_table = table
-            count +=1
+            count += 1
 
     if count > 1:
         raise RuntimeError("Tags provided do not identify a unique route table")
@@ -426,7 +427,7 @@ def ensure_subnet_associations(vpc_conn, vpc_id, route_table, subnets,
 
     if purge_subnets:
         to_delete = [a_id for a_id in current_association_ids
-                 if a_id not in new_association_ids]
+                     if a_id not in new_association_ids]
 
         for a_id in to_delete:
             changed = True
@@ -503,10 +504,10 @@ def get_route_table_info(route_table):
     for route in route_table.routes:
         routes.append(route.__dict__)
 
-    route_table_info = { 'id': route_table.id,
-                         'routes': routes,
-                         'tags': route_table.tags,
-                         'vpc_id': route_table.vpc_id }
+    route_table_info = {'id': route_table.id,
+                        'routes': routes,
+                        'tags': route_table.tags,
+                        'vpc_id': route_table.vpc_id}
 
     return route_table_info
 
@@ -618,16 +619,16 @@ def main():
     argument_spec = ec2_argument_spec()
     argument_spec.update(
         dict(
-            lookup = dict(default='tag', required=False, choices=['tag', 'id']),
-            propagating_vgw_ids = dict(default=None, required=False, type='list'),
+            lookup=dict(default='tag', required=False, choices=['tag', 'id']),
+            propagating_vgw_ids=dict(default=None, required=False, type='list'),
             purge_routes=dict(default=True, type='bool'),
             purge_subnets=dict(default=True, type='bool'),
-            route_table_id = dict(default=None, required=False),
-            routes = dict(default=[], required=False, type='list'),
-            state = dict(default='present', choices=['present', 'absent']),
-            subnets = dict(default=None, required=False, type='list'),
-            tags = dict(default=None, required=False, type='dict', aliases=['resource_tags']),
-            vpc_id = dict(default=None, required=True)
+            route_table_id=dict(default=None, required=False),
+            routes=dict(default=[], required=False, type='list'),
+            state=dict(default='present', choices=['present', 'absent']),
+            subnets=dict(default=None, required=False, type='list'),
+            tags=dict(default=None, required=False, type='dict', aliases=['resource_tags']),
+            vpc_id=dict(default=None, required=True)
         )
     )
 


Test patch: