cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Unifying wording and formatting of all include and import modules (#31938)

Browse source 
* Unifying wording and formatting of all include and import modules

* Changes based on comments from dharmabumstead

* Removed instances of the term ‘Ansible Engine’

* Removed instances of term ‘Ansible Engine’

* Updated term

* Updated wording

* Updated wording

* Removed the term ‘Ansible Engine’
This commit is contained in:
Jiri Tyr 2017-11-22 22:05:29 +00:00 committed by scottb
parent 496ce388ab
commit 283fee90a7
7 changed files with 169 additions and 154 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
lib/ansible/modules/utilities/logic/_include.py
View file

@ -7,71 +7,74 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['deprecated'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
author: Ansible Core Team (@ansible)
module: include
short_description: include a play or task list.
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_playbook, import_tasks.
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 M(include_tasks), M(import_playbook), M(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).
- Before 2.0 all includes were 'static', executed at play compile time.
- Static includes are not subject to most directives, for example, loops or conditionals, they are applied instead to each inherited task.
- Since 2.0 task includes are dynamic and behave more like real tasks. This means they can be looped, skipped and use variables from any source.
Ansible tries to auto detect this, use the `static` directive (new in 2.1) to bypass autodetection.
- 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).
- Before Ansible version 2.0, all includes were 'static' and were executed when the play was compiled.
- Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each
inherited task.
- Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped,
skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static`
directive (which was added in Ansible 2.1) to bypass autodetection.
- This module is also supported for Windows targets.
version_added: "0.6"
options:
free-form:
description:
- This module allows you to specify the name of the file directly w/o any other options.
- This module allows you to specify the name of the file directly without any other options.
notes:
- This is really not a module, though it appears as such, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a
module can.
- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
- This module is also supported for Windows targets.
'''
EXAMPLES = """
# include a play after another play
- hosts: localhost
tasks:
- debug:
msg: "play1"
msg: play1
- include: otherplays.yml
- name: Include a play after another play
include: otherplays.yaml
# include task list in play
- hosts: all
tasks:
- debug:
msg: task1
- include: stuff.yml
- name: Include task list in play
include: stuff.yaml
- debug:
msg: task10
# dyanmic include task list in play
- hosts: all
tasks:
- debug:
msg: task1
- include: "{{ hostvar }}.yml"
- name: Include task list in play only if the condition is true
include: "{{ hostvar }}.yaml"
static: no
when: hostvar is defined
"""
RETURN = """
# this module does not return anything except plays or tasks to execute
# This module does not return anything except plays or tasks to execute.
"""

31
lib/ansible/modules/utilities/logic/import_playbook.py
View file

@ -7,37 +7,38 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
author: Ansible Core Team (@ansible)
module: import_playbook
short_description: import a playbook.
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.
- 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.
- The name of the imported playbook is specified directly without any other option.
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.
- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
'''
EXAMPLES = """
- name: include a play after another play
hosts: localhost
- hosts: localhost
tasks:
- debug:
msg: "play1"
msg: play1
- import_playbook: otherplays.yml
- name: Include a play after another play
import_playbook: otherplays.yaml
- name: This DOES NOT WORK
@ -46,10 +47,10 @@ EXAMPLES = """
- debug:
msg: task1
- name: This failes because I'm inside a play already
import_playbook: stuff.yml
- name: This fails because I'm inside a play already
import_playbook: stuff.yaml
"""
RETURN = """
# this module does not return anything except plays to execute
# This module does not return anything except plays to execute.
"""

37
lib/ansible/modules/utilities/logic/import_role.py
View file

@ -7,21 +7,23 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
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 keywords, loops and conditionals will not be applied to this action, but to the imported tasks instead.
If you want the opposite behaviour, use M(include_role) instead.
- Much like the `roles:` keyword, this task loads a role, but it allows you to control it when the role tasks run in
between other tasks of the play.
- Most keywords, loops and conditionals will only be applied to the imported tasks, not to this statement itself. If
you want the opposite behaviour, use M(include_role) instead.
version_added: "2.4"
options:
name:
@ -30,19 +32,19 @@ options:
required: True
tasks_from:
description:
- "File to load from a Role's tasks/ directory."
- File to load from a role's C(tasks/) directory.
required: False
default: 'main'
default: main
vars_from:
description:
- "File to load from a Role's vars/ directory."
- File to load from a role's C(vars/) directory.
required: False
default: 'main'
default: main
defaults_from:
description:
- "File to load from a Role's defaults/ directory."
- File to load from a role's C(defaults/) directory.
required: False
default: 'main'
default: main
allow_duplicates:
description:
- Overrides the role's metadata setting to allow using a role more than once with the same parameters.
@ -50,7 +52,8 @@ options:
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.
- If C(True) the variables from C(defaults/) and C(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.
@ -62,7 +65,7 @@ EXAMPLES = """
- import_role:
name: myrole
- name: Run tasks/other.yml instead of 'main'
- name: Run tasks/other.yaml instead of 'main'
import_role:
name: myrole
tasks_from: other
@ -71,7 +74,7 @@ EXAMPLES = """
import_role:
name: myrole
vars:
rolevar1: 'value from task'
rolevar1: value from task
- name: Apply loop to each task in role
import_role:
@ -89,5 +92,5 @@ EXAMPLES = """
"""
RETURN = """
# this module does not return anything except tasks to execute
# This module does not return anything except tasks to execute.
"""

31
lib/ansible/modules/utilities/logic/import_tasks.py
View file

@ -7,52 +7,53 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
author: Ansible Core Team (@ansible)
module: import_tasks
short_description: import a task list.
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.
- The name of the imported file is specified directly without any other option.
- Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement
itself. If you need any of those to apply, 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.
- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
'''
EXAMPLES = """
# include task list in play
- hosts: all
tasks:
- debug:
msg: task1
- import_tasks: stuff.yml
- name: Include task list in play
import_tasks: stuff.yaml
- debug:
msg: task10
# apply conditional to all imported tasks
- hosts: all
hosts: all
tasks:
- debug:
msg: task1
- import_tasks: stuff.yml
- name: Apply conditional to all imported tasks
import_tasks: stuff.yaml
when: hostvar is defined
"""
RETURN = """
# this module does not return anything except tasks to execute
# This module does not return anything except tasks to execute.
"""

44
lib/ansible/modules/utilities/logic/include_role.py
View file

@ -7,19 +7,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
author: Ansible Core Team (@ansible)
module: include_role
short_description: Load and execute a role
description:
- Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks.
- Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be
treated more as tasks.
- Unlike M(import_role), most keywords, including loops and conditionals, apply to this statement.
- This module is also supported for Windows targets.
version_added: "2.2"
options:
@ -29,19 +32,19 @@ options:
required: True
tasks_from:
description:
- "File to load from a Role's tasks/ directory."
- File to load from a role's C(tasks/) directory.
required: False
default: 'main'
default: main
vars_from:
description:
- "File to load from a Role's vars/ directory."
- File to load from a role's C(vars/) directory.
required: False
default: 'main'
default: main
defaults_from:
description:
- "File to load from a Role's defaults/ directory."
- File to load from a role's C(defaults/) directory.
required: False
default: 'main'
default: main
allow_duplicates:
description:
- Overrides the role's metadata setting to allow using a role more than once with the same parameters.
@ -49,21 +52,22 @@ options:
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.
- If C(True) the variables from C(defaults/) and C(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.
- 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.
- Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
need templating, loops or 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 Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
'''
EXAMPLES = """
- include_role:
name: myrole
- name: Run tasks/other.yml instead of 'main'
- name: Run tasks/other.yaml instead of 'main'
include_role:
name: myrole
tasks_from: other
@ -72,7 +76,7 @@ EXAMPLES = """
include_role:
name: myrole
vars:
rolevar1: 'value from task'
rolevar1: value from task
- name: Use role in loop
include_role:
@ -83,12 +87,12 @@ EXAMPLES = """
loop_control:
loop_var: roleinputvar
- name: conditional role
- name: Conditional role
include_role:
name: myrole
when: not idontwanttorun
"""
RETURN = """
# this module does not return anything except tasks to execute
# This module does not return anything except tasks to execute.
"""

27
lib/ansible/modules/utilities/logic/include_tasks.py
View file

@ -7,51 +7,52 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author:
- "Ansible Core Team (@ansible)"
author: Ansible Core Team (@ansible)
module: include_tasks
short_description: dynamically include a task list.
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.
- The name of the imported file is specified directly without any other option.
- Unlike M(import_tasks), most keywords, including loops and conditionals, apply to this statement.
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.
- This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module.
'''
EXAMPLES = """
# include task list in play
- hosts: all
tasks:
- debug:
msg: task1
- include_tasks: stuff.yml
- name: Include task list in play
include_tasks: stuff.yaml
- debug:
msg: task10
# dyanmic include task list in play
- hosts: all
tasks:
- debug:
msg: task1
- include_tasks: "{{ hostvar }}.yml"
- name: Include task list in play only if the condition is true
include_tasks: "{{ hostvar }}.yaml"
when: hostvar is defined
"""
RETURN = """
# this module does not return anything except tasks to execute
# This module does not return anything except tasks to execute.
"""

62
lib/ansible/modules/utilities/logic/include_vars.py
View file

@ -5,19 +5,21 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
'supported_by': 'core'
}
DOCUMENTATION = '''
---
author: "Allen Sanabria (@linuxdynasty)"
author: Allen Sanabria (@linuxdynasty)
module: include_vars
short_description: Load variables from files, dynamically within a task.
short_description: Load variables from files, dynamically within a task
description:
- Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task runtime. If loading a directory,
the files are sorted alphabetically before being loaded.
- Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task
runtime. If loading a directory, the files are sorted alphabetically before being loaded.
- This module is also supported for Windows targets.
version_added: "1.4"
options:
@ -35,13 +37,13 @@ options:
name:
version_added: "2.2"
description:
- The name of a variable into which assign the included vars, if omitted (null) they will be made top level vars.
- The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars.
default: null
depth:
version_added: "2.2"
description:
- When using C(dir), this module will, by default, recursively go through each sub directory and load up the variables.
By explicitly setting the depth, this module will only go as deep as the depth.
- When using C(dir), this module will, by default, recursively go through each sub directory and load up the
variables. By explicitly setting the depth, this module will only go as deep as the depth.
default: 0
files_matching:
version_added: "2.2"
@ -57,65 +59,65 @@ options:
version_added: "2.3"
description:
- List of file extensions to read when using C(dir).
default: ['yaml', 'yml', 'json']
default: [yaml, yml, json]
required: False
free-form:
description:
- This module allows you to specify the 'file' option directly w/o any other options.
- This module allows you to specify the 'file' option directly without any other options.
There is no 'free-form' option, this is just an indicator, see example below.
notes:
- This module is also supported for Windows targets.
'''
EXAMPLES = """
- name: Include vars of stuff.yml into the 'stuff' variable (2.2).
- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
include_vars:
file: stuff.yml
file: stuff.yaml
name: stuff
- name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
include_vars:
file: contingency_plan.yml
file: contingency_plan.yaml
name: plans
when: x == 0
- name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file.
include_vars: "{{ item }}"
with_first_found:
- "{{ ansible_distribution }}.yml"
- "{{ ansible_os_family }}.yml"
- "default.yml"
- "{{ ansible_distribution }}.yaml"
- "{{ ansible_os_family }}.yaml"
- default.yaml
- name: bare include (free-form)
include_vars: myvars.yml
- name: Bare include (free-form)
include_vars: myvars.yaml
- name: Include all .json and .jsn files in vars/all and all nested directories (2.3)
include_vars:
dir: 'vars/all'
dir: vars/all
extensions:
- json
- jsn
- name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2)
include_vars:
dir: 'vars/all'
dir: vars/all
name: test
- name: Include default extension files in vars/services (2.2)
include_vars:
dir: 'vars/services'
dir: vars/services
depth: 1
- name: Include only files matching bastion.yml (2.2)
- name: Include only files matching bastion.yaml (2.2)
include_vars:
dir: 'vars'
files_matching: 'bastion.yml'
dir: vars
files_matching: bastion.yaml
- name: Include all .yml files except bastion.yml (2.3)
- name: Include all .yaml files except bastion.yaml (2.3)
include_vars:
dir: 'vars'
ignore_files: 'bastion.yml'
extensions: ['yml']
dir: vars
ignore_files: bastion.yaml
extensions: [yaml]
"""
RETURN = '''
@ -128,6 +130,6 @@ ansible_included_var_files:
description: A list of files that were successfully included
returned: success
type: list
sample: [ '/path/to/file.yml', '/path/to/file.json' ]
sample: [ '/path/to/file.yaml', '/path/to/file.json' ]
version_added: 2.4
'''