From 3e351b4727824baee82a7d7355f942c94298ceaa Mon Sep 17 00:00:00 2001 From: James Tanner Date: Thu, 7 Nov 2013 01:43:55 -0500 Subject: [PATCH] Fixes #4092 Add documentation for yaml format of tasks and all keywords --- docsite/rst/index.rst | 2 + docsite/rst/playbooks.rst | 2 + docsite/rst/playbooks_tasks.rst | 269 ++++++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+) create mode 100644 docsite/rst/playbooks_tasks.rst diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index 96d7ca69b09..450bd42dfb1 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -111,6 +111,7 @@ and adopt these only if they seem relevant or useful to your environment. playbooks_error_handling playbooks_lookups playbooks_prompts + playbooks_tasks playbooks_tags .. _ansibleworks_awx: @@ -183,3 +184,4 @@ Some additional topics you may be interested in: YAMLSyntax + diff --git a/docsite/rst/playbooks.rst b/docsite/rst/playbooks.rst index a4e58b9f2c5..6a48eef4c8a 100644 --- a/docsite/rst/playbooks.rst +++ b/docsite/rst/playbooks.rst @@ -380,6 +380,8 @@ can do this:: Learn about YAML syntax :doc:`playbooks_best_practices` Various tips about managing playbooks in the real world + :doc:`playbooks_tasks` + An index of formats and keywords for tasks :doc:`index` Hop back to the documentation index for a lot of special topics about playbooks :doc:`modules` diff --git a/docsite/rst/playbooks_tasks.rst b/docsite/rst/playbooks_tasks.rst new file mode 100644 index 00000000000..260954ceec5 --- /dev/null +++ b/docsite/rst/playbooks_tasks.rst @@ -0,0 +1,269 @@ +Tasks +===== + +.. contents:: + :depth: 2 + +Playbook tasks can have a few different formats and can take many different keywords. + +.. _task_formats: + +Task Formats +++++++++++++++++++++++ + +Basic +`````````````` + +The first keyword in a task can be the module name:: + + - debug: msg="hello world" + +It can also be a name:: + + - name: a task with a name + debug: msg="hello world" + +Args can be separated to newlines:: + + - copy: src=/srv/myfiles/foo.conf + dest=/etc/foo.conf + +Old style with args inline:: + + - action: debug 'msg="hello world"' + +Old style with a name defined:: + + - action: debug 'msg="hello world"' + name: a task with aname + +Old style with args as a dictionary:: + + - action: debug + args: + msg: "hello world" + + +Connection Types +```````````````` + +Setting the connection type to local:: + + - debug: msg="hello world" + connection: local + +Setting the connection type to ssh:: + + - debug: msg="hello world" + connection: ssh + +Old style with a local connection:: + + - local_action: debug 'msg="hello world"' + + +.. _task_keywords: + +Task Keywords +++++++++++++++++++++++ + +Valid keywords for tasks in playbooks. + +action +`````````````` + +always_run +`````````````` +:doc:`playbooks_checkmode` + +any_errors_fatal +```````````````` +:doc:`playbooks_error_handling` + +args +`````````````` + +async +`````````````` +:doc:`playbooks_async` + + +changed_when +`````````````` +:doc:`playbooks_error_handling` + +connection +`````````````` +:doc:`playbooks_delegation` + +delay +`````````````` + +delegate_to +`````````````` +:doc:`playbooks_delegation` + +environment +`````````````` + +failed_when +`````````````` +:doc:`playbooks_error_handling` + +first_available_file +```````````````````` + +ignore_errors +`````````````` +:doc:`playbooks_error_handling` + +local_action +`````````````` +:doc:`playbooks_delegation` + +name +`````````````` + +notify +`````````````` +:doc:`playbooks` + +only_if +`````````````` + +poll +`````````````` +:doc:`playbooks_async` + +register +`````````````` +:doc:`playbooks_variables` +:doc:`playbooks_loops` + +remote_user +`````````````` +:doc:`playbooks` + +retries +`````````````` +:doc:`playbooks_loops` + +sudo +`````````````` + +sudo_user +`````````````` + +sudo_pass +`````````````` + +tags +`````````````` +:doc:`playbooks_tags` + +transport +`````````````` +:doc:`playbooks_delegation` + +until +`````````````` +:doc:`playbooks_loops` + +when +`````````````` +:doc:`playbooks_conditionals` + +with_dnstext +`````````````` +:doc:`playbooks_loops` + +with_env +`````````````` +:doc:`playbooks_loops` + +with_file +`````````````` +:doc:`playbooks_loops` + +with_fileglob +`````````````` +:doc:`playbooks_loops` + +with_first_found +```````````````` +:doc:`playbooks_loops` + +with_flattened +`````````````` +:doc:`playbooks_loops` + +with_indexed_items +`````````````````` +:doc:`playbooks_loops` + +with_inventory_hostnames +```````````````````````` +:doc:`playbooks_loops` + +with_items +`````````````` +:doc:`playbooks_loops` + +with_lines +`````````````` +:doc:`playbooks_loops` + +with_nested +`````````````` +:doc:`playbooks_loops` + +with_password +`````````````` +:doc:`playbooks_loops` + +with_pipe +`````````````` +:doc:`playbooks_loops` + +with_random_choice +`````````````````` +:doc:`playbooks_loops` + +with_redis_kv +`````````````` +:doc:`playbooks_loops` + +with_sequence +`````````````` +:doc:`playbooks_loops` + +with_subelements +```````````````` +:doc:`playbooks_loops` + +with_template +`````````````` +:doc:`playbooks_loops` + +with_together +`````````````` +:doc:`playbooks_loops` + +.. seealso:: + + :doc:`playbooks` + An introduction to playbooks + :doc:`playbooks_roles` + Playbook organization by roles + :doc:`playbooks_best_practices` + Best practices in playbooks + :doc:`playbooks_conditionals` + Conditional statements in playbooks + :doc:`playbooks_variables` + All about variables + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel + +