Checking the Validity of Extra Variables Passed to an Ansible Playbook

Ansible is a powerful and popular tool used by DevOps teams for configuration management and application deployment. One of its strong points is its flexibility, provided by features such as variable definition. Variables in Ansible allow you to manage differences between systems, making your playbooks reusable across different environments.

Often, there’s a need to pass extra variables to an Ansible playbook to further tailor its execution. While this feature can be very useful, it’s important to check the validity of these extra variables to prevent errors and ensure smooth execution of the playbook.

In this blog post, we will walk you through a step-by-step guide on how to check the validity of the extra variables passed to an Ansible playbook. Let’s get started!

Step 1: Understanding Extra Variables

In Ansible, extra variables are custom variables that you can pass to the playbook at the command line. They are defined using the -e or --extra-vars flag followed by the variable and its value. Extra variables take precedence over other variables, allowing you to override previously defined variables.

For example, the command to run a playbook with an extra variable might look like this:

ansible-playbook deploy.yml -e "env=production"

In this case, env is the extra variable and production is its value.

Step 2: Implementing Variable Validation

To ensure that your playbook runs smoothly and as expected, it’s crucial to validate the extra variables. There are several ways you can implement this, and one of the most effective is through the use of the assert module.

The assert module in Ansible allows you to set conditions that must be met for the playbook to proceed. If the conditions are not met, the playbook will fail, allowing you to catch potential issues early.

For instance, if you have an extra variable env that should only have the values “production”, “staging”, or “development”, you can add the following task at the beginning of your playbook:

name: Check validity of env variable
      - env in ['production', 'staging', 'development']
    fail_msg: "The env variable must be either 'production', 'staging', or 'development'"

If the value of env is anything other than “production”, “staging”, or “development”, the playbook will fail with the specified error message.

Step 3: Dealing with Undefined Variables

Another common issue is the absence of an expected extra variable. In Ansible, if you try to use a variable that is not defined, it will cause an error.

To deal with this, Ansible has a default filter that you can use to provide a default value for a variable if it is not defined. For example:

name: Set default value for env variable
    env: "{{ env | default('development') }}"

In this task, if env is not defined, it will be given the default value “development”.

Step 4: Additional Validations

Sometimes, you might want to perform additional checks on the extra variables. For instance, you might want to verify that a variable is a certain type (like an integer), or that it follows a certain format (like an email address).

For these kinds of validations, you can use the regex_match filter, int filter, length filter, and other built-in Ansible filters. For example:

name: Check if var is an integer
      - var | int == var
    fail_msg: "The var variable must be an integer"

- name: Check if email follows the correct format
      - email | regex_match('^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$')
    fail_msg: "The email variable must be a valid email address"

These tasks will ensure that var is an integer and email is a valid email address.

Step 4: Fallback to Predefined Definitions if Validations Fail

there are various ways you can implement a fallback mechanism for invalid variables in an Ansible playbook. One method to achieve this is by using set_fact in conjunction with conditional statements and the assert module. Here is an example using the env variable mentioned in the previous section:

- name: Check validity of env variable
      - env is defined
      - env in ['production', 'staging', 'development']
    ignore_errors: yes

- name: Fall back to default value for env variable
    env: "development"
  when: env is undefined or env not in ['production', 'staging', 'development']

Let’s break this down:

  1. Check validity of env variable: This task checks if the env variable is defined and if it holds a valid value. If these conditions are not met, the task will fail, but because of the ignore_errors: yes line, the playbook will continue running.
  2. Fall back to default value for env variable: This task sets the env variable to its default value if it’s not defined or if it doesn’t hold a valid value. This is done using the set_fact module and the when conditional statement.

The when keyword allows a task to be executed only if certain conditions are met. In this case, the set_fact task will only run if env is undefined or if env is not one of the valid values (“production”, “staging”, or “development”).

Using this approach, if an invalid env variable is passed, Ansible will fall back to the predefined default value (“development” in this case), ensuring that the playbook execution can continue without errors.


By using the power of Ansible’s assert module, filters, and some simple logic, you can validate the extra variables passed to your playbooks and make your Ansible deployments more robust and reliable.

Remember, while Ansible offers significant flexibility in terms of variable usage, with flexibility comes the need for careful management. As such, always take the time to validate your variables. After all, prevention is better than debugging!

Scroll to Top