From 96aee766f4c2ae2fe769d408a010834ef95dff71 Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Wed, 2 Sep 2020 12:50:12 -0500 Subject: [PATCH] More docs updates to reflect collections ecosystem (#71597) --- docs/docsite/rst/user_guide/become.rst | 23 ++++++++++--------- docs/docsite/rst/user_guide/modules_intro.rst | 19 +++++---------- .../rst/user_guide/modules_support.rst | 4 ++-- .../user_guide/shared_snippets/with2loop.txt | 6 ++--- 4 files changed, 22 insertions(+), 30 deletions(-) diff --git a/docs/docsite/rst/user_guide/become.rst b/docs/docsite/rst/user_guide/become.rst index 9bf70894b71..4e30edd58fc 100644 --- a/docs/docsite/rst/user_guide/become.rst +++ b/docs/docsite/rst/user_guide/become.rst @@ -291,7 +291,7 @@ Become and network automation As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all Ansible-maintained network platforms that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary. -You must set the connection type to either ``connection: network_cli`` or ``connection: httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details. +You must set the connection type to either ``connection: ansible.netcommon.network_cli`` or ``connection: ansible.netcommon.httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` documentation for details. You can use escalated privileges on only the specific tasks that need them, on an entire play, or on all plays. Adding ``become: yes`` and ``become_method: enable`` instructs Ansible to enter ``enable`` mode before executing the task, play, or playbook where those parameters are set. @@ -306,7 +306,7 @@ To set ``enable`` mode for a specific task, add ``become`` at the task level: .. code-block:: yaml - name: Gather facts (eos) - eos_facts: + arista.eos.eos_facts: gather_subset: - "!hardware" become: yes @@ -321,7 +321,7 @@ To set enable mode for all tasks in a single play, add ``become`` at the play le become_method: enable tasks: - name: Gather facts (eos) - eos_facts: + arista.eos.eos_facts: gather_subset: - "!hardware" @@ -334,8 +334,8 @@ Often you wish for all tasks in all plays to run using privilege mode, that is b .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: eos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: arista.eos.eos ansible_user: myuser ansible_become: yes ansible_become_method: enable @@ -407,7 +407,8 @@ task: .. code-block:: yaml - - win_whoami: + - Check my user name + ansible.windows.win_whoami: become: yes The output will look something similar to the below: @@ -534,7 +535,7 @@ If running on a version of Ansible that is older than 2.5 or the normal .. code-block:: yaml - name: grant the ansible user the SeTcbPrivilege right - win_user_right: + ansible.windows.win_user_right: name: SeTcbPrivilege users: '{{ansible_user}}' action: add @@ -632,7 +633,7 @@ or with this Ansible task: .. code-block:: yaml - name: allow blank password on become - win_regedit: + ansible.windows.win_regedit: path: HKLM:\SYSTEM\CurrentControlSet\Control\Lsa name: LimitBlankPasswordUse data: 0 @@ -707,7 +708,7 @@ Here are some examples of how to use ``become_flags`` with Windows tasks: .. code-block:: yaml - name: copy a file from a fileshare with custom credentials - win_copy: + ansible.windows.win_copy: src: \\server\share\data\file.txt dest: C:\temp\file.txt remote_src: yes @@ -719,12 +720,12 @@ Here are some examples of how to use ``become_flags`` with Windows tasks: ansible_become_flags: logon_type=new_credentials logon_flags=netcredentials_only - name: run a command under a batch logon - win_whoami: + ansible.windows.win_whoami: become: yes become_flags: logon_type=batch - name: run a command and not load the user profile - win_whomai: + ansible.windows.win_whomai: become: yes become_flags: logon_flags= diff --git a/docs/docsite/rst/user_guide/modules_intro.rst b/docs/docsite/rst/user_guide/modules_intro.rst index 482b49aca3d..bb6d2cd7102 100644 --- a/docs/docsite/rst/user_guide/modules_intro.rst +++ b/docs/docsite/rst/user_guide/modules_intro.rst @@ -3,7 +3,7 @@ Introduction to modules ======================= -Modules (also referred to as "task plugins" or "library plugins") are discrete units of code that can be used from the command line or in a playbook task. Ansible executes each module, usually on the remote target node, and collects return values. +Modules (also referred to as "task plugins" or "library plugins") are discrete units of code that can be used from the command line or in a playbook task. Ansible executes each module, usually on the remote managed node, and collects return values. In Ansible 2.10 and later, most modules are hosted in collections. You can execute modules from the command line:: @@ -11,34 +11,27 @@ You can execute modules from the command line:: ansible webservers -m ping ansible webservers -m command -a "/sbin/reboot -t now" -Each module supports taking arguments. Nearly all modules take ``key=value`` -arguments, space delimited. Some modules take no arguments, and the command/shell modules simply -take the string of the command you want to run. +Each module supports taking arguments. Nearly all modules take ``key=value`` arguments, space delimited. Some modules take no arguments, and the command/shell modules simply take the string of the command you want to run. From playbooks, Ansible modules are executed in a very similar way:: - - name: reboot the servers - action: command /sbin/reboot -t now - -Which can be abbreviated to:: - - name: reboot the servers command: /sbin/reboot -t now -Another way to pass arguments to a module is using YAML syntax also called 'complex args' :: +Another way to pass arguments to a module is using YAML syntax, also called 'complex args' :: - name: restart webserver service: name: httpd state: restarted -All modules return JSON format data. This means modules can be written in any programming language. Modules should be idempotent, and should avoid making any changes if they detect that the current state matches the desired final state. When used in an Ansible playbook, modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks. +All modules return JSON format data. This means modules can be written in any programming language. Modules should be idempotent, and should avoid making any changes if they detect that the current state matches the desired final state. When used in an Ansible playbook, modules can trigger 'change events' in the form of notifying :ref:`handlers ` to run additional tasks. -Documentation for each module can be accessed from the command line with the ansible-doc tool:: +You can access the documentation for each module from the command line with the ansible-doc tool:: ansible-doc yum -For a list of all available modules, see the :ref:`Module Docs `, or run the following at a command prompt:: +For a list of all available modules, see the :ref:`Collection docs `, or run the following at a command prompt:: ansible-doc -l diff --git a/docs/docsite/rst/user_guide/modules_support.rst b/docs/docsite/rst/user_guide/modules_support.rst index f21d0c25bf7..6faa7333d24 100644 --- a/docs/docsite/rst/user_guide/modules_support.rst +++ b/docs/docsite/rst/user_guide/modules_support.rst @@ -32,7 +32,7 @@ Maintenance Issue Reporting =============== -If you find a bug that affects a plugin in the main Ansible repo: +If you find a bug that affects a plugin in the main Ansible repo, also known as ``ansible-base``: #. Confirm that you are running the latest stable version of Ansible or the devel branch. #. Look at the `issue tracker in the Ansible repo `_ to see if an issue has already been filed. @@ -56,7 +56,7 @@ If you find a bug that affects a module in an Automation Hub collection: Support ======= -All plugins that remain in ansible-base and all collections hosted in Automation Hub are supported by Red Hat. No other plugins or collections are supported by Red Hat. If you have a subscription to the Red Hat Ansible Automation Platform, you can find more information and resources on the `Red Hat Customer Portal. `_ +All plugins that remain in ``ansible-base`` and all collections hosted in Automation Hub are supported by Red Hat. No other plugins or collections are supported by Red Hat. If you have a subscription to the Red Hat Ansible Automation Platform, you can find more information and resources on the `Red Hat Customer Portal. `_ .. seealso:: diff --git a/docs/docsite/rst/user_guide/shared_snippets/with2loop.txt b/docs/docsite/rst/user_guide/shared_snippets/with2loop.txt index c1aae7daefe..266adff88da 100644 --- a/docs/docsite/rst/user_guide/shared_snippets/with2loop.txt +++ b/docs/docsite/rst/user_guide/shared_snippets/with2loop.txt @@ -1,8 +1,6 @@ -With the release of Ansible 2.5, the recommended way to perform loops is the use the new ``loop`` keyword instead of ``with_X`` style loops. +In most cases, loops work best with the ``loop`` keyword instead of ``with_X`` style loops. The ``loop`` syntax is usually best expressed using filters instead of more complex use of ``query`` or ``lookup``. -In many cases, ``loop`` syntax is better expressed using filters instead of more complex use of ``query`` or ``lookup``. - -The following examples will show how to convert many common ``with_`` style loops to ``loop`` and filters. +These examples show how to convert many common ``with_`` style loops to ``loop`` and filters. with_list ---------