ansible vars_files vs include_vars

Question

What is the difference between

• vars_files directive

  and

• include_vars module

Which should be used when, is any of above deprecated, discouraged?

Answer 1

vars_files are read when the play starts. include_vars are read when the play reaches the task. You probably might be interested also in Variable precedence: Where should I put a variable?

Answer 2

Both vars_files and include_vars are labeled as stable interfaces so neither of them are deprecated. Both of them have some commonalities but they solve different purposes.

vars_files:

vars_file directive can only be used when defining a play to specify variable files. The variables from those files are included in the playbook. Since it is used in the start of the play, it most likely implies that some other play(before this play) created those vars files or they were created statically before running the configuration; means they were kind of configuration variables for the play.

include_vars:

vars_files serves one purpose of including the vars from a set of files but it cannot handle the cases if

• the vars files were created dynamically and you want to include them in play
• include vars in a limited scope.
• You have multiple vars files and you want to include them based on certain criteria e.g. if the local database exists then include configuration of local database otherwise include configuration of a remotely hosted database.
• include_vars have higher priority than vars_files so, it can be used to override default configuration(vars).
• include_vars are evaluated lazily(evaluated at the time when they are used).
• You want to include vars dynamically using a loop.
• You want to read a file and put all those variables in a named dictionary instead of reading all variables in the global variable namespace.
• You want to include all files in a directory or some subset of files in a directory(based on prefix or exclusion list) without knowing the exact names of the vars file(s).

These are some of the cases which I can think of and if you want to use any of the above cases then you need include_vars.

Answer 3

Some updated information...

• import_* is considered static reuse, vars_files is a type of import.
• include_* is considered dynamic reuse.

As Vladimir mentioned,

vars_files are read when the play starts. include_vars are read when the play reaches the task

Like all static items, vars_files are read before the play starts. Unlike include_vars, which are "included" when the play reaches it.

One of the biggest differences between static reuse and dynamic reuse is how the variables or tasks within them are processed. All static reuse items are processed with the linear strategy by default, all host stay in lockstep with each other. Each tasks has to complete on ALL hosts before the next task can begin. Hosts that are skipped actually get a noop task to process.

Dynamic reuse does not change the performance strategy from linear, however it does change the order the tasks are processed. With dynamic reuse, the entire group of tasks must complete on a single host before they are process by the next host. Unfortunately, all the other hosts get to twiddle their noops while they wait.

Include statements are good when you need to 'loop' a host through a series of tasks with registered outputs and do something with that information before the before the next host starts.

Import statements are good when you need to collect information or perform a task on a group of hosts before the next task can start for any host.

Here is a really good table that compares all the different Include_* and Import_* functions.Comparing includes and imports: dynamic and static re-use

Just as an FYI, here is a link to more information about performance strategies and how you can improve performance. How can I improve performance for network playbooks?