Fix places in docs that refer to modules without namespace

We've namespaced all plugin docs.  Change the docs to reflect that
This commit is contained in:
Toshio Kuratomi 2018-04-18 08:29:28 -07:00
parent f9d83944ec
commit 9faf7b949e
11 changed files with 60 additions and 58 deletions

View file

@ -33,11 +33,11 @@ a playbook satisfy certain criteria.)
More often, Action Plugins set up some values on the controller, then invoke an
actual module on the managed node that does something with these values. An
easy to understand version of this is the :ref:`template Action Plugin
<template>`. The :ref:`template Action Plugin <template>` takes values from
<template_module>`. The :ref:`template Action Plugin <template_module>` takes values from
the user to construct a file in a temporary location on the controller using
variables from the playbook environment. It then transfers the temporary file
to a temporary file on the remote system. After that, it invokes the
:ref:`copy module <copy>` which operates on the remote system to move the file
:ref:`copy module <copy_module>` which operates on the remote system to move the file
into its final location, sets file permissions, and so on.
.. _flow_new_style_modules:

View file

@ -173,9 +173,9 @@ Collect data
Ansible facts modules gather system information 'facts' that are available to the rest of your playbook.
Ansible Networking ships with a number of network-specific facts modules. In this example, we use the ``_facts`` modules :ref:`eos_facts <eos_facts>`, :ref:`ios_facts <ios_facts>` and :ref:`vyos_facts <vyos_facts>` to connect to the remote networking device. As the credentials are not explicitly passed via module arguments, Ansible uses the username and password from the inventory file.
Ansible Networking ships with a number of network-specific facts modules. In this example, we use the ``_facts`` modules :ref:`eos_facts <eos_facts_module>`, :ref:`ios_facts <ios_facts_module>` and :ref:`vyos_facts <vyos_facts_module>` to connect to the remote networking device. As the credentials are not explicitly passed via module arguments, Ansible uses the username and password from the inventory file.
Ansible's "Network Fact modules" gather information from the system and store the results in facts prefixed with ``ansible_net_``. The data collected by these modules is documented in the `Return Values` section of the module docs, in this case :ref:`eos_facts <eos_facts>` and :ref:`vyos_facts <vyos_facts>`. We can use the facts, such as ``ansible_net_version`` late on in the "Display some facts" task.
Ansible's "Network Fact modules" gather information from the system and store the results in facts prefixed with ``ansible_net_``. The data collected by these modules is documented in the `Return Values` section of the module docs, in this case :ref:`eos_facts <eos_facts_module>` and :ref:`vyos_facts <vyos_facts_module>`. We can use the facts, such as ``ansible_net_version`` late on in the "Display some facts" task.
To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the group defined in the inventory file, for more information on the use of conditionals in Ansible Playbooks see :ref:`the_when_statement`.
@ -357,7 +357,7 @@ For more information, see :ref:`magic_variables_and_hostvars`.
Get running configuration
-------------------------
The :ref:`eos_config <eos_config>` and :ref:`vyos_config <vyos_config>` modules have a ``backup:`` option that when set will cause the module to create a full backup of the current ``running-config`` from the remote device before any changes are made. The backup file is written to the ``backup`` folder in the playbook root directory. If the directory does not exist, it is created.
The :ref:`eos_config <eos_config_module>` and :ref:`vyos_config <vyos_config_module>` modules have a ``backup:`` option that when set will cause the module to create a full backup of the current ``running-config`` from the remote device before any changes are made. The backup file is written to the ``backup`` folder in the playbook root directory. If the directory does not exist, it is created.
To demonstrate how we can move the backup file to a different location, we register the result and move the file to the path stored in ``backup_path``.

View file

@ -86,7 +86,7 @@ Before you can use eAPI to connect to a switch, you must enable eAPI. To enable
become_method: enable
when: ansible_network_os == 'eos'
You can find more options for enabling HTTP/HTTPS and local http in the :ref:`eos_eapi <eos_eapi>` module documentation.
You can find more options for enabling HTTP/HTTPS and local http in the :ref:`eos_eapi <eos_eapi_module>` module documentation.
Once eAPI is enabled, change your ``group_vars/eos.yml`` to use the eAPI connection.

View file

@ -80,7 +80,7 @@ Before you can use NX-API to connect to a switch, you must enable NX-API. To ena
enable_https: yes
when: ansible_network_os == 'nxos'
To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos_nxapi <nxos_nxapi>` module documentation.
To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos_nxapi <nxos_nxapi_module>` module documentation.
Once NX-API is enabled, change your ``group_vars/nxos.yml`` to use the NX-API connection.

View file

@ -118,15 +118,15 @@ Deprecation notices
The following modules will be removed in Ansible 2.5. Please update your playbooks accordingly.
* :ref:`ec2_vpc <ec2_vpc>`
* :ref:`cl_bond <cl_bond>`
* :ref:`cl_bridge <cl_bridge>`
* :ref:`cl_img_install <cl_img_install>`
* :ref:`cl_interface <cl_interface>`
* :ref:`cl_interface_policy <cl_interface_policy>`
* :ref:`cl_license <cl_license>`
* :ref:`cl_ports <cl_ports>`
* :ref:`nxos_mtu <nxos_mtu>` use :ref:`nxos_system <nxos_system>` instead
* :ref:`ec2_vpc <ec2_vpc_module>`
* :ref:`cl_bond <cl_bond_module>`
* :ref:`cl_bridge <cl_bridge_module>`
* :ref:`cl_img_install <cl_img_install_module>`
* :ref:`cl_interface <cl_interface_module>`
* :ref:`cl_interface_policy <cl_interface_policy_module>`
* :ref:`cl_license <cl_license_module>`
* :ref:`cl_ports <cl_ports_module>`
* :ref:`nxos_mtu <nxos_mtu_module>` use :ref:`nxos_system <nxos_system_module>` instead
Noteworthy module changes
-------------------------

View file

@ -77,7 +77,7 @@ Modules
Major changes in popular modules are detailed here
* The :ref:`win_shell <win_shell>` and :ref:`win_command <win_command>` modules now properly preserve quoted arguments in the command-line. Tasks that attempted to work around the issue by adding extra quotes/escaping may need to be reworked to remove the superfluous escaping. See `Issue 23019 <https://github.com/ansible/ansible/issues/23019>`_ for additional detail.
* The :ref:`win_shell <win_shell_module>` and :ref:`win_command <win_command_module>` modules now properly preserve quoted arguments in the command-line. Tasks that attempted to work around the issue by adding extra quotes/escaping may need to be reworked to remove the superfluous escaping. See `Issue 23019 <https://github.com/ansible/ansible/issues/23019>`_ for additional detail.
Modules removed
---------------
@ -91,15 +91,15 @@ Deprecation notices
The following modules will be removed in Ansible 2.8. Please update your playbooks accordingly.
* :ref:`azure <azure>`, use :ref:`azure_rm_virtualmachine <azure_rm_virtualmachine>`, which uses the new Resource Manager SDK.
* :ref:`win_msi <win_msi>`, use :ref:`win_package <win_package>` instead
* :ref:`azure <azure_module>`, use :ref:`azure_rm_virtualmachine <azure_rm_virtualmachine_module>`, which uses the new Resource Manager SDK.
* :ref:`win_msi <win_msi_module>`, use :ref:`win_package <win_package_module>` instead
Noteworthy module changes
-------------------------
* The :ref:`win_get_url <win_get_url>` module has the dictionary ``win_get_url`` in its results deprecated, its content is now also available directly in the resulting output, like other modules. This dictionary will be removed in Ansible 2.8.
* The :ref:`win_unzip <win_unzip>` module no longer includes the dictionary ``win_unzip`` in its results; the contents are now included directly in the resulting output, like other modules.
* The :ref:`win_package <win_package>` module return values ``exit_code`` and ``restart_required`` have been deprecated in favour of ``rc`` and ``reboot_required`` respectively. The deprecated return values will be removed in Ansible 2.6.
* The :ref:`win_get_url <win_get_url_module>` module has the dictionary ``win_get_url`` in its results deprecated, its content is now also available directly in the resulting output, like other modules. This dictionary will be removed in Ansible 2.8.
* The :ref:`win_unzip <win_unzip_module>` module no longer includes the dictionary ``win_unzip`` in its results; the contents are now included directly in the resulting output, like other modules.
* The :ref:`win_package <win_package_module>` module return values ``exit_code`` and ``restart_required`` have been deprecated in favour of ``rc`` and ``reboot_required`` respectively. The deprecated return values will be removed in Ansible 2.6.
Plugins

View file

@ -132,17 +132,17 @@ Modules removed
The following modules no longer exist:
* :ref:`nxos_mtu <nxos_mtu>` use :ref:`nxos_system <nxos_system>`'s ``system_mtu`` option or :ref:`nxos_interface <nxos_interface>` instead
* :ref:`cl_interface_policy <cl_interface_policy>` use :ref:`nclu <nclu>` instead
* :ref:`cl_bridge <cl_bridge>` use :ref:`nclu <nclu>` instead
* :ref:`cl_img_install <cl_img_install>` use :ref:`nclu <nclu>` instead
* :ref:`cl_ports <cl_ports>` use :ref:`nclu <nclu>` instead
* :ref:`cl_license <cl_license>` use :ref:`nclu <nclu>` instead
* :ref:`cl_interface <cl_interface>` use :ref:`nclu <nclu>` instead
* :ref:`cl_bond <cl_bond>` use :ref:`nclu <nclu>` instead
* :ref:`ec2_vpc <ec2_vpc>` use :ref:`ec2_vpc_net <ec2_vpc_net>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl>` instead.
* :ref:`ec2_ami_search <ec2_ami_search>` use :ref:`ec2_ami_facts <ec2_ami_facts>` instead
* :ref:`docker <docker>` use :ref:`docker_container <docker_container>` and :ref:`docker_image <docker_image>` instead
* :ref:`nxos_mtu <nxos_mtu_module>` use :ref:`nxos_system <nxos_system_module>`'s ``system_mtu`` option or :ref:`nxos_interface <nxos_interface_module>` instead
* :ref:`cl_interface_policy <cl_interface_policy_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_bridge <cl_bridge_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_img_install <cl_img_install_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_ports <cl_ports_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_license <cl_license_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_interface <cl_interface_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_bond <cl_bond_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
* :ref:`ec2_ami_search <ec2_ami_search_module>` use :ref:`ec2_ami_facts <ec2_ami_facts_module>` instead
* :ref:`docker <docker_module>` use :ref:`docker_container <docker_container_module>` and :ref:`docker_image <docker_image_module>` instead
Deprecation notices
-------------------
@ -150,23 +150,23 @@ Deprecation notices
The following modules will be removed in Ansible 2.9. Please update your playbooks accordingly.
* Apstra's ``aos_*`` modules are deprecated as they do not work with AOS 2.1 or higher. See new modules at `https://github.com/apstra <https://github.com/apstra>`_.
* :ref:`nxos_ip_interface <nxos_ip_interface>` use :ref:`nxos_l3_interface <nxos_l3_interface>` instead.
* :ref:`nxos_portchannel <nxos_portchannel>` use :ref:`nxos_linkagg <nxos_linkagg>` instead.
* :ref:`nxos_switchport <nxos_switchport>` use :ref:`nxos_l2_interface <nxos_l2_interface>` instead.
* :ref:`panos_security_policy <panos_security_policy>` use :ref:`panos_security_rule <panos_security_rule>` instead.
* :ref:`panos_nat_policy <panos_nat_policy>` use :ref:`panos_nat_rule <panos_nat_rule>` instead.
* :ref:`vsphere_guest <vsphere_guest>` use :ref:`vmware_guest <vmware_guest>` instead.
* :ref:`nxos_ip_interface <nxos_ip_interface_module>` use :ref:`nxos_l3_interface <nxos_l3_interface_module>` instead.
* :ref:`nxos_portchannel <nxos_portchannel_module>` use :ref:`nxos_linkagg <nxos_linkagg_module>` instead.
* :ref:`nxos_switchport <nxos_switchport_module>` use :ref:`nxos_l2_interface <nxos_l2_interface_module>` instead.
* :ref:`panos_security_policy <panos_security_policy_module>` use :ref:`panos_security_rule <panos_security_rule_module>` instead.
* :ref:`panos_nat_policy <panos_nat_policy_module>` use :ref:`panos_nat_rule <panos_nat_rule_module>` instead.
* :ref:`vsphere_guest <vsphere_guest_module>` use :ref:`vmware_guest <vmware_guest_module>` instead.
Noteworthy module changes
-------------------------
* The :ref:`stat <stat>` and :ref:`win_stat <win_stat>` modules have changed the default of the option ``get_md5`` from ``true`` to ``false``.
* The :ref:`stat <stat_module>` and :ref:`win_stat <win_stat_module>` modules have changed the default of the option ``get_md5`` from ``true`` to ``false``.
This option will be removed starting with Ansible version 2.9. The options ``get_checksum: True``
and ``checksum_algorithm: md5`` can still be used if an MD5 checksum is
desired.
* ``osx_say`` module was renamed into :ref:`say <say>`.
* ``osx_say`` module was renamed into :ref:`say <say_module>`.
Plugins
=======

View file

@ -96,7 +96,7 @@ when a term comes up on the mailing list.
they can be used in :term:`playbooks` and templates just like
variables, facts are things that are inferred, rather than set. Facts
are automatically discovered by Ansible when running plays by
executing the internal :ref:`setup module <setup>` on the remote nodes. You
executing the internal :ref:`setup module <setup_module>` on the remote nodes. You
never have to call the setup module explicitly, it just runs, but it
can be disabled to save time if it is not needed or you can tell
ansible to collect only a subset of the full facts via the
@ -267,7 +267,7 @@ when a term comes up on the mailing list.
Generally, Ansible is not a programming language. It prefers to be
more declarative, though various constructs like ``loop`` allow
a particular task to be repeated for multiple items in a list.
Certain modules, like :ref:`yum <yum>` and :ref:`apt <apt>`, actually take
Certain modules, like :ref:`yum <yum_module>` and :ref:`apt <apt_module>`, actually take
lists directly, and can install all packages given in those lists
within a single transaction, dramatically speeding up total time to
configuration, so they can be used without loops.
@ -368,7 +368,7 @@ when a term comes up on the mailing list.
Resource Model
Ansible modules work in terms of resources. For instance, the
:ref:`file module <file>` will select a particular file and ensure
:ref:`file module <file_module>` will select a particular file and ensure
that the attributes of that resource match a particular model. As an
example, we might wish to change the owner of :file:`/etc/motd` to
``root`` if it is not already set to ``root``, or set its mode to
@ -412,8 +412,8 @@ when a term comes up on the mailing list.
perform many operations wrapped in a sudo command, and can work with
both password-less and password-based sudo. Some operations that
don't normally work with sudo (like scp file transfer) can be achieved
with Ansible's :ref:`copy <copy>`, :ref:`template <template>`, and
:ref:`fetch <fetch>` modules while running in sudo mode.
with Ansible's :ref:`copy <copy_module>`, :ref:`template <template_module>`, and
:ref:`fetch <fetch_module>` modules while running in sudo mode.
SSH (Native)
Native OpenSSH as an Ansible transport is specified with ``-c ssh``

View file

@ -51,7 +51,7 @@ Using the ACI modules
---------------------
The Ansible ACI modules provide a user-friendly interface to managing your ACI environment using Ansible playbooks.
For instance ensuring that a specific tenant exists, is done using the following Ansible task using module `aci_tenant <aci_tenant>`:
For instance ensuring that a specific tenant exists, is done using the following Ansible task using module `aci_tenant <aci_tenant_module>`:
.. code-block:: yaml
@ -96,7 +96,7 @@ Or query all objects.
state: query
register: all_tenants
After registering the return values of the `aci_tenant <aci_tenant>` task as shown above, you can access all tenant information from variable ``all_tenants``.
After registering the return values of the `aci_tenant <aci_tenant_module>` task as shown above, you can access all tenant information from variable ``all_tenants``.
Common parameters
@ -290,17 +290,17 @@ Using ACI REST with Ansible
---------------------------
While already a lot of ACI modules exists in the Ansible distribution, and the most common actions can be performed with these existing modules, there's always something that may not be possible with off-the-shelf modules.
The :ref:`aci_rest <aci_rest>` module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly.
The :ref:`aci_rest <aci_rest_module>` module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly.
Built-in idempotency
....................
Because the APIC REST API is intrinsically idempotent and can report whether a change was made, the :ref:`aci_rest <aci_rest>` module automatically inherits both capabilities and is a first-class solution for automating your ACI infrastructure. As a result, users that require more powerful low-level access to their ACI infrastructure don't have to give up on idempotency and don't have to guess whether a change was performed when using the :ref:`aci_rest <aci_rest>` module.
Because the APIC REST API is intrinsically idempotent and can report whether a change was made, the :ref:`aci_rest <aci_rest_module>` module automatically inherits both capabilities and is a first-class solution for automating your ACI infrastructure. As a result, users that require more powerful low-level access to their ACI infrastructure don't have to give up on idempotency and don't have to guess whether a change was performed when using the :ref:`aci_rest <aci_rest_module>` module.
Using the aci_rest module
.........................
The :ref:`aci_rest <aci_rest>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require the path to end with ``.json``.
The :ref:`aci_rest <aci_rest_module>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require the path to end with ``.json``.
When you're making modifications, you can use the POST or DELETE methods, whereas doing just queries require the GET method.
@ -375,7 +375,7 @@ More information
................
Plenty of resources exist to learn about ACI's APIC REST interface, we recommend the links below:
- :ref:`The aci_rest module documentation <aci_rest>`
- :ref:`The aci_rest module documentation <aci_rest_module>`
- `APIC REST API Configuration Guide <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/rest_cfg/2_1_x/b_Cisco_APIC_REST_API_Configuration_Guide.html>`_ -- Detailed guide on how the APIC REST API is designed and used, incl. many examples
- `APIC Management Information Model reference <https://developer.cisco.com/docs/apic-mim-ref/>`_ -- Complete reference of the APIC object model
- `Cisco DevNet Learning Labs about ACI and REST <https://learninglabs.cisco.com/labs/tags/ACI,REST>`_
@ -439,7 +439,7 @@ APIC error messages
The following error messages may occur and this section can help you understand what exactly is going on and how to fix/avoid them.
APIC Error 122: unknown managed object class 'polUni'
In case you receive this error while you are certain your :ref:`aci_rest <aci_rest>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
In case you receive this error while you are certain your :ref:`aci_rest <aci_rest_module>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag
@ -454,7 +454,7 @@ The following error messages may occur and this section can help you understand
Known issues
------------
The :ref:`aci_rest <aci_rest>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of this module.
The :ref:`aci_rest <aci_rest_module>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of this module.
All below issues either have been reported to the vendor, and most can simply be avoided.

View file

@ -150,8 +150,8 @@ Ways to resolve this include:
* Use `pipelining`. When pipelining is enabled, Ansible doesn't save the
module to a temporary file on the client. Instead it pipes the module to
the remote python interpreter's stdin. Pipelining does not work for
python modules involving file transfer (for example: :ref:`copy <copy>`,
:ref:`fetch <fetch>`, :ref:`template <template>`), or for non-python modules.
python modules involving file transfer (for example: :ref:`copy <copy_module>`,
:ref:`fetch <fetch_module>`, :ref:`template <template_module>`), or for non-python modules.
* (Available in Ansible 2.1) Install POSIX.1e filesystem acl support on the
managed host. If the temporary directory on the remote host is mounted with

View file

@ -19,8 +19,10 @@ Ansible Vault can encrypt any structured data file used by Ansible. This can in
Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety.
Ansible Vault can also encrypt arbitrary files, even binary files. If a vault-encrypted file is
given as the ``src`` argument to the :ref:`copy <copy>`, :ref:`template <template>`,
:ref:`unarchive <unarchive>`, :ref:`script <script>` or :ref:`assemble <assemble>` modules, the file will be placed at the destination on the target host decrypted (assuming a valid vault password is supplied when running the play).
given as the ``src`` argument to the :ref:`copy <copy_module>`, :ref:`template <template_module>`,
:ref:`unarchive <unarchive_module>`, :ref:`script <script_module>` or :ref:`assemble
<assemble_module>` modules, the file will be placed at the destination on the target host decrypted
(assuming a valid vault password is supplied when running the play).
As of version 2.3, Ansible supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more details below.