diff --git a/docsite/rst/playbooks.rst b/docsite/rst/playbooks.rst index b2cf63748c..0059adbdef 100644 --- a/docsite/rst/playbooks.rst +++ b/docsite/rst/playbooks.rst @@ -334,6 +334,19 @@ Variables passed in can then be used in the included files. You can reference t (In addition to the explicitly passed in parameters, all variables from the vars section are also available for use here as well.) +Starting in 1.0, variables can also be passed to include files using an alternative syntax, +which also supports structured variables:: + + tasks: + + - include: wordpress.yml + vars: + user: timmy + some_list_variable: + - alpha + - beta + - gamma + .. note:: As of 1.0, task include statements can be used at arbitrary depth. They were previously limited to a single level, so task includes diff --git a/docsite/rst/playbooks2.rst b/docsite/rst/playbooks2.rst index ec8f1ae5b2..aceffc26db 100644 --- a/docsite/rst/playbooks2.rst +++ b/docsite/rst/playbooks2.rst @@ -367,6 +367,13 @@ registered tasks. As an example:: action: shell /bin/true when_changed: $result +Note that if you have several tasks that all share the same conditional statement, you can affix the conditional +to a task include statement as below. Note this does not work with playbook includes, just task includes. All the tasks +get evaluated, but the conditional is applied to each and every task:: + + - include: tasks/sometasks.yml + when_string: 'reticulating splines' in $output + Conditional Imports ``````````````````` @@ -564,6 +571,42 @@ Negative numbers are not supported. This works as follows:: - group: name=group${item} state=present with_sequence: count=4 +Setting the Environment (and Working With Proxies) +`````````````````````````````````````````````````` + +.. versionadded: 1.1 + +It is quite possible that you may need to get package updates through a proxy, or even get some package +updates through a proxy and access other packages not through a proxy. Ansible makes it easy for you +to configure your environment by using the 'environment' keyword. Here is an example:: + +- hosts: all + user: root + + tasks: + + - apt: name=cobbler state=installed + environment: + http_proxy: http://proxy.example.com:8080 + +The environment can also be stored in a variable, and accessed like so:: + +- hosts: all + user: root + + # here we make a variable named "env" that is a dictionary + vars: + env: + http_proxy=http://proxy.example.com:8080 + + tasks: + + - apt: name=cobbler state=installed + environment: $env + +While just proxy settings were shown above, any number of settings can be supplied. + + Getting values from files ````````````````````````` @@ -874,6 +917,35 @@ Therefore, if you want to set a default value for something you wish to override place to set such a default is in a group variable. The 'group_vars/all' file makes an excellent place to put global variables that are true across your entire site, since everything has higher priority than these values. + +Check Mode ("Dry Run") --check +``````````````````````````````` + +.. versionadded:: 1.1 + +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 the primary core modules, but it is not required that all modules do +this) will report what changes they would have made. 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 --check + +Showing Differences with --diff +``````````````````````````````` + +.. versionadded:: 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 + Style Points ````````````