aws ssm parameter lookup - testing and documentation around negative and failure cases (#36550)

lib/ansible/plugins/lookup/aws_ssm.py

@@ -23,10 +23,20 @@ description:
     The first 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.
-  - When explicitly looking up a parameter by name the parameter being missing will be an error.
+  - If looking up an explicitly listed parameter by name which does not exist then the lookup will
+    return a None value which will be interpreted by Jinja2 as an empty string.  You can use the
+    ```default``` filter to give a default value in this case but must set the second parameter to
+    true (see examples below)
   - When looking up a path for parameters under it a dictionary will be returned for each path.
     If there is no parameter under that path then the return will be successful but the
     dictionary will be empty.
+  - If the lookup fails due to lack of permissions or due to an AWS client error then the aws_ssm
+    will generate an error, normally crashing the current ansible task.  This is normally the right
+    thing since ignoring a value that IAM isn't giving access to could cause bigger problems and
+    wrong behavour or loss of data.  If you want to continue in this case then you will have to set
+    up two ansible tasks, one which sets a variable and ignores failures one which uses the value
+    of that variable with a default.  See the examples below.
+
 options:
   decrypt:
     description: A boolean to indicate whether to decrypt the parameter.
@@ -51,9 +61,6 @@ EXAMPLES = '''
 - name: lookup ssm parameter store in the current region
   debug: msg="{{ lookup('aws_ssm', 'Hello' ) }}"
 
-- name: lookup a key which doesn't exist, returns ""
-  debug: msg="{{ lookup('aws_ssm', 'NoKey') }}"
-
 - name: lookup ssm parameter store in nominated region
   debug: msg="{{ lookup('aws_ssm', 'Hello', region=us-east-2 ) }}"
 
@@ -66,6 +73,20 @@ EXAMPLES = '''
 - name: lookup ssm parameter store with all options.
   debug: msg="{{ lookup('aws_ssm', 'Hello', decrypt=false, region=us-east-2, aws_profile=myprofile') }}"
 
+- name: lookup a key which doesn't exist, returns ""
+  debug: msg="{{ lookup('aws_ssm', 'NoKey') }}"
+
+- name: lookup a key which doesn't exist, returning a default ('root')
+  debug: msg="{{ lookup('aws_ssm', 'AdminID') | default('root', true) }}"
+
+- name: lookup a key which doesn't exist failing to store it in a fact
+  set_fact:
+    temp_secret: "{{ lookup('aws_ssm', '/NoAccess/hiddensecret') }}"
+  ignore_errors: true
+
+- name: show fact default to "access failed" if we don't have access
+  debug: msg="{{ "the secret was:" ~ temp_secret | default('couldn\'t access secret') }}"
+
 - name: return a dictionary of ssm parameters from a hierarchy path
   debug: msg="{{ lookup('aws_ssm', '/PATH/to/params', region=ap-southeast-2, bypath=true, recursive=true' ) }}"
 

test/integration/targets/aws_ssm_parameters/tasks/main.yml

@@ -74,10 +74,11 @@
         - "'{{lookup('aws_ssm', '/' ~ ssm_key_prefix ~ '/path', region=ec2_region, aws_access_key=ec2_access_key, aws_secret_key=ec2_secret_key, aws_security_token=security_token, bypath=True, shortnames=true ) | to_json }}' == '{\"toovar\": \"too value\", \"wonvar\": \"won value\"}'"
 
     # ============================================================
-    - name: Returns empty value in case we don't find a named parameter
+    - name: Returns empty value in case we don't find a named parameter and default filter works
       assert:
        that:
         - "'{{lookup('aws_ssm', '/' ~ ssm_key_prefix ~ '/Goodbye', region=ec2_region, aws_access_key=ec2_access_key, aws_secret_key=ec2_secret_key, aws_security_token=security_token )}}' == ''"
+        - "'{{lookup('aws_ssm', '/' ~ ssm_key_prefix ~ '/Goodbye', region=ec2_region, aws_access_key=ec2_access_key, aws_secret_key=ec2_secret_key, aws_security_token=security_token ) | default('I_can_has_default', true)}}' == 'I_can_has_default'"
 
     # ============================================================
     - name: Handle multiple paths with one that doesn't exist - default to full names.