diff options
author | Brian Coca <brian.coca+git@gmail.com> | 2017-09-14 16:27:56 -0400 |
---|---|---|
committer | Toshio Kuratomi <a.badger@gmail.com> | 2017-09-15 13:21:00 -0700 |
commit | 2b8508f4718aabbf35240172748af139a8857bab (patch) | |
tree | 7a06af25b5d2ff8e2f39c09a7b03281864712952 /lib | |
parent | a725b62f51ddf080d9ff362593dd01aa53c70fcb (diff) | |
download | ansible-2b8508f4718aabbf35240172748af139a8857bab.tar.gz |
deprecated include
added docs for new actions that take over include duties
(cherry picked from commit 8799038a895ed0ff230e2aa0629c4b83e8f15cf1)
Diffstat (limited to 'lib')
-rw-r--r-- | lib/ansible/cli/doc.py | 7 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/_include.py (renamed from lib/ansible/modules/utilities/logic/include.py) | 4 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/import_plays.py | 55 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/import_role.py | 93 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/import_tasks.py | 58 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/include_role.py | 9 | ||||
-rw-r--r-- | lib/ansible/modules/utilities/logic/include_tasks.py | 57 |
7 files changed, 276 insertions, 7 deletions
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 02ee8a534a..556a7551f8 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -417,7 +417,12 @@ class DocCLI(CLI): text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent)) if 'deprecated' in doc and doc['deprecated'] is not None and len(doc['deprecated']) > 0: - text.append("DEPRECATED: \n%s\n" % doc.pop('deprecated')) + text.append("DEPRECATED: \n") + if isinstance(doc['deprecated'], dict): + text.append("\tReason: %(why)s\n\tScheduled removal: Ansible %(version)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated')) + else: + text.append("%s" % doc.pop('deprecated')) + text.append("\n") try: support_block = self.get_support_block(doc) diff --git a/lib/ansible/modules/utilities/logic/include.py b/lib/ansible/modules/utilities/logic/_include.py index ab3aef7898..65dd331490 100644 --- a/lib/ansible/modules/utilities/logic/include.py +++ b/lib/ansible/modules/utilities/logic/_include.py @@ -8,7 +8,7 @@ __metaclass__ = type ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], + 'status': ['deprecated'], 'supported_by': 'core'} @@ -18,6 +18,8 @@ author: - "Ansible Core Team (@ansible)" module: include short_description: include a play or task list. +deprecated: + The include action was too confusing, dealing with both plays and tasks, being both dynamic and static. This module will be removed in version 2.8. As alternatives use include_tasks, import_plays, import_tasks. description: - Includes a file with a list of plays or tasks to be executed in the current playbook. - Files with a list of plays can only be included at the top level, lists of tasks can only be included where tasks normally run (in play). diff --git a/lib/ansible/modules/utilities/logic/import_plays.py b/lib/ansible/modules/utilities/logic/import_plays.py new file mode 100644 index 0000000000..3ccab82b8d --- /dev/null +++ b/lib/ansible/modules/utilities/logic/import_plays.py @@ -0,0 +1,55 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core'} + + +DOCUMENTATION = ''' +--- +author: + - "Ansible Core Team (@ansible)" +module: import_plays +short_description: import a playbook. +description: + - Includes a file with a list of plays to be executed. + - Files with a list of plays can only be included at the top level, you cannot use this action inside a Play. +version_added: "2.4" +options: + free-form: + description: + - This action allows you to specify the name of the file directly w/o any other options. +notes: + - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. +''' + +EXAMPLES = """ +- name: include a play after another play + hosts: localhost + tasks: + - debug: + msg: "play1" + +- import_plays: otherplays.yml + + +- name: This DOES NOT WORK + hosts: all + tasks: + - debug: + msg: task1 + + - name: This failes because I'm inside a play already + import_plays: stuff.yml +""" + +RETURN = """ +# this module does not return anything except plays to execute +""" diff --git a/lib/ansible/modules/utilities/logic/import_role.py b/lib/ansible/modules/utilities/logic/import_role.py new file mode 100644 index 0000000000..8a56872844 --- /dev/null +++ b/lib/ansible/modules/utilities/logic/import_role.py @@ -0,0 +1,93 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core'} + + +DOCUMENTATION = ''' +--- +author: + - "Ansible Core Team (@ansible)" +module: import_role +short_description: Import a role into a play +description: + - Mostly like the `roles:` keyword this action loads a role, but it allows you to control when the tasks run in between other playbook tasks. + - Most keyworkds, loops and conditionals will not be applied to this action, but to the imported tasks instead. + If you want the opposite behaviour, use M(import_role) instead. +version_added: "2.4" +options: + name: + description: + - The name of the role to be executed. + required: True + tasks_from: + description: + - "File to load from a Role's tasks/ directory." + required: False + default: 'main' + vars_from: + description: + - "File to load from a Role's vars/ directory." + required: False + default: 'main' + defaults_from: + description: + - "File to load from a Role's defaults/ directory." + required: False + default: 'main' + allow_duplicates: + description: + - Overrides the role's metadata setting to allow using a role more than once with the same parameters. + required: False + default: True + private: + description: + - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play. + default: None +notes: + - Handlers are made available to the whole play. +''' + +EXAMPLES = """ +- hosts: all + tasks: + - import_role: + name: myrole + + - name: Run tasks/other.yml instead of 'main' + import_role: + name: myrole + tasks_from: other + + - name: Pass variables to role + import_role: + name: myrole + vars: + rolevar1: 'value from task' + + - name: Apply loop to each task in role + import_role: + name: myrole + with_items: + - '{{ roleinput1 }}' + - '{{ roleinput2 }}' + loop_control: + loop_var: roleinputvar + + - name: Apply condition to each task in role + import_role: + name: myrole + when: not idontwanttorun +""" + +RETURN = """ +# this module does not return anything except tasks to execute +""" diff --git a/lib/ansible/modules/utilities/logic/import_tasks.py b/lib/ansible/modules/utilities/logic/import_tasks.py new file mode 100644 index 0000000000..d7770eb1fc --- /dev/null +++ b/lib/ansible/modules/utilities/logic/import_tasks.py @@ -0,0 +1,58 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core'} + + +DOCUMENTATION = ''' +--- +author: + - "Ansible Core Team (@ansible)" +module: import_tasks +short_description: import a task list. +description: + - Imports a list of tasks to be added to the current playbook for subsequent execution. +version_added: "2.4" +options: + free-form: + description: + - This action allows you to specify the name of the file directly w/o any other options. + - Any loops, conditionals and most other keywords will be applied to the included tasks, not to this statement itself. + - If you need any of those to apply to this action, use M(include_tasks) instead. +notes: + - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. +''' + +EXAMPLES = """ +# include task list in play +- hosts: all + tasks: + - debug: + msg: task1 + + - import_tasks: stuff.yml + + - debug: + msg: task10 + +# apply conditional to all imported tasks +- hosts: all + tasks: + - debug: + msg: task1 + + - include: stuff.yml" + when: hostvar is defined +""" + +RETURN = """ +# this module does not return anything except tasks to execute +""" diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py index b56e8eb3b1..0ff592ac3c 100644 --- a/lib/ansible/modules/utilities/logic/include_role.py +++ b/lib/ansible/modules/utilities/logic/include_role.py @@ -53,11 +53,10 @@ options: default: None notes: - Handlers are made available to the whole play. - - simple dependencies seem to work fine. - - As with C(include) this task can be static or dynamic, If static it implies that it won't need templating nor loops nor conditionals and will - show included tasks in the --list options. Ansible will try to autodetect what is needed, but you can set `static` to `yes` or `no` at task - level to control this. - - This module is also supported for Windows targets. + - Before 2.4, as with C(include), this task could be static or dynamic, If static it implied that it won't need templating nor loops nor conditionals + and will show included tasks in the --list options. + Ansible would try to autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this. + - After 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one. ''' EXAMPLES = """ diff --git a/lib/ansible/modules/utilities/logic/include_tasks.py b/lib/ansible/modules/utilities/logic/include_tasks.py new file mode 100644 index 0000000000..2eaa9bdade --- /dev/null +++ b/lib/ansible/modules/utilities/logic/include_tasks.py @@ -0,0 +1,57 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core'} + + +DOCUMENTATION = ''' +--- +author: + - "Ansible Core Team (@ansible)" +module: include_tasks +short_description: dynamically include a task list. +description: + - Includes a file with a list of tasks to be executed in the current playbook. +version_added: "2.4" +options: + free-form: + description: + - This action allows you to specify the name of the file directly w/o any other options. + - Unlike M(import_tasks) this action will be affected by most keywords, including loops and conditionals. +notes: + - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. +''' + +EXAMPLES = """ +# include task list in play +- hosts: all + tasks: + - debug: + msg: task1 + + - include_tasks: stuff.yml + + - debug: + msg: task10 + +# dyanmic include task list in play +- hosts: all + tasks: + - debug: + msg: task1 + + - include_tasks: "{{ hostvar }}.yml" + when: hostvar is defined +""" + +RETURN = """ +# this module does not return anything except tasks to execute +""" |