2b28beb1d7
* add check_mode option for tasks includes example testcases for the template module * extend check_mode option * replace always_run, see also proposal rename_always_run * rename always_run where used and add deprecation warning * add some documentation * have check_mode overwrite always_run * use unique template name to prevent conflicts test_check_mode was right before, but failed due to using the same filename as other roles * still mention always_run in the docs * set deprecation of always_run to version 2.4 * fix rst style * expand documentation on per-task check mode
3.6 KiB
Check Mode ("Dry Run")
1.1
Topics
When ansible-playbook is executed with --check it will
not make any changes on remote systems. Instead, any module instrumented
to support 'check mode' (which contains most of the primary core
modules, but it is not required that all modules do this) will report
what changes they would have made rather than making them. Other modules
that do not support check mode will also take no action, but just will
not report what changes they might have made.
Check mode is just a simulation, and if you have steps that use conditionals that depend on the results of prior commands, it may be less useful for you. However it is great for one-node-at-time basic configuration management use cases.
Example:
ansible-playbook foo.yml --checkEnabling or disabling check mode for tasks
2.2
Sometimes you may want to modify the check mode behavior of
individual tasks. This is done via the check_mode option,
which can be added to tasks.
There are two options:
- Force a task to run in check mode, even when the
playbook is called without
--check. This is calledcheck_mode: yes. - Force a task to run in normal mode and make changes
to the system, even when the playbook is called with
--check. This is calledcheck_mode: no.
Note
Prior to version 2.2 only the the equivalent of
check_mode: no existed. The notation for that was
always_run: yes.
Instead of yes/no you can use a Jinja2
expression, just like the when clause.
Example:
tasks:
- name: this task will make changes to the system even in check mode
command: /something/to/run --even-in-check-mode
check_mode: no
- name: this task will always run under checkmode and not change the system
lineinfile: line="important config" dest=/path/to/myconfig.conf state=present
check_mode: yesRunning single tasks with check_mode: yes can be useful
to write tests for ansible modules, either to test the module itself or
to the the conditions under which a module would make changes. With
register (see playbooks_conditionals) you can check the potential
changes.
Information about check mode in variables
2.1
If you want to skip, or ignore errors on some tasks in check mode you
can use a boolean magic variable ansible_check_mode which
will be set to True during check mode.
Example:
tasks:
- name: this task will be skipped in check mode
git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello
when: not ansible_check_mode
- name: this task will ignore errors in check mode
git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello
ignore_errors: "{{ ansible_check_mode }}"Showing Differences with --diff
1.1
The --diff option to ansible-playbook works great with
--check (detailed above) but can also be used by itself.
When this flag is supplied, if any templated files on the remote system
are changed, and the ansible-playbook CLI will report back the textual
changes made to the file (or, if used with --check, the
changes that would have been made). Since the diff feature produces a
large amount of output, it is best used when checking a single host at a
time, like so:
ansible-playbook foo.yml --check --diff --limit foo.example.com