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

Wording changes to docs (#70082)

Browse source
This commit is contained in:
Alicia Cozine 2020-12-08 15:46:34 -06:00 committed by GitHub
parent 6098793315
commit e5ccd18be4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 82 additions and 80 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
docs/docsite/rst/dev_guide/developing_plugins.rst
View file

@ -195,10 +195,10 @@ To create a callback plugin, create a new class with the Base(Callbacks) class a
.. code-block:: python
from ansible.plugins.callback import CallbackBase
from ansible.plugins.callback import CallbackBase
class CallbackModule(CallbackBase):
pass
class CallbackModule(CallbackBase):
pass
From there, override the specific methods from the CallbackBase that you want to provide a callback for.
For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with ``v2``.
@ -210,16 +210,16 @@ but with an extra option so you can see how configuration works in Ansible versi
.. code-block:: python
# Make coding more python3-ish, this is required for contributions to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
# Make coding more python3-ish, this is required for contributions to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
# not only visible to ansible-doc, it also 'declares' the options the plugin requires and how to configure them.
DOCUMENTATION = '''
# not only visible to ansible-doc, it also 'declares' the options the plugin requires and how to configure them.
DOCUMENTATION = '''
callback: timer
callback_type: aggregate
requirements:
- whitelist in configuration
- enable in configuration
short_description: Adds time to play stats
version_added: "2.0"
description:
@ -233,24 +233,24 @@ but with an extra option so you can see how configuration works in Ansible versi
env:
- name: ANSIBLE_CALLBACK_TIMER_FORMAT
default: "Playbook run took %s days, %s hours, %s minutes, %s seconds"
'''
from datetime import datetime
'''
from datetime import datetime
from ansible.plugins.callback import CallbackBase
from ansible.plugins.callback import CallbackBase
class CallbackModule(CallbackBase):
"""
This callback module tells you how long your plays ran for.
"""
CALLBACK_VERSION = 2.0
CALLBACK_TYPE = 'aggregate'
CALLBACK_NAME = 'namespace.collection_name.timer'
class CallbackModule(CallbackBase):
"""
This callback module tells you how long your plays ran for.
"""
CALLBACK_VERSION = 2.0
CALLBACK_TYPE = 'aggregate'
CALLBACK_NAME = 'namespace.collection_name.timer'
# only needed if you ship it and don't want to enable by default
CALLBACK_NEEDS_WHITELIST = True
# only needed if you ship it and don't want to enable by default
CALLBACK_NEEDS_ENABLED = True
def __init__(self):
def __init__(self):
# make sure the expected objects are present, calling the base's __init__
super(CallbackModule, self).__init__()
@ -258,14 +258,14 @@ but with an extra option so you can see how configuration works in Ansible versi
# start the timer when the plugin is loaded, the first play should start a few milliseconds after.
self.start_time = datetime.now()
def _days_hours_minutes_seconds(self, runtime):
def _days_hours_minutes_seconds(self, runtime):
''' internal helper method for this callback '''
minutes = (runtime.seconds // 60) % 60
r_seconds = runtime.seconds - (minutes * 60)
return runtime.days, runtime.seconds // 3600, minutes, r_seconds
# this is only event we care about for display, when the play shows its summary stats; the rest are ignored by the base class
def v2_playbook_on_stats(self, stats):
# this is only event we care about for display, when the play shows its summary stats; the rest are ignored by the base class
def v2_playbook_on_stats(self, stats):
end_time = datetime.now()
runtime = end_time - self.start_time
@ -273,6 +273,7 @@ but with an extra option so you can see how configuration works in Ansible versi
# Also note the use of the display object to print to screen. This is available to all callbacks, and you should use this over printing yourself
self._display.display(self._plugin_options['format_string'] % (self._days_hours_minutes_seconds(runtime)))
Note that the ``CALLBACK_VERSION`` and ``CALLBACK_NAME`` definitions are required for properly functioning plugins for Ansible version 2.0 and later. ``CALLBACK_TYPE`` is mostly needed to distinguish 'stdout' plugins from the rest, since you can only load one plugin that writes to stdout.
For example callback plugins, see the source code for the `callback plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_
@ -331,35 +332,34 @@ Here's a simple lookup plugin implementation --- this lookup returns the content
.. code-block:: python
# python 3 headers, required if submitting to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
# python 3 headers, required if submitting to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
lookup: file
author: Daniel Hokka Zakrisson <daniel@hozac.com>
version_added: "0.9"
short_description: read file contents
description:
- This lookup returns the contents from a file on the Ansible controller's file system.
options:
_terms:
description: path(s) of files to read
required: True
notes:
- if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
- this lookup does not understand globing --- use the fileglob lookup instead.
"""
from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
from ansible.utils.display import Display
DOCUMENTATION = """
lookup: file
author: Daniel Hokka Zakrisson <daniel@hozac.com>
version_added: "0.9"
short_description: read file contents
description:
- This lookup returns the contents from a file on the Ansible controller's file system.
options:
_terms:
description: path(s) of files to read
required: True
notes:
- if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
- this lookup does not understand globing --- use the fileglob lookup instead.
"""
from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
from ansible.utils.display import Display
display = Display()
display = Display()
class LookupModule(LookupBase):
class LookupModule(LookupBase):
def run(self, terms, variables=None, **kwargs):
def run(self, terms, variables=None, **kwargs):
# lookups in general are expected to both take a list as input and output a list
@ -389,7 +389,10 @@ Here's a simple lookup plugin implementation --- this lookup returns the content
return ret
The following is an example of how this lookup is called::
The following is an example of how this lookup is called:
.. code-block:: YAML
---
- hosts: all
@ -401,6 +404,7 @@ The following is an example of how this lookup is called::
- debug:
msg: the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}
For example lookup plugins, see the source code for the `lookup plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
For more usage examples of lookup plugins, see :ref:`Using Lookups<playbooks_lookups>`.
@ -451,12 +455,12 @@ This ``get_vars`` method just needs to return a dictionary structure with the va
Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a task. This avoids the costly 'always execute' behavior that occurred during inventory construction in older versions of Ansible. Since Ansible version 2.10, vars plugin execution can be toggled by the user to run when preparing to execute a task or after importing an inventory source.
Since Ansible 2.10, vars plugins can require whitelisting. Vars plugins that don't require whitelisting will run by default. To require whitelisting for your plugin set the class variable ``REQUIRES_WHITELIST``:
You can create vars plugins that are not enabled by default using the class variable ``REQUIRES_ENABLED``. If your vars plugin resides in a collection, it cannot be enabled by default. You must use ``REQUIRES_ENABLED`` in all collections-based vars plugins. To require users to enable your plugin, set the class variable ``REQUIRES_ENABLED``:
.. code-block:: python
class VarsModule(BaseVarsPlugin):
REQUIRES_WHITELIST = True
REQUIRES_ENABLED = True
Include the ``vars_plugin_staging`` documentation fragment to allow users to determine when vars plugins run.
@ -478,8 +482,6 @@ Include the ``vars_plugin_staging`` documentation fragment to allow users to det
- vars_plugin_staging
'''
Also since Ansible 2.10, vars plugins can reside in collections. Vars plugins in collections must require whitelisting to be functional.
For example vars plugins, see the source code for the `vars plugins included with Ansible Core
<https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_.

2
docs/docsite/rst/dev_guide/testing_running_locally.rst
View file

@ -44,7 +44,7 @@ Environment Variables
When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options.
* Not exposed to the test environment unless whitelisted in ``test/lib/ansible_test/_internal/util.py`` in the ``common_environment`` function.
* Not exposed to the test environment unless enabled in ``test/lib/ansible_test/_internal/util.py`` in the ``common_environment`` function.
Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --venv``. However, using the ``--docker`` option would
require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set

2
docs/docsite/rst/galaxy/dev_guide.rst
View file

@ -141,7 +141,7 @@ By default the command will wait for Galaxy to complete the import process, disp
Successfully submitted import request 41
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
Retrieving GitHub repo githubuser/ansible-role-repo
Accessing branch: master
Accessing branch: devel
Parsing and validating meta/main.yml
Parsing galaxy_tags
Parsing platforms

10
docs/docsite/rst/galaxy/user_guide.rst
View file

@ -160,7 +160,7 @@ This returns everything found in Galaxy for the role:
scm: None
src: username.repo_name
stargazers_count: 0
travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=main
version:
watchers_count: 1
@ -279,7 +279,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
# from GitHub, overriding the name and specifying a specific tag
- name: nginx_role
src: https://github.com/bennojoy/nginx
version: master
version: main
# from GitHub, specifying a specific commit hash
- src: https://github.com/bennojoy/nginx
@ -287,15 +287,15 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
# from a webserver, where the role is packaged in a tar.gz
- name: http-role-gz
src: https://some.webserver.example.com/files/master.tar.gz
src: https://some.webserver.example.com/files/main.tar.gz
# from a webserver, where the role is packaged in a tar.bz2
- name: http-role-bz2
src: https://some.webserver.example.com/files/master.tar.bz2
src: https://some.webserver.example.com/files/main.tar.bz2
# from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
- name: http-role-xz
src: https://some.webserver.example.com/files/master.tar.xz
src: https://some.webserver.example.com/files/main.tar.xz
# from Bitbucket
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy

4
docs/docsite/rst/plugins/callback.rst
View file

@ -30,11 +30,11 @@ You can activate a custom callback by either dropping it into a ``callback_plugi
Plugins are loaded in alphanumeric order. For example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`.
Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :ref:`ansible.cfg <ansible_configuration_settings>` file in order to function. For example:
Most callbacks shipped with Ansible are disabled by default and need to be enabled in your :ref:`ansible.cfg <ansible_configuration_settings>` file in order to function. For example:
.. code-block:: ini
#callback_whitelist = timer, mail, profile_roles, collection_namespace.collection_name.custom_callback
#callback_enabled = timer, mail, profile_roles, collection_namespace.collection_name.custom_callback
Setting a callback plugin for ``ansible-playbook``
--------------------------------------------------

4
docs/docsite/rst/plugins/vars.rst
View file

@ -21,9 +21,9 @@ Enabling vars plugins
You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
Starting in Ansible 2.10, vars plugins can require whitelisting rather than running by default. To enable a plugin that requires whitelisting set ``vars_plugins_enabled`` in the ``defaults`` section of :ref:`ansible.cfg <ansible_configuration_settings>` or set the ``ANSIBLE_VARS_ENABLED`` environment variable to the list of vars plugins you want to execute. By default, the :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible is whitelisted.
Most vars plugins are disabled by default. To enable a vars plugin, set ``vars_plugins_enabled`` in the ``defaults`` section of :ref:`ansible.cfg <ansible_configuration_settings>` or set the ``ANSIBLE_VARS_ENABLED`` environment variable to the list of vars plugins you want to execute. By default, the :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible is enabled.
Starting in Ansible 2.10, you can use vars plugins in collections. All vars plugins in collections require whitelisting and need to use the fully qualified collection name in the format ``namespace.collection_name.vars_plugin_name``.
Starting in Ansible 2.10, you can use vars plugins in collections. All vars plugins in collections must be explicitly enabled and must use the fully qualified collection name in the format ``namespace.collection_name.vars_plugin_name``.
.. code-block:: yaml

2
docs/docsite/rst/porting_guides/porting_guide_2.0.rst
View file

@ -97,7 +97,7 @@ uses key=value escaping which has not changed. The other option is to check for
If you need the old behavior, quote the value to pass it around as a string.
* Empty variables and variables set to null in yaml are no longer converted to empty strings. They will retain the value of `None`.
You can override the `null_representation` setting to an empty string in your config file by setting the :envvar:`ANSIBLE_NULL_REPRESENTATION` environment variable.
* Extras callbacks must be whitelisted in ansible.cfg. Copying is no longer necessary but whitelisting in ansible.cfg must be completed.
* Extras callbacks must be enabled in ansible.cfg. Copying is no longer necessary but you must enable them in ansible.cfg.
* dnf module has been rewritten. Some minor changes in behavior may be observed.
* win_updates has been rewritten and works as expected now.
* from 2.0.1 onwards, the implicit setup task from gather_facts now correctly inherits everything from play, but this might cause issues for those setting

6
docs/docsite/rst/roadmap/ROADMAP_2_5.rst
View file

@ -60,8 +60,8 @@ Vault
-----
- Vault secrets client inc new 'keyring' client
Runtime Check on Modules for Blacklisting
-----------------------------------------
Runtime Check on Modules for Disabling
--------------------------------------
- Filter on things like "supported_by" in module metadata
- Provide users with an option of "warning, error or allow/ignore"
- Configurable via ansible.cfg and environment variable
@ -80,7 +80,7 @@ Windows
- win_updates **(done)**
- Fix win_updates to detect (or request) become
- Add whitelist/blacklist features to win_updates
- Add enable/disable features to win_updates
- win_dsc further improvements **(done)**
General Cloud

2
docs/docsite/rst/user_guide/playbooks_filters.rst
View file

@ -1306,7 +1306,7 @@ An idempotent method to generate unique hashes per system is to use a salt that
{{ 'secretpassword' | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }}
Hash types available depend on the master system running Ansible, 'hash' depends on hashlib, password_hash depends on passlib (https://passlib.readthedocs.io/en/stable/lib/passlib.hash.html).
Hash types available depend on the control system running Ansible, 'hash' depends on hashlib, password_hash depends on passlib (https://passlib.readthedocs.io/en/stable/lib/passlib.hash.html).
.. versionadded:: 2.7

4
docs/docsite/rst/user_guide/playbooks_reuse.rst
View file

@ -24,14 +24,14 @@ Ansible offers four distributed, re-usable artifacts: variables files, task file
Re-using playbooks
==================
You can incorporate multiple playbooks into a master playbook. However, you can only use imports to re-use playbooks. For example:
You can incorporate multiple playbooks into a main playbook. However, you can only use imports to re-use playbooks. For example:
.. code-block:: yaml
- import_playbook: webservers.yml
- import_playbook: databases.yml
Importing incorporates playbooks in other playbooks statically. Ansible runs the plays and tasks in each imported playbook in the order they are listed, just as if they had been defined directly in the master playbook.
Importing incorporates playbooks in other playbooks statically. Ansible runs the plays and tasks in each imported playbook in the order they are listed, just as if they had been defined directly in the main playbook.
Re-using files and roles
========================

12
docs/docsite/rst/user_guide/plugin_filtering_config.rst
View file

@ -1,15 +1,15 @@
.. _plugin_filtering_config:
Blacklisting modules
====================
Rejecting modules
=================
If you want to avoid using certain modules, you can blacklist them to prevent Ansible from loading them. To blacklist plugins, create a yaml configuration file. The default location for this file is :file:`/etc/ansible/plugin_filters.yml`, or you can select a different path for the blacklist file using the :ref:`PLUGIN_FILTERS_CFG` setting in the ``defaults`` section of your ansible.cfg. Here is an example blacklist file:
If you want to avoid using certain modules, you can add them to a reject list to prevent Ansible from loading them. To reject plugins, create a yaml configuration file. The default location for this file is :file:`/etc/ansible/plugin_filters.yml`. You can select a different path for the reject list using the :ref:`PLUGIN_FILTERS_CFG` setting in the ``defaults`` section of your ansible.cfg. Here is an example reject list:
.. code-block:: YAML
---
filter_version: '1.0'
module_blacklist:
module_rejectlist:
# Deprecated
- docker
# We only allow pip, not easy_install
@ -19,8 +19,8 @@ The file contains two fields:
* A file version so that you can update the format while keeping backwards compatibility in the future. The present version should be the string, ``"1.0"``
* A list of modules to blacklist. Any module in this list will not be loaded by Ansible when it searches for a module to invoke for a task.
* A list of modules to reject. Ansible will not load any module in this list when it searches for a module to invoke for a task.
.. note::
You cannot blacklist the ``stat`` module, as it is required for Ansible to run.
The ``stat`` module is required for Ansible to run. Do not add this module to your reject list.

2
docs/docsite/rst/user_guide/sample_setup.rst
View file

@ -30,7 +30,7 @@ This layout organizes most tasks in roles, with a single inventory file for each
module_utils/ # if any custom module_utils to support modules, put them here (optional)
filter_plugins/ # if any custom filter plugins, put them here (optional)
site.yml # master playbook
site.yml # main playbook
webservers.yml # playbook for webserver tier
dbservers.yml # playbook for dbserver tier
tasks/ # task files included from playbooks