From 3b74dc2f6efb2775c07ee6c9262671e58098d651 Mon Sep 17 00:00:00 2001
From: Will Thames <will@thames.id.au>
Date: Thu, 12 Apr 2018 13:01:18 +1000
Subject: [PATCH] Improve aws_ec2 plugin documentation (#37689)

* Better formatting
* More examples
---
 lib/ansible/plugins/inventory/aws_ec2.py | 71 +++++++++++++-----------
 1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/lib/ansible/plugins/inventory/aws_ec2.py b/lib/ansible/plugins/inventory/aws_ec2.py
index 89b006cbd23..f379c50f588 100644
--- a/lib/ansible/plugins/inventory/aws_ec2.py
+++ b/lib/ansible/plugins/inventory/aws_ec2.py
@@ -56,39 +56,44 @@ DOCUMENTATION = '''
 '''
 
 EXAMPLES = '''
-simple_config_file:
-
-    plugin: aws_ec2
-    boto_profile: aws_profile
-    regions: # populate inventory with instances in these regions
-      - us-east-1
-      - us-east-2
-    filters:
-      # all instances with their `Environment` tag set to `dev`
-      tag:Environment: dev
-      # all dev and QA hosts
-      tag:Environment:
-        - dev
-        - qa
-      instance.group-id: sg-xxxxxxxx
-    # ignores 403 errors rather than failing
-    strict_permissions: False
-    hostnames:
-      - tag:Name=Tag1,Name=Tag2
-      - tag:CustomDNSName
-      - dns-name
-
-    # constructed features may be used to create custom groups
-    strict: False
-    keyed_groups:
-      - prefix: arch
-        key: 'architecture'
-        value: 'x86_64'
-      - prefix: tag
-        key: tags
-        value:
-          "Name": "Test"
-
+plugin: aws_ec2
+boto_profile: aws_profile
+regions: # populate inventory with instances in these regions
+  - us-east-1
+  - us-east-2
+filters:
+  # all instances with their `Environment` tag set to `dev`
+  tag:Environment: dev
+  # all dev and QA hosts
+  tag:Environment:
+    - dev
+    - qa
+  instance.group-id: sg-xxxxxxxx
+# ignores 403 errors rather than failing
+strict_permissions: False
+hostnames:
+  - tag:Name=Tag1,Name=Tag2  # return specific hosts only
+  - tag:CustomDNSName
+  - dns-name
+
+# keyed_groups may be used to create custom groups
+strict: False
+keyed_groups:
+  # add e.g. x86_64 hosts to an arch_x86_64 group
+  - prefix: arch
+    key: 'architecture'
+  # add hosts to tag_Name_Value groups for each Name/Value tag pair
+  - prefix: tag
+    key: tags
+  # add hosts to e.g. instance_type_z3_tiny
+  - prefix: instance_type
+    key: instance_type
+  # create security_groups_sg_abcd1234 group for each SG
+  - key: 'security_groups|json_query("[].group_id")'
+    prefix: 'security_groups'
+  # create a group for each value of the Application tag
+  - key: tag.Application
+    separator: ''
 '''
 
 from ansible.errors import AnsibleError, AnsibleParserError