Add documentation for the aws_ssm lookup plugin. (#32763)

lib/ansible/plugins/lookup/aws_ssm.py

@@ -6,53 +6,89 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible.module_utils.ec2 import HAS_BOTO3
+DOCUMENTATION = '''
-from ansible.errors import AnsibleError
+    lookup: aws_ssm
-from ansible.plugins.lookup import LookupBase
+    author:
-from ansible.module_utils.parsing.convert_bool import boolean
+      - Bill Wang <ozbillwang(at)gmail.com>
-
+      - Marat Bakeev <hawara(at)gmail.com>
-try:
+    version_added: 2.5
-    from botocore.exceptions import ClientError
+    short_description: Get the value for a SSM parameter.
-    import boto3
+    description:
-except ImportError:
+      - Get the value for an Amazon Simple Systems Manager parameter or a heirarchy of parameters. The first
-    pass  # will be captured by imported HAS_BOTO3
+        argument you pass the lookup can either be a parameter name or a hierarchy of parameters. Hierarchies start
-
+        with a forward slash and end with the parameter name. Up to 5 layers may be specified.
-
+    options:
-class LookupModule(LookupBase):
+      aws_profile:
-    def run(self, terms, variables, **kwargs):
+        description: The boto profile to use. You may use environment variables or the default profile as an alternative.
-        '''
+      region:
-        # lookup sample:
+        description: The region to use. You may use environment variables ar the default profile's region as an alternative.
-        - name: lookup ssm parameter store in the current region
+      decrypt:
+        description: A boolean to indicate whether to decrypt the parameter.
+        default: false
+      bypath:
+        description: A boolean to indicate whether the parameter is provided as a hierarchy.
+        default: false
+      recursive:
+        description: A boolean to indicate whether to retrieve all parameters within a hierarchy.
+        default: false
+      shortnames:
+        description: Indicates whether to return the shortened name if using a parameter hierarchy.
+        default: false
+'''
+
+EXAMPLES = '''
+# lookup sample:
+- name: lookup ssm parameter store in the current region
   debug: msg="{{ lookup('aws_ssm', 'Hello' ) }}"
 
-        - name: lookup a key which doesn't exist, return ""
+- name: lookup a key which doesn't exist, returns ""
   debug: msg="{{ lookup('aws_ssm', 'NoKey') }}"
 
-        - name: lookup ssm parameter store in nominated region
+- name: lookup ssm parameter store in nominated region
   debug: msg="{{ lookup('aws_ssm', 'Hello', 'region=us-east-2' ) }}"
 
-        - name: lookup ssm parameter store without decrypted
+- name: lookup ssm parameter store without decrypted
   debug: msg="{{ lookup('aws_ssm', 'Hello', 'decrypt=False' ) }}"
 
-        - name: lookup ssm parameter store in nominated aws profile
+- name: lookup ssm parameter store in nominated aws profile
   debug: msg="{{ lookup('aws_ssm', 'Hello', 'aws_profile=myprofile' ) }}"
 
-        - name: lookup ssm parameter store with all options.
+- name: lookup ssm parameter store with all options.
   debug: msg="{{ lookup('aws_ssm', 'Hello', 'decrypt=false', 'region=us-east-2', 'aws_profile=myprofile') }}"
 
-        - name: return a dictionary of ssm parameters from a hierarchy path
+- name: return a dictionary of ssm parameters from a hierarchy path
   debug: msg="{{ lookup('aws_ssm', '/PATH/to/params', 'region=ap-southeast-2', 'bypath', 'recursive=true' ) }}"
 
-        - name: return a dictionary of ssm parameters from a hierarchy path with shortened names (param instead of /PATH/to/param)
+- name: return a dictionary of ssm parameters from a hierarchy path with shortened names (param instead of /PATH/to/param)
   debug: msg="{{ lookup('aws_ssm', '/PATH/to/params', 'region=ap-southeast-2', 'shortnames', 'bypath', 'recursive=true' ) }}"
 
-        - name: Iterate over a parameter hierarchy
+- name: Iterate over a parameter hierarchy
   debug: msg='key contains {{item.Name }} with value {{item.Value}} '
   with_aws_ssm:
     - '/TEST/test-list'
     - 'region=ap-southeast-2'
     - 'bypath'
+'''
 
+from ansible.module_utils.ec2 import HAS_BOTO3
+from ansible.errors import AnsibleError
+from ansible.plugins.lookup import LookupBase
+from ansible.module_utils.parsing.convert_bool import boolean
+
+try:
+    from botocore.exceptions import ClientError
+    import boto3
+except ImportError:
+    pass  # will be captured by imported HAS_BOTO3
+
+
+class LookupModule(LookupBase):
+    def run(self, terms, variables, **kwargs):
+        '''
+            :param terms: a list of plugin options
+                          e.g. ['parameter_name', 'region=us-east-1', 'aws_profile=profile', 'decrypt=false']
+            :param variables: config variables
+            :return The value of the SSM parameter or None
         '''
 
         ret = {}