diff options
29 files changed, 90 insertions, 87 deletions
diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index d3d1528efc..1562ed42c6 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -394,7 +394,7 @@ This is an example using an extract from a YAML inventory, as the INI format do ... To use an inline vaulted variables with an INI inventory you need to store it in a 'vars' file in YAML format, -it can reside in host_vars/ or group_vars/ to be automatically picked up or referenced from a play via ``vars_files`` or ``include_vars``. +it can reside in host_vars/ or group_vars/ to be automatically picked up or referenced from a play through ``vars_files`` or ``include_vars``. To run a playbook with this setup, drop the ``-k`` flag and add a flag for your ``vault-id``: diff --git a/docs/docsite/rst/network/getting_started/index.rst b/docs/docsite/rst/network/getting_started/index.rst index d9638a5c9a..bf9f2eb01b 100644 --- a/docs/docsite/rst/network/getting_started/index.rst +++ b/docs/docsite/rst/network/getting_started/index.rst @@ -8,7 +8,7 @@ Ansible collections support a wide range of vendors, device types, and actions, - Automate repetitive tasks to speed routine network changes and free up your time for more strategic work - Leverage the same simple, powerful, and agentless automation tool for network tasks that operations and development use -- Separate the data model (in a playbook or role) from the execution layer (via Ansible modules) to manage heterogeneous network devices +- Separate the data model (in a playbook or role) from the execution layer (through Ansible modules) to manage heterogeneous network devices - Benefit from community and vendor-generated sample playbooks and roles to help accelerate network automation projects - Communicate securely with network hardware over SSH or HTTPS diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 8785d715fe..202814b304 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -326,7 +326,7 @@ Error: "Authentication failed" **Platforms:** Any -Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible-connection`` (via ``ansible`` or ``ansible-playbook``) can not be used to connect to the remote device. +Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible-connection`` (through ``ansible`` or ``ansible-playbook``) can not be used to connect to the remote device. @@ -340,7 +340,7 @@ For example: Suggestions to resolve: -If you are specifying credentials via ``password:`` (either directly or via ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this: +If you are specifying credentials through ``password:`` (either directly or through ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this: .. code-block:: yaml @@ -728,9 +728,9 @@ Example Ansible inventory file ansible_password=!vault... -.. note:: Using ``ProxyCommand`` with passwords via variables +.. note:: Using ``ProxyCommand`` with passwords through variables - By design, SSH doesn't support providing passwords via environment variables. + By design, SSH doesn't support providing passwords through environment variables. This is done to prevent secrets from leaking out, for example in ``ps`` output. We recommend using SSH Keys, and if needed an ssh-agent, rather than passwords, where ever possible. diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index 87dec31bd6..a628164655 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -41,7 +41,7 @@ All tasks in a block inherit directives applied at the block level. Most of what when: ansible_facts['distribution'] == 'CentOS' become: true become_user: root - ignore_errors: yes + ignore_errors: true In the example above, the 'when' condition will be evaluated before Ansible runs each of the three tasks in the block. All three tasks also inherit the privilege escalation directives, running as the root user. Finally, ``ignore_errors: yes`` ensures that Ansible continues to execute the playbook even if some of the tasks fail. @@ -153,7 +153,7 @@ You can use blocks with ``flush_handlers`` in a rescue task to ensure that all h - name: Print a message ansible.builtin.debug: msg: 'I execute normally' - changed_when: yes + changed_when: true notify: run me even after an error - name: Force a failure diff --git a/docs/docsite/rst/playbook_guide/playbooks_checkmode.rst b/docs/docsite/rst/playbook_guide/playbooks_checkmode.rst index 9c131d86b3..4b21f7cf92 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_checkmode.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_checkmode.rst @@ -37,14 +37,14 @@ For example: tasks: - name: This task will always make changes to the system ansible.builtin.command: /something/to/run --even-in-check-mode - check_mode: no + check_mode: false - name: This task will never make changes to the system ansible.builtin.lineinfile: line: "important config" dest: /path/to/myconfig.conf state: present - check_mode: yes + check_mode: true register: changes_to_important_config Running single tasks with ``check_mode: yes`` can be useful for testing Ansible modules, either to test the module itself or to test the conditions under which a module would make changes. You can register variables (see :ref:`playbooks_conditionals`) on these tasks for even more detail on the potential changes. @@ -104,4 +104,4 @@ Because the ``--diff`` option can reveal sensitive information, you can disable owner: root group: root mode: '0600' - diff: no + diff: false diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst index b13a7bd33a..f920fd74b4 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst @@ -29,7 +29,7 @@ The simplest conditional statement applies to a single task. Create the task, th ansible.posix.seboolean: name: mysql_connect_any state: true - persistent: yes + persistent: true when: ansible_selinux.status == "enabled" # all variables can be used directly in conditionals without double curly braces diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 79ac720e09..79d7c31ee0 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -138,7 +138,7 @@ After Ansible invokes the debugger, you can use the seven :ref:`debugger command - hosts: test debugger: on_failed - gather_facts: no + gather_facts: false vars: var1: value1 tasks: @@ -253,7 +253,7 @@ Update args command - hosts: test strategy: debug - gather_facts: yes + gather_facts: true vars: pkg_name: not_exist tasks: diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index 389ef0b28d..d94fc1ef46 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -20,7 +20,7 @@ By default Ansible stops executing tasks on a host when a task fails on that hos - name: Do not count this as a failure ansible.builtin.command: /bin/false - ignore_errors: yes + ignore_errors: true The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors. @@ -37,7 +37,7 @@ You can ignore a task failure due to the host instance being 'UNREACHABLE' with - name: This executes, fails, and the failure is ignored ansible.builtin.command: /bin/true - ignore_unreachable: yes + ignore_unreachable: true - name: This executes, fails, and ends the play for this host ansible.builtin.command: /bin/true @@ -47,14 +47,14 @@ And at the playbook level: .. code-block:: yaml - hosts: all - ignore_unreachable: yes + ignore_unreachable: true tasks: - name: This executes, fails, and the failure is ignored ansible.builtin.command: /bin/true - name: This executes, fails, and ends the play for this host ansible.builtin.command: /bin/true - ignore_unreachable: no + ignore_unreachable: false .. _resetting_unreachable: diff --git a/docs/docsite/rst/playbook_guide/playbooks_intro.rst b/docs/docsite/rst/playbook_guide/playbooks_intro.rst index 75be4e8322..8592b0429f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_intro.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_intro.rst @@ -116,7 +116,7 @@ Assuming you load balance your checkout location, ``ansible-pull`` scales essent Run ``ansible-pull --help`` for details. -There's also a `clever playbook <https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to configure ``ansible-pull`` via a crontab from push mode. +There's also a `clever playbook <https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to configure ``ansible-pull`` through a crontab from push mode. Verifying playbooks =================== diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index a2090ccbf1..5e8afdeafb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -239,7 +239,7 @@ You can use Jinja2 expressions to iterate over complex lists. For example, a loo community.mysql.mysql_user: name: "{{ item[0] }}" priv: "{{ item[1] }}.*:ALL" - append_privs: yes + append_privs: true password: "foo" loop: "{{ ['alice', 'bob'] | product(['clientdb', 'employeedb', 'providerdb']) | list }}" @@ -448,7 +448,7 @@ Variable Description :: loop_control: - extended: yes + extended: true .. note:: When using ``loop_control.extended`` more memory will be utilized on the control node. This is a result of ``ansible_loop.allitems`` containing a reference to the full loop data for every loop. When serializing the results for display in callback plugins within the main ansible process, these references may be dereferenced causing memory usage to increase. @@ -459,8 +459,8 @@ To disable the ``ansible_loop.allitems`` item, to reduce memory consumption, set :: loop_control: - extended: yes - extended_allitems: no + extended: true + extended_allitems: false Accessing the name of your loop_var ----------------------------------- @@ -468,7 +468,7 @@ Accessing the name of your loop_var As of Ansible 2.8 you can get the name of the value provided to ``loop_control.loop_var`` using the ``ansible_loop_var`` variable -For role authors, writing roles that allow loops, instead of dictating the required ``loop_var`` value, you can gather the value via the following +For role authors, writing roles that allow loops, instead of dictating the required ``loop_var`` value, you can gather the value through the following .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst index 3b28d385a8..7222ab3396 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst @@ -42,7 +42,7 @@ For example, to manage a system service (which requires ``root`` privileges) whe service: name: httpd state: started - become: yes + become: true To run a command as the ``apache`` user: @@ -50,7 +50,7 @@ To run a command as the ``apache`` user: - name: Run a command as the apache user command: somecommand - become: yes + become: true become_user: apache To do something as the ``nobody`` user when the shell is nologin: @@ -59,7 +59,7 @@ To do something as the ``nobody`` user when the shell is nologin: - name: Run a command as nobody command: somecommand - become: yes + become: true become_method: su become_user: nobody become_flags: '-s /bin/sh' @@ -316,7 +316,7 @@ To set ``enable`` mode for a specific task, add ``become`` at the task level: arista.eos.eos_facts: gather_subset: - "!hardware" - become: yes + become: true become_method: enable To set enable mode for all tasks in a single play, add ``become`` at the play level: @@ -324,7 +324,7 @@ To set enable mode for all tasks in a single play, add ``become`` at the play le .. code-block:: yaml - hosts: eos-switches - become: yes + become: true become_method: enable tasks: - name: Gather facts (eos) @@ -344,7 +344,7 @@ Often you wish for all tasks in all plays to run using privilege mode, that is b ansible_connection: ansible.netcommon.network_cli ansible_network_os: arista.eos.eos ansible_user: myuser - ansible_become: yes + ansible_become: true ansible_become_method: enable Passwords for enable mode @@ -374,7 +374,7 @@ Ansible still supports ``enable`` mode with ``connection: local`` for legacy net gather_subset: - "!hardware" provider: - authorize: yes + authorize: true auth_pass: " {{ secret_auth_pass }}" We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode consistently. The use of ``authorize`` and of ``provider`` dictionaries will be deprecated in future. Check the :ref:`platform_options` documentation for details. @@ -423,7 +423,7 @@ task: - Check my user name ansible.windows.win_whoami: - become: yes + become: true The output will look something similar to the below: @@ -725,9 +725,9 @@ Here are some examples of how to use ``become_flags`` with Windows tasks: ansible.windows.win_copy: src: \\server\share\data\file.txt dest: C:\temp\file.txt - remote_src: yes + remote_src: true vars: - ansible_become: yes + ansible_become: true ansible_become_method: runas ansible_become_user: DOMAIN\user ansible_become_password: Password01 @@ -735,12 +735,12 @@ Here are some examples of how to use ``become_flags`` with Windows tasks: - name: run a command under a batch logon ansible.windows.win_whoami: - become: yes + become: true become_flags: logon_type=batch - name: run a command and not load the user profile ansible.windows.win_whomai: - become: yes + become: true become_flags: logon_flags= diff --git a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst index 61bd034ba0..1afb3fa028 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst @@ -19,7 +19,7 @@ Here is a most basic example: - name: username prompt: What is your username? - private: no + private: false - name: password prompt: What is your password? @@ -56,9 +56,9 @@ You can hash the entered value so you can use it, for instance, with the user mo - name: my_password2 prompt: Enter password2 - private: yes + private: true encrypt: sha512_crypt - confirm: yes + confirm: true salt_size: 7 If you have `Passlib <https://passlib.readthedocs.io/en/stable/>`_ installed, you can use any crypt scheme the library supports: @@ -107,8 +107,8 @@ Some special characters, such as ``{`` and ``%`` can create templating errors. I vars_prompt: - name: my_password_with_weird_chars prompt: Enter password - unsafe: yes - private: yes + unsafe: true + private: true .. seealso:: diff --git a/docs/docsite/rst/playbook_guide/playbooks_python_version.rst b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst index efcadb229c..ee18b60713 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_python_version.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst @@ -16,7 +16,7 @@ Dictionary views ================ In Python2, the :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items` -methods return a list. Jinja2 returns that to Ansible via a string +methods return a list. Jinja2 returns that to Ansible using a string representation that Ansible can turn back into a list. In Python3, those methods return a :ref:`dictionary view <python3:dict-views>` object. The diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst index 3731351774..89cc5a4216 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst @@ -17,7 +17,7 @@ Ansible offers four distributed, re-usable artifacts: variables files, task file - A variables file contains only variables. - A task file contains only tasks. - A playbook contains at least one play, and may contain variables, tasks, and other content. You can re-use tightly focused playbooks, but you can only re-use them statically, not dynamically. - - A role contains a set of related tasks, variables, defaults, handlers, and even modules or other plugins in a defined file-tree. Unlike variables files, task files, or playbooks, roles can be easily uploaded and shared via Ansible Galaxy. See :ref:`playbooks_reuse_roles` for details about creating and using roles. + - A role contains a set of related tasks, variables, defaults, handlers, and even modules or other plugins in a defined file-tree. Unlike variables files, task files, or playbooks, roles can be easily uploaded and shared through Ansible Galaxy. See :ref:`playbooks_reuse_roles` for details about creating and using roles. .. versionadded:: 2.4 diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index dee8573752..dc230da2da 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -324,8 +324,7 @@ role ``meta/argument_specs.yml`` file. All fields are lower-case. * Ensure that the default value in the docs matches the default value in the code. The actual default for the role variable will always come from ``defaults/main.yml``. * The default field must not be listed as part of the description, unless it requires additional information or conditions. - * If the option is a boolean value, you can use any of the boolean values recognized by Ansible: - (such as true/false or yes/no). Choose the one that reads better in the context of the option. + * If the option is a boolean value, you should use `true/false` if you want to be compatible with `ansible-lint`. :choices: diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 0e176d0f3a..4da0af02f4 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -67,7 +67,7 @@ You can apply the same tag to more than one individual task. This example tags s ansible.builtin.service: name: ntpd state: started - enabled: yes + enabled: true tags: ntp - name: Install NFS utils @@ -147,7 +147,7 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use ansible.builtin.service: name: ntpd state: started - enabled: yes + enabled: true - name: Install NFS utils ansible.builtin.yum: @@ -183,7 +183,7 @@ If all the tasks in a play should get the same tag, you can add the tag at the l ansible.builtin.service: name: ntpd state: started - enabled: yes + enabled: true - hosts: fileservers tags: filesharing diff --git a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst index 3e8cb5ce80..e90947e6f5 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst @@ -537,7 +537,7 @@ By default, Ansible gathers facts at the beginning of each play. If you do not n .. code-block:: yaml - hosts: whatever - gather_facts: no + gather_facts: false Adding custom facts ------------------- @@ -615,7 +615,7 @@ By default, fact gathering runs once at the beginning of each play. If you creat - name: Create directory for ansible custom facts ansible.builtin.file: state: directory - recurse: yes + recurse: true path: /etc/ansible/facts.d - name: Install custom ipmi fact diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 67a8c461c4..9efa1b810a 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -42,7 +42,7 @@ uses key=value escaping which has not changed. The other option is to check for "{{ (ansible_version|version_compare('2.0', 'ge'))|ternary( 'test1_junk 1\\3' | regex_replace('(.*)_junk (.*)', '\\1 \\2') , 'test1_junk 1\\\\3' | regex_replace('(.*)_junk (.*)', '\\\\1 \\\\2') ) }}" * trailing newline When a string with a trailing newline was specified in the - playbook via yaml dict format, the trailing newline was stripped. When + playbook through yaml dict format, the trailing newline was stripped. When specified in key=value format, the trailing newlines were kept. In v2, both methods of specifying the string will keep the trailing newlines. If you relied on the trailing newline being stripped, you can change your playbook @@ -149,7 +149,7 @@ Should now be:: a: 1 * Setting any_errors_fatal on a task is no longer supported. This should be set at the play level only. -* Bare variables in the `environment` dictionary (for plays/tasks/etc.) are no longer supported. Variables specified there should use the full variable syntax: '{{foo}}'. +* Bare variables in the `environment` dictionary (for plays/tasks/and so on) are no longer supported. Variables specified there should use the full variable syntax: '{{foo}}'. * Tags (or any directive) should no longer be specified with other parameters in a task include. Instead, they should be specified as an option on the task. For example:: diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst index 678c28edaa..ff0a1eff69 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst @@ -43,8 +43,8 @@ Command Line ============ * The ``ansible-galaxy login`` command has been removed, as the underlying API it used for GitHub auth is being shut down. Publishing roles or - collections to Galaxy via ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI via a token file (default location - ``~/.ansible/galaxy_token``) or (insecurely) via the ``--token`` argument to ``ansible-galaxy``. + collections to Galaxy through ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI through a token file (default location + ``~/.ansible/galaxy_token``) or (insecurely) through the ``--token`` argument to ``ansible-galaxy``. Deprecated @@ -80,7 +80,7 @@ Plugins Lookup plugin names case-sensitivity ------------------------------------ -* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. +* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked through ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. Noteworthy plugin changes ------------------------- @@ -232,7 +232,7 @@ netbox.netbox - nb_inventory - Move around ``extracted_primary_ip`` to allow for ``config_context`` or ``custom_field`` to overwrite. (#377) - nb_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396) - nb_lookup - Allow ID to be passed in and use ``.get`` instead of ``.filter``. (#376) -- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found via env. (#391) +- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found through env. (#391) Deprecated Features ------------------- @@ -567,7 +567,7 @@ netbox.netbox ``netbox.netbox.netbox`` would be used for both inventory plugin and lookup plugin, but in different contexts so no collision will arise, but confusion will. I renamed the lookup plugin to ``nb_lookup`` so it will be used with the FQCN ``netbox.netbox.nb_lookup``. The inventory plugin will now be called within an inventory file by ``netbox.netbox.nb_inventory`` -- To pass in integers via Ansible Jinja filters for a key in ``data`` that +- To pass in integers through Ansible Jinja filters for a key in ``data`` that requires querying an endpoint is now done by making it a dictionary with an ``id`` key. The previous behavior was to just pass in an integer and it was converted when normalizing the data, but some people may have names @@ -674,7 +674,7 @@ community.kubernetes - k8s - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_auth - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_config_resource_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection. -- k8s_exec - New module for executing commands on pods via Kubernetes API (https://github.com/ansible-collections/community.kubernetes/pull/14). +- k8s_exec - New module for executing commands on pods through Kubernetes API (https://github.com/ansible-collections/community.kubernetes/pull/14). - k8s_exec - Return rc for the command executed (https://github.com/ansible-collections/community.kubernetes/pull/158). - k8s_info - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_log - New module for retrieving pod logs (https://github.com/ansible-collections/community.kubernetes/pull/16). @@ -952,7 +952,7 @@ community.vmware community.zabbix ~~~~~~~~~~~~~~~~ -- zabbix_proxy (module) - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive via ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place. +- zabbix_proxy (module) - deprecates ``interface`` sub-options ``type`` and ``main`` when proxy type is set to passive through ``status=passive``. Make sure these suboptions are removed from your playbook as they were never supported by Zabbix in the first place. f5networks.f5_modules ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst index d20d74ece9..9a66c23d0f 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.3.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.3.rst @@ -92,7 +92,7 @@ Use of multiple tags Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last specified tag overriding all the other specified tags. This behaviour is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behaviour. -In 2.4, the default will be to merge the tags. You can enable the old overwriting behavior via the config option. +In 2.4, the default will be to merge the tags. You can enable the old overwriting behavior through the config option. In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behaviour. @@ -219,8 +219,8 @@ Will result in: transport: cli host: "{{ ansible_host }}" -delegate_to vs ProxyCommand ---------------------------- +ProxyCommand replaces delegate_to +--------------------------------- The new connection framework for Network Modules in Ansible 2.3 that uses ``cli`` transport no longer supports the use of the ``delegate_to`` directive. @@ -228,6 +228,6 @@ In order to use a bastion or intermediate jump host to connect to network device transport, network modules now support the use of ``ProxyCommand``. To use ``ProxyCommand`` configure the proxy settings in the Ansible inventory -file to specify the proxy host via ``ansible_ssh_common_args``. +file to specify the proxy host through ``ansible_ssh_common_args``. For details on how to do this see the :ref:`network proxy guide <network_delegate_to_vs_ProxyCommand>`. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.4.rst b/docs/docsite/rst/porting_guides/porting_guide_2.4.rst index 52bb0e3c91..d58ae48d13 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.4.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.4.rst @@ -25,7 +25,7 @@ Ansible will not support Python 2.4 or 2.5 on the target hosts anymore. Going fo Inventory ========= -Inventory has been refactored to be implemented via plugins and now allows for multiple sources. This change is mostly transparent to users. +Inventory has been refactored to be implemented through plugins and now allows for multiple sources. This change is mostly transparent to users. One exception is the ``inventory_dir``, which is now a host variable; previously it could only have one value so it was set globally. This means you can no longer use it early in plays to determine ``hosts:`` or similar keywords. @@ -63,7 +63,7 @@ Use of multiple tags Specifying ``--tags`` (or ``--skip-tags``) multiple times on the command line currently leads to the last one overriding all the previous ones. This behavior is deprecated. In the future, if you specify --tags multiple times the tags will be merged together. From now on, using ``--tags`` multiple times on one command line will emit a deprecation warning. Setting the ``merge_multiple_cli_tags`` option to True in the ``ansible.cfg`` file will enable the new behavior. -In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior via the config option. +In 2.4, the default has change to merge the tags. You can enable the old overwriting behavior through the config option. In 2.5, multiple ``--tags`` options will be merged with no way to go back to the old behavior. @@ -124,7 +124,7 @@ The most notable difference to users is that vars plugins now get invoked on dem Inventory plugins ----------------- -Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work via the ``script`` inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts. +Developers should start migrating from hardcoded inventory with dynamic inventory scripts to the new Inventory Plugins. The scripts will still work through the ``script`` inventory plugin but Ansible development efforts will now concentrate on writing plugins rather than enhancing existing scripts. Both users and developers should look into the new plugins because they are intended to alleviate the need for many of the hacks and workarounds found in the dynamic inventory scripts. @@ -138,7 +138,7 @@ Users: Developers: -* If your callback does not inherit from ``CallbackBase`` (directly or indirectly via another callback), it will still work, but issue a deprecation notice. +* If your callback does not inherit from ``CallbackBase`` (directly or indirectly through another callback), it will still work, but issue a deprecation notice. To avoid this and ensure it works in the future change it to inherit from ``CallbackBase`` so it has the new options handling methods and properties. You can also implement the new options handling methods and properties but that won't automatically inherit changes added in the future. You can look at ``CallbackBase`` itself and/or ``AnsiblePlugin`` for details. * Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.7.rst b/docs/docsite/rst/porting_guides/porting_guide_2.7.rst index 27a6a99fc0..0ab53655d0 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.7.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.7.rst @@ -40,7 +40,7 @@ One thing that this does affect is the ability to use :command:`/usr/bin/ansible a host which has Python-2.6. ``ansible-pull`` runs on the host being managed but it is a controller script, not a module so it will need an updated Python. Actively developed Linux distros which ship with Python-2.6 have some means to install newer Python versions (For instance, you can install -Python-2.7 via an SCL on RHEL-6) but you may need to also install Python bindings for many common +Python-2.7 through an SCL on RHEL-6) but you may need to also install Python bindings for many common modules to work (For RHEL-6, for instance, selinux bindings and yum would have to be installed for the updated Python install). @@ -123,8 +123,8 @@ If you are the author of a third-party module which uses ``__file__`` with ``Ans + package = os.path.join(module.tmpdir, to_native(deb.rsplit('/', 1)[1])) -Using a loop on a package module via squash_actions ---------------------------------------------------- +Using a loop on a package module through squash_actions +------------------------------------------------------- The use of ``squash_actions`` to invoke a package module, such as "yum", to only invoke the module once is deprecated, and will be removed in Ansible 2.11. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index 4e0669410d..1f3903476e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -347,7 +347,7 @@ Deprecated removed in 2.12. If you need the old behavior switch to ``FactCache.first_order_merge()`` instead. -* Supporting file-backed caching via self.cache is deprecated and will +* Supporting file-backed caching through self.cache is deprecated and will be removed in Ansible 2.12. If you maintain an inventory plugin, update it to use ``self._cache`` as a dictionary. For implementation details, see the :ref:`developer guide on inventory plugins<inventory_plugin_caching>`. @@ -543,7 +543,7 @@ Plugins * ``osx_say`` callback plugin was renamed into :ref:`say <say_callback>`. -* Inventory plugins now support caching via cache plugins. To start using a cache plugin with your inventory see the section on caching in the :ref:`inventory guide<using_inventory>`. To port a custom cache plugin to be compatible with inventory see :ref:`developer guide on cache plugins<developing_cache_plugins>`. +* Inventory plugins now support caching through cache plugins. To start using a cache plugin with your inventory see the section on caching in the :ref:`inventory guide<using_inventory>`. To port a custom cache plugin to be compatible with inventory see :ref:`developer guide on cache plugins<developing_cache_plugins>`. Porting custom scripts ====================== diff --git a/docs/docsite/rst/porting_guides/porting_guide_3.rst b/docs/docsite/rst/porting_guides/porting_guide_3.rst index 2f387bb903..12ec21cd08 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_3.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_3.rst @@ -262,7 +262,7 @@ community.general - The Google cloud inventory script ``gce.py`` has been migrated to the ``community.google`` collection. Install the ``community.google`` collection in order to continue using it. - archive - remove path folder itself when ``remove`` parameter is true (https://github.com/ansible-collections/community.general/issues/1041). - log_plays callback - add missing information to the logs generated by the callback plugin. This changes the log message format (https://github.com/ansible-collections/community.general/pull/442). -- passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old ``key: value`` parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, e.g. ``foo: [bar, baz]`` will become a list with two elements in the new version, but a string ``'[bar, baz]'`` in the old (https://github.com/ansible-collections/community.general/issues/1673). +- passwordstore lookup plugin - now parsing a password store entry as YAML if possible, skipping the first line (which by convention only contains the password and nothing else). If it cannot be parsed as YAML, the old ``key: value`` parser will be used to process the entry. Can break backwards compatibility if YAML formatted code was parsed in a non-YAML interpreted way, for example ``foo: [bar, baz]``, will become a list with two elements in the new version, but a string ``'[bar, baz]'`` in the old (https://github.com/ansible-collections/community.general/issues/1673). - pkgng - passing ``name: *`` with ``state: absent`` will no longer remove every installed package from the system. It is now a noop. (https://github.com/ansible-collections/community.general/pull/569). - pkgng - passing ``name: *`` with ``state: latest`` or ``state: present`` will no longer install every package from the configured package repositories. Instead, ``name: *, state: latest`` will upgrade all already-installed packages, and ``name: *, state: present`` is a noop. (https://github.com/ansible-collections/community.general/pull/569). - proxmox_kvm - recognize ``force=yes`` in conjunction with ``state=absent`` to forcibly remove a running VM (https://github.com/ansible-collections/community.general/pull/849). @@ -314,7 +314,7 @@ dellemc.os10 ngine_io.cloudstack ~~~~~~~~~~~~~~~~~~~ -- Authentication option using INI files e.g. ``cloudstack.ini`` has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables. +- Authentication option using INI files for example ``cloudstack.ini``, has been removed. The only supported option to authenticate is by using the module params with fallback to the ENV variables. - default zone deprecation - The `zone` param default value, across multiple modules, has been deprecated due to unreliable API (https://github.com/ngine-io/ansible-collection-cloudstack/pull/62). Major Changes @@ -392,7 +392,7 @@ kubernetes.core - k8s_* - Add support for vaulted kubeconfig and src (https://github.com/ansible-collections/kubernetes.core/pull/193). - k8s_auth - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_config_resource_name - Filter plugin migrated from Ansible 2.9 to Kubernetes collection. -- k8s_exec - New module for executing commands on pods via Kubernetes API (https://github.com/ansible-collections/kubernetes.core/pull/14). +- k8s_exec - New module for executing commands on pods through Kubernetes API (https://github.com/ansible-collections/kubernetes.core/pull/14). - k8s_exec - Return rc for the command executed (https://github.com/ansible-collections/kubernetes.core/pull/158). - k8s_info - Module migrated from Ansible 2.9 to Kubernetes collection. - k8s_log - New module for retrieving pod logs (https://github.com/ansible-collections/kubernetes.core/pull/16). @@ -409,7 +409,7 @@ netbox.netbox - nb_inventory - Move around ``extracted_primary_ip`` to allow for ``config_context`` or ``custom_field`` to overwrite. (#377) - nb_inventory - Services are now a list of integers due to NetBox 2.10 changes. (#396) - nb_lookup - Allow ID to be passed in and use ``.get`` instead of ``.filter``. (#376) -- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found via env. (#391) +- nb_lookup - Allow ``api_endpoint`` and ``token`` to be found through env. (#391) ovirt.ovirt ~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_4.rst b/docs/docsite/rst/porting_guides/porting_guide_4.rst index 003faba37f..4e91a30d63 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_4.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_4.rst @@ -194,7 +194,7 @@ Breaking Changes community.zabbix ~~~~~~~~~~~~~~~~ -- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_). +- all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_). Deprecated Features ------------------- @@ -464,7 +464,7 @@ fortinet.fortios netbox.netbox ~~~~~~~~~~~~~ -- packages is now a required Python package and gets installed via Ansible 2.10+. +- packages is now a required Python package and gets installed through Ansible 2.10+. Removed Features ---------------- diff --git a/docs/docsite/rst/porting_guides/porting_guide_5.rst b/docs/docsite/rst/porting_guides/porting_guide_5.rst index f26d7fb2a1..6257ccd1f2 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_5.rst @@ -114,7 +114,7 @@ Plugins * ``unique`` filter with Jinja2 < 2.10 is case-sensitive and now raise coherently an error if ``case_sensitive=False`` instead of when ``case_sensitive=True``. * Set theory filters (``intersect``, ``difference``, ``symmetric_difference`` and ``union``) are now case-sensitive. Explicitly use ``case_sensitive=False`` to keep previous behavior. Note: with Jinja2 < 2.10, the filters were already case-sensitive by default. -* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, e.g. ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. +* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, for example ``bcrypt_sha256``, now default to the "2b" format and if the "2a" format is required it must be specified. Porting custom scripts ====================== @@ -572,7 +572,7 @@ community.routeros community.zabbix ~~~~~~~~~~~~~~~~ -- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_). +- all roles now reference other roles and modules through their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_). kubernetes.core ~~~~~~~~~~~~~~~ @@ -784,7 +784,7 @@ netapp.cloudmanager netbox.netbox ~~~~~~~~~~~~~ -- packages is now a required Python package and gets installed via Ansible 2.10+. +- packages is now a required Python package and gets installed through Ansible 2.10+. openvswitch.openvswitch ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst b/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst index 5a1bdb0b7e..275de7250e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_base_2.10.rst @@ -36,8 +36,8 @@ Command Line ============ * The ``ansible-galaxy login`` command has been removed, as the underlying API it used for GitHub auth is being shut down. Publishing roles or - collections to Galaxy via ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI via a token file (default location - ``~/.ansible/galaxy_token``) or (insecurely) via the ``--token`` argument to ``ansible-galaxy``. + collections to Galaxy through ``ansible-galaxy`` now requires that a Galaxy API token be passed to the CLI through a token file (default location + ``~/.ansible/galaxy_token``) or (insecurely) through the ``--token`` argument to ``ansible-galaxy``. Deprecated @@ -73,7 +73,7 @@ Plugins Lookup plugin names case-sensitivity ------------------------------------ -* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked via ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. +* Prior to Ansible ``2.10`` lookup plugin names passed in as an argument to the ``lookup()`` function were treated as case-insensitive as opposed to lookups invoked through ``with_<lookup_name>``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. Noteworthy plugin changes ------------------------- diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst index 2d60bf26b0..4e33e84247 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.12.rst @@ -112,7 +112,7 @@ Plugins * ``unique`` filter with Jinja2 < 2.10 is case-sensitive and now raise coherently an error if ``case_sensitive=False`` instead of when ``case_sensitive=True``. * Set theory filters (``intersect``, ``difference``, ``symmetric_difference`` and ``union``) are now case-sensitive. Explicitly use ``case_sensitive=False`` to keep previous behavior. Note: with Jinja2 < 2.10, the filters were already case-sensitive by default. -* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, e.g. ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. +* ``password_hash``` now uses ``passlib`` defaults when an option is unspecified, for example ``bcrypt_sha256`` now default to the "2b" format and if the "2a" format is required it must be specified. Porting custom scripts ====================== diff --git a/docs/docsite/rst/scenario_guides/guide_alicloud.rst b/docs/docsite/rst/scenario_guides/guide_alicloud.rst index 0e0212e76a..fd78bf19cf 100644 --- a/docs/docsite/rst/scenario_guides/guide_alicloud.rst +++ b/docs/docsite/rst/scenario_guides/guide_alicloud.rst @@ -39,13 +39,17 @@ To pass authentication credentials as environment variables: export ALICLOUD_ACCESS_KEY='Alicloud123' export ALICLOUD_SECRET_KEY='AlicloudSecret123' -To store authentication credentials in a vars_file, encrypt them with :ref:`Ansible Vault<vault>` to keep them secure, then list them:: +To store authentication credentials in a vars_files, encrypt them with :ref:`Ansible Vault<vault>` to keep them secure, then list them: + +.. code-block:: yaml --- alicloud_access_key: "--REMOVED--" alicloud_secret_key: "--REMOVED--" -Note that if you store your credentials in a vars_file, you need to refer to them in each Alicloud module. For example:: +Note that if you store your credentials in a vars_files, you need to refer to them in each Alicloud module. For example: + +.. code-block:: yaml - ali_instance: alicloud_access_key: "{{alicloud_access_key}}" |