How to Make Ansible variable mandatory

Question

I'm looking for the way how to make Ansible to analyze playbooks for required and mandatory variables before run playbook's execution like:

- name: create remote app directory hierarchy
  file:
    path: "/opt/{{ app_name | required }}/"
    state: directory
    owner: "{{ app_user | required }}"
    group: "{{ app_user_group | required }}"
  ...

and rise error message if variable is undefined, like:

please set "app_name" variable before run (file XXX/main.yml:99)

You might find this answer uselful: https://stackoverflow.com/a/30120360/4503915 — ThoFin, Jul 10 '17 at 13:33

score 53 · Answer 1 · answered Dec 24 '18 at 11:07

53

As Arbab Nazar mentioned, you can use {{ variable | mandatory }} (see Forcing variables to be defined) inside Ansible task.

But I think it looks nicer to add this as first task, it checks is app_name, app_user and app_user_group exist:

- name: 'Check mandatory variables are defined'
  assert:
    that:
      - app_name is defined
      - app_user is defined
      - app_user_group is defined

answered Dec 24 '18 at 11:07

Alexey Vazhnov

1,291
17
20

2

Here is better version from @Lev: https://stackoverflow.com/a/61563967/10354853 – Alexey Vazhnov May 03 '20 at 08:02
1

Thanks, but your solution is easier to remember and use. – Basil Musa Jun 14 '20 at 19:36

score 30 · Accepted Answer · edited Mar 19 '21 at 14:42

30

You can use this:

{{ variable | mandatory }}

edited Mar 19 '21 at 14:42

xy2

484
2
9

answered Jul 10 '17 at 15:59

Arbab Nazar

22,378
10
76
82

2

This will not check that the variable is defined _before_ playbook execution as asked in the original question, instead it will fail when the var is evaluated at templating/runtime (which is the default behavior unless you set ` DEFAULT_UNDEFINED_VAR_BEHAVIOR = False`). https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#defining-mandatory-values – mp04 Feb 04 '21 at 20:16
1

It's not a good solution and causes to false positives when the `variable` has value, but its value is `false`. In this situation, ansible wrongly errors that the variable is not set. So, the solution provided by Alexy Vazhnov down there is correct and should be accepted. – Emran May 02 '21 at 09:32

score 18 · Answer 3 · edited May 26 '21 at 09:26

Usually inside a role I perform checking input variables like in the example:

- name: "Verify that required string variables are defined"
  assert:
    that: 
      - "{{ ahs_var }} is defined"
      - "{{ ahs_var }} | length > 0"
      - "{{ ahs_var }} != None"
    fail_msg: "{{ ahs_var }} needs to be set for the role to work"
    success_msg: "Required variable {{ ahs_var }} is defined"
  loop_control:
    loop_var: ahs_var
  with_items:
    - ahs_item1
    - ahs_item2
    - ahs_item3

by the way there are some tricks:

Don't use global variables inside a role.
If you want use global variables define the role specific variable & set global variable to it i.e. some_role_name__db_port: "{{ db_port | default(5432) }}".
It makes sense to use role name as the prefix for variable. it helps to understand the source inventory easier.
Your role might be looped some how, so it makes sense to override the default item.

I like your double underscore to delimit the role name within the variable name. I have used this convention with success in other applications. — John McGehee, May 07 '20 at 23:33

René Pijl · Answer 4 · 2020-07-15T11:37:24.073

12

One way to check if mandatory variables are defined is:

- fail:
    msg: "Variable '{{ item }}' is not defined"
  when: item not in vars
  with_items:
    - app_nam
    - var2

edited Jul 15 '20 at 11:37

answered Jan 07 '18 at 17:43

René Pijl

4,310
1
19
25

papiro · Answer 5 · 2023-02-08T22:12:19.303

If using a role-based architecture, check out the docs on role argument validation.

It allows for you to specify a roles/<role_name>/meta/argument_specs.yml file which allows you to make variables required. Here is an example taken from their sample specification:

# roles/myapp/meta/argument_specs.yml
---
argument_specs:
  # roles/myapp/tasks/main.yml entry point
  main:
    short_description: The main entry point for the myapp role.
    options:
      myapp_int:
        type: "int"
        required: false
        default: 42
        description: "The integer value, defaulting to 42."

      myapp_str:
        type: "str"
        required: true
        description: "The string value"

  # roles/myapp/tasks/alternate.yml entry point
  alternate:
    short_description: The alternate entry point for the myapp role.
    options:
      myapp_int:
        type: "int"
        required: false
        default: 1024
        description: "The integer value, defaulting to 1024."

score 3 · Answer 6 · answered Jul 11 '17 at 00:34

3

There are 2 approaches:

Specify |mandatory filter
1. Beware dictionaries - if a key with mandatory value fails to eval, you may have a hard time uh understanding which is it.
Use assert module

answered Jul 11 '17 at 00:34

mvk_il

940
8
11

How to Make Ansible variable mandatory

6 Answers6

Linked