diff --git a/changelogs/fragments/evn_default.yml b/changelogs/fragments/evn_default.yml new file mode 100644 index 00000000000..b999d28acee --- /dev/null +++ b/changelogs/fragments/evn_default.yml @@ -0,0 +1,2 @@ +minor_changes: + - env lookup, add default option diff --git a/lib/ansible/plugins/lookup/env.py b/lib/ansible/plugins/lookup/env.py index d88e9e3bd86..dc08870ee66 100644 --- a/lib/ansible/plugins/lookup/env.py +++ b/lib/ansible/plugins/lookup/env.py @@ -17,24 +17,36 @@ DOCUMENTATION = """ description: - Environment variable or list of them to lookup the values for. required: True + default: + description: What return when the variable is undefined + type: raw + default: '' + version_added: '2.13' notes: - - The module returns an empty string if the environment variable is not - defined. This makes it impossible to differentiate between the case the - variable is not defined and the case the variable is defined but it - contains an empty string. - - The C(default) filter requires second parameter to be set to C(True) - in order to set a default value in the case the variable is not - defined (see examples). + - You can pass the `Undefined` object as C(default) to force an undefined error """ EXAMPLES = """ - name: Basic usage debug: - msg: "'{{ lookup('env', 'HOME') }}' is the HOME environment variable." + msg: "{{ lookup('env', 'HOME') }} is the HOME environment variable." -- name: Example how to set default value if the variable is not defined +- name: Before 2.13, how to set default value if the variable is not defined. + This cannot distinguish between USR undefined and USR=''. debug: - msg: "'{{ lookup('env', 'USR') | default('nobody', True) }}' is the user." + msg: "{{ lookup('env', 'USR')|default('nobody', True) }} is the user." + +- name: Example how to set default value if the variable is not defined, ignores USR='' + debug: + msg: "{{ lookup('env', 'USR', default='nobody') }} is the user." + +- name: Set default value to Undefined, if the variable is not defined + debug: + msg: "{{ lookup('env', 'USR', default=Undefined) }} is the user." + +- name: Set default value to undef(), if the variable is not defined + debug: + msg: "{{ lookup('env', 'USR', default=undef()) }} is the user." """ RETURN = """ @@ -44,17 +56,24 @@ RETURN = """ type: list """ +from jinja2.runtime import Undefined +from ansible.errors import AnsibleUndefinedVariable from ansible.plugins.lookup import LookupBase from ansible.utils import py3compat class LookupModule(LookupBase): def run(self, terms, variables, **kwargs): - ret = [] + self.set_options(var_options=variables, direct=kwargs) + + ret = [] + d = self.get_option('default') for term in terms: var = term.split()[0] - ret.append(py3compat.environ.get(var, '')) - + val = py3compat.environ.get(var, d) + if isinstance(val, Undefined): + raise AnsibleUndefinedVariable('The "env" lookup, found an undefined variable: %s' % var) + ret.append(val) return ret diff --git a/test/integration/targets/lookup_env/runme.sh b/test/integration/targets/lookup_env/runme.sh new file mode 100755 index 00000000000..698d6bfa8cd --- /dev/null +++ b/test/integration/targets/lookup_env/runme.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +set -ex + +unset USR +# this should succeed and return 'nobody' as var is undefined +ansible -m debug -a msg="{{ lookup('env', 'USR', default='nobody')}}" localhost |grep nobody +# var is defined but empty, so should return empty +USR='' ansible -m debug -a msg="{{ lookup('env', 'USR', default='nobody')}}" localhost |grep -v nobody + +# this should fail with undefined +ansible -m debug -a msg="{{ lookup('env', 'USR', default=Undefined)}}" localhost && exit 1 || exit 0