diff --git a/docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html b/docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html index ada446b42f743f..16342c1712ca0b 100644 --- a/docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html +++ b/docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html @@ -44,10 +44,14 @@ {{ _('Edit on GitHub') }} {% else %} - {% if pagename.endswith('_module') %} - {{ _('Edit on GitHub') }} - {% elif pagename.startswith('plugins') and meta.get('source', None) %} - {{ _('Edit on GitHub') }} + {% if (pagename.endswith('_module')) or (pagename.endswith('_become')) + or (pagename.endswith('_cache')) or (pagename.endswith('_callback')) + or (pagename.endswith('_connection')) or (pagename.endswith('_inventory')) + or (pagename.endswith('_lookup')) or (pagename.endswith('_shell')) + or (pagename.endswith('_strategy')) or (pagename.endswith('_vars')) + %} + +
{% elif pagename.startswith('cli') and meta.get('source', None) %} {{ _('Edit on GitHub') }} {% elif (not 'list_of' in pagename) and (not 'category' in pagename) %} diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 55e861f999090d..11344ea712c43f 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -43,7 +43,7 @@ Here's an overview of the PR lifecycle: Automated PR review: ansibullbot -------------------------------- -Because Ansible receives many pull requests, and because we love automating things, we've automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short. +Because Ansible receives many pull requests, and because we love automating things, we have automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short. `Ansibullbot `_ serves many functions: @@ -139,11 +139,7 @@ We don't merge every PR. Here are some tips for making your PR useful, attractiv Changelogs ---------- -Changelogs help users and developers keep up with changes to Ansible. -Ansible builds a changelog for each release from fragments. -You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base. -You don't have to add a changelog fragment for PRs that add new -modules and plugins, because our tooling does that for you automatically. +Changelogs help users and developers keep up with changes to Ansible. Ansible builds a changelog for each release from fragments. You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-base. You do not have to add a changelog fragment for PRs that add new modules and plugins, because our tooling does that for you automatically. We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR. @@ -152,35 +148,29 @@ We build short summary changelogs for minor releases as well as for major releas Creating a changelog fragment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A basic changelog fragment is a ``.yaml`` file placed in the -``changelogs/fragments/`` directory. Each file contains a yaml dict with -keys like ``bugfixes`` or ``major_changes`` followed by a list of -changelog entries of bugfixes or features. Each changelog entry is -rst embedded inside of the yaml file which means that certain -constructs would need to be escaped so they can be interpreted by rst -and not by yaml (or escaped for both yaml and rst if that's your -desire). Each PR **must** use a new fragment file rather than adding to -an existing one, so we can trace the change back to the PR that introduced it. +A basic changelog fragment is a ``.yaml`` file placed in the ``changelogs/fragments/`` directory. Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features. Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it. -To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of corresponding repository. -The file name should include the PR number and a description of the change. -It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml`` +To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml`` -A single changelog fragment may contain multiple sections but most will only contain one section. -The toplevel keys (bugfixes, major_changes, and so on) are defined in the -`config file `_ for our release note tool. Here are the valid sections and a description of each: +A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file `_ for our `release note tool `_. Here are the valid sections and a description of each: + +**breaking_changes** + Changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Displayed in both the changelogs and the :ref:`Porting Guides `. **major_changes** - Major changes to Ansible itself. Generally does not include module or plugin changes. + Major changes to Ansible itself. Generally does not include module or plugin changes. Displayed in both the changelogs and the :ref:`Porting Guides `. **minor_changes** Minor changes to Ansible, modules, or plugins. This includes new features, new parameters added to modules, or behavior changes to existing parameters. **deprecated_features** - Features that have been deprecated and are scheduled for removal in a future release. + Features that have been deprecated and are scheduled for removal in a future release. Displayed in both the changelogs and the :ref:`Porting Guides `. **removed_features** - Features that were previously deprecated and are now removed. + Features that were previously deprecated and are now removed. Displayed in both the changelogs and the :ref:`Porting Guides `. + +**security_fixes** + Fixes that address CVEs or resolve security concerns. Include links to CVE information. **bugfixes** Fixes that resolve issues. @@ -188,8 +178,7 @@ The toplevel keys (bugfixes, major_changes, and so on) are defined in the **known_issues** Known issues that are currently not fixed or will not be fixed. -Each changelog entry must contain a link to its issue between parentheses at the end. -If there is no corresponding issue, the entry must contain a link to the PR itself. +Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself. Most changelog entries will be ``bugfixes`` or ``minor_changes``. When writing a changelog entry that pertains to a particular module, start the entry with ``- [module name] -`` and the following sentence with a lowercase letter. @@ -222,9 +211,7 @@ Once you've written the changelog fragment for your PR, commit the file and incl Backporting merged PRs ====================== -All Ansible PRs must be merged to the ``devel`` branch first. -After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a -pull request to backport the change to a previous stable branch. +All Ansible PRs must be merged to the ``devel`` branch first. After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a pull request to backport the change to a previous stable branch. We do **not** backport features. diff --git a/docs/docsite/rst/dev_guide/developing_api.rst b/docs/docsite/rst/dev_guide/developing_api.rst index c7505a747b7f23..eeff46845b2150 100644 --- a/docs/docsite/rst/dev_guide/developing_api.rst +++ b/docs/docsite/rst/dev_guide/developing_api.rst @@ -6,7 +6,7 @@ Python API .. contents:: Topics -.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. +.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner `_ first. There are several ways to use Ansible from an API perspective. You can use the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index d9e77a373c7caa..1854afa430162d 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -25,6 +25,8 @@ Collections follow a simple data structure. None of the directories are required collection/ ├── docs/ ├── galaxy.yml + ├── meta/ + │ └── runtime.yml ├── plugins/ │ ├── modules/ │ │ └── module1.py @@ -194,6 +196,64 @@ command completion, or environment variables are presented throughout the Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. +.. _meta_runtime_yml: + +meta directory +-------------- + +A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys: + +- *requires_ansible*: + + The version of Ansible required to use the collection. Multiple versions can be separated with a comma. + + .. code:: yaml + + requires_ansible: ">=2.10,<2.11" + + .. note:: although the version is a `PEP440 Version Specifier `_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``. + +- *plugin_routing*: + + Content in a collection that Ansible needs to load from another location or that has been deprecated/removed. + The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys. + To define a new location for a plugin, set the ``redirect`` field to another name. + To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal date or version. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal date or version. + + .. code:: yaml + + plugin_routing: + inventory: + kubevirt: + redirect: community.general.kubevirt + my_inventory: + tombstone: + removal_version: "2.0.0" + warning_text: my_inventory has been removed. Please use other_inventory instead. + modules: + my_module: + deprecation: + removal_date: "2021-11-30" + warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead. + redirect: another.collection.new_module + podman_image: + redirect: containers.podman.podman_image + module_utils: + ec2: + redirect: amazon.aws.ec2 + util_dir.subdir.my_util: + redirect: namespace.name.my_util + +- *import_redirection* + + A mapping of names for Python import statements and their redirected locations. + + .. code:: yaml + + import_redirection: + ansible.module_utils.old_utility: + redirect: ansible_collections.collection_name.plugins.module_utils.new_location + .. _creating_collections_skeleton: @@ -469,16 +529,63 @@ Collection versions use `Semantic Versioning `_ for version .. _migrate_to_collection: -Migrating Ansible content to a collection -========================================= +Migrating Ansible content to a different collection +==================================================== + +To migrate content from one collection to another, you need to create three PRs as follows: + +#. Create a PR against the old collection to remove the content. +#. Create a PR against the new collection to add the files removed in step 1. +#. Update the ``ansible/ansible:devel`` branch entries for all files moved. + + +Removing the content from the old collection +---------------------------------------------- + +Create a PR against the old collection repo to remove the modules, module_utils, plugins, and docs_fragments related to this migration: + +#. If you are removing an action plugin, remove the corresponding module that contains the documentation. +#. If you are removing a module, remove any corresponding action plugin that should stay with it. +#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo. +#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt`` +#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``. +#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``. +#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries. +#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name. +#. If possible, do not yet add deprecation warnings to the new ``meta/runtime.yml`` entries, but only for a later major release. So the order should be: + 1. Remove content, add redirects in 3.0.0; + 2. Deprecate redirects in 4.0.0; + 3. Set removal version to 5.0.0 or later. -You can experiment with migrating existing modules into a collection using the `content_collector tool `_. The ``content_collector`` is a playbook that helps you migrate content from an Ansible distribution into a collection. .. warning:: - This tool is in active development and is provided only for experimentation and feedback at this point. + Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning: + + #. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage. + #. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.). + + +Adding the content to the new collection +----------------------------------------- + +Create a PR in the new collection to: + +#. Add ALL the files removed in first PR (from the old collection). +#. If it is an action plugin, include the corresponding module with documentation. +#. If it is a module, check if it has a corresponding action plugin that should move with it. +#. Check ``meta/ `` for relevant updates to ``action_groups.yml`` and ``runtime.yml`` if they exist. +#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN. +#. Review ``tests/sanity/ignore-\*.txt`` entries. +#. Update ``meta/runtime.yml``. + +Updating ``ansible/ansible:devel`` branch entries for all files moved +---------------------------------------------------------------------- + +Create a third PR on ``ansible/ansible`` repository to: -See the `content_collector README `_ for full details and usage guidelines. +#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry). +#. Update ``.github/BOTMETA.yml`` (the migrated_to entry) BOTMETA.yml ----------- @@ -486,7 +593,6 @@ BOTMETA.yml The `BOTMETA.yml `_ in the ansible/ansible GitHub repository is the source of truth for: * ansibullbot -* the docs build for collections-based modules Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build process for docs.ansible.com will know where to find the module docs. diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 9f0ff088970901..a315ebec6f839e 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -232,6 +232,10 @@ The preferred way to install Ansible on a Mac is with ``pip``. The instructions can be found in :ref:`from_pip`. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely. It should be noted that pip must be run as a module on macOS, and the linked ``pip`` instructions will show you how to do that. +.. note:: + + If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it. + If you are installing on macOS Mavericks (10.9), you may encounter some noise from your compiler. A workaround is to do the following:: $ CFLAGS=-Qunused-arguments CPPFLAGS=-Qunused-arguments pip install --user ansible @@ -301,6 +305,10 @@ Ansible can be installed with ``pip``, the Python package manager. If ``pip`` is $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py $ python get-pip.py --user +.. note:: + + If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it. + Then install Ansible [1]_:: $ python -m pip install --user ansible @@ -324,6 +332,33 @@ If you wish to install Ansible globally, run the following commands:: Please make sure you have the latest version of ``pip`` before installing Ansible. If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions `_ . +Upgrading Ansible from version 2.9 and older to version 2.10 or later +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Starting in version 2.10, Ansible is made of two packages. You need to first uninstall the old Ansible version (2.9 or earlier) before upgrading. +If you do not uninstall the older version of Ansible, you will see the following message, and no change will be performed: + +.. code-block:: console + + Cannot install ansible-base with a pre-existing ansible==2.x installation. + + Installing ansible-base with ansible-2.9 or older currently installed with + pip is known to cause problems. Please uninstall ansible and install the new + version: + + pip uninstall ansible + pip install ansible-base + + ... + +As explained by the message, to upgrade you must first remove the version of Ansible installed and then install it +to the latest version. + +.. code-block:: console + + $ pip uninstall ansible + $ pip install ansible + .. _from_pip_devel: Installing the development version of Ansible @@ -333,6 +368,10 @@ Installing the development version of Ansible You should only run Ansible from ``devel`` if you are modifying the Ansible engine, or trying out features under development. This is a rapidly changing source of code and can become unstable at any point. +.. note:: + + If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it. + The development version of Ansible can be directly installed from GitHub with pip:: $ python -m pip install --user https://github.com/ansible/ansible/archive/devel.tar.gz @@ -348,6 +387,10 @@ See :ref:`from_source` for instructions on how to run Ansible directly from sour Virtual Environments ^^^^^^^^^^^^^^^^^^^^ +.. note:: + + If you have Ansible 2.9 or older installed, you need to use ``pip uninstall ansible`` first to remove older versions of Ansible before re-installing it. + Ansible can also be installed inside a new or existing ``virtualenv``:: $ python -m virtualenv ansible # Create a virtualenv if one does not already exist diff --git a/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst b/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst index fc1ef685b1732a..9c68c60b486648 100644 --- a/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst @@ -113,7 +113,9 @@ The ``handle_httperror(self, exception)`` method can deal with status codes retu * A value of ``true`` means that the request can be retried. This my be used to indicate a transient error, or one that has been resolved. For example, the default implementation will try to call ``login()`` when presented with a 401, and return ``true`` if successful. -* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be returned to the calling module as an exception. Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response. +* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be raised as an exception to the calling module. + +* Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response. For example httpapi plugins, see the `source code for the httpapi plugins `_ included with Ansible Core. diff --git a/docs/docsite/rst/network/user_guide/platform_ce.rst b/docs/docsite/rst/network/user_guide/platform_ce.rst index 2a26d43dbc21fa..194917482c19a5 100644 --- a/docs/docsite/rst/network/user_guide/platform_ce.rst +++ b/docs/docsite/rst/network/user_guide/platform_ce.rst @@ -4,11 +4,12 @@ CloudEngine OS Platform Options *************************************** -CloudEngine CE OS supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +CloudEngine CE OS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -27,7 +28,8 @@ Connections Available Indirect Access via a bastion (jump host) via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: netconf`` + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.netconf`` |enable_mode| not supported by ce OS not supported by ce OS @@ -36,7 +38,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, Ansible still supports ``ansible_connection=local`` on all CloudEngine modules. We recommend modernizing to use ``ansible_connection=netconf`` or ``ansible_connection=network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.netconf`` or ``ansible_connection=ansible.netcommon.network_cli`` instead. Using CLI in Ansible ==================== @@ -47,8 +49,8 @@ Example CLI inventory ``[ce:vars]`` .. code-block:: yaml [ce:vars] - ansible_connection=network_cli - ansible_network_os=ce + ansible_connection=ansible.netcommon.network_cli + ansible_network_os=community.network.ce ansible_user=myuser ansible_password=!vault... ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -58,15 +60,15 @@ Example CLI inventory ``[ce:vars]`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Retrieve CE OS version - ce_command: + community.network.ce_command: commands: display version - when: ansible_network_os == 'ce' + when: ansible_network_os == 'community.network.ce' Using NETCONF in Ansible @@ -80,16 +82,16 @@ Before you can use NETCONF to connect to a switch, you must: - install the ``ncclient`` python package on your control node(s) with ``pip install ncclient`` - enable NETCONF on the CloudEngine OS device(s) -To enable NETCONF on a new switch via Ansible, use the ``ce_config`` module via the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this: +To enable NETCONF on a new switch using Ansible, use the ``community.network.ce_config`` module with the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this: .. code-block:: yaml - name: Enable NETCONF - connection: network_cli - ce_config: + connection: ansible.netcommon.network_cli + community.network.ce_config: lines: - snetconf server enable - when: ansible_network_os == 'ce' + when: ansible_network_os == 'community.network.ce' Once NETCONF is enabled, change your variables to use the NETCONF connection. @@ -99,110 +101,110 @@ Example NETCONF inventory ``[ce:vars]`` .. code-block:: yaml [ce:vars] - ansible_connection=netconf - ansible_network_os=ce + ansible_connection=ansible.netcommon.netconf + ansible_network_os=community.network.ce ansible_user=myuser ansible_password=!vault | ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"' -Example NETCONF Task +Example NETCONF task -------------------- .. code-block:: yaml - name: Create a vlan, id is 50(ce) - ce_vlan: + community.network.ce_vlan: vlan_id: 50 name: WEB - when: ansible_network_os == 'ce' + when: ansible_network_os == 'community.network.ce' Notes ======================== -Modules work with connection C(network_cli) --------------------------------------------- +Modules that work with ``ansible.netcommon.network_cli`` +--------------------------------------------------------- .. code-block:: yaml - ce_acl_interface - ce_command - ce_config - ce_evpn_bgp - ce_evpn_bgp_rr - ce_evpn_global - ce_facts - ce_mlag_interface - ce_mtu - ce_netstream_aging - ce_netstream_export - ce_netstream_global - ce_netstream_template - ce_ntp_auth - ce_rollback - ce_snmp_contact - ce_snmp_location - ce_snmp_traps - ce_startup - ce_stp - ce_vxlan_arp - ce_vxlan_gateway - ce_vxlan_global - - -Modules work with connection C(netconf) --------------------------------------------- + community.network.ce_acl_interface + community.network.ce_command + community.network.ce_config + community.network.ce_evpn_bgp + community.network.ce_evpn_bgp_rr + community.network.ce_evpn_global + community.network.ce_facts + community.network.ce_mlag_interface + community.network.ce_mtu + community.network.ce_netstream_aging + community.network.ce_netstream_export + community.network.ce_netstream_global + community.network.ce_netstream_template + community.network.ce_ntp_auth + community.network.ce_rollback + community.network.ce_snmp_contact + community.network.ce_snmp_location + community.network.ce_snmp_traps + community.network.ce_startup + community.network.ce_stp + community.network.ce_vxlan_arp + community.network.ce_vxlan_gateway + community.network.ce_vxlan_global + + +Modules that work with ``ansible.netcommon.netconf`` +----------------------------------------------------- .. code-block:: yaml - ce_aaa_server - ce_aaa_server_host - ce_acl - ce_acl_advance - ce_bfd_global - ce_bfd_session - ce_bfd_view - ce_bgp - ce_bgp_af - ce_bgp_neighbor - ce_bgp_neighbor_af - ce_dldp - ce_dldp_interface - ce_eth_trunk - ce_evpn_bd_vni - ce_file_copy - ce_info_center_debug - ce_info_center_global - ce_info_center_log - ce_info_center_trap - ce_interface - ce_interface_ospf - ce_ip_interface - ce_lacp - ce_link_status - ce_lldp - ce_lldp_interface - ce_mlag_config - ce_netconf - ce_ntp - ce_ospf - ce_ospf_vrf - ce_reboot - ce_sflow - ce_snmp_community - ce_snmp_target_host - ce_snmp_user - ce_static_route - ce_static_route_bfd - ce_switchport - ce_vlan - ce_vrf - ce_vrf_af - ce_vrf_interface - ce_vrrp - ce_vxlan_tunnel - ce_vxlan_vap + community.network.ce_aaa_server + community.network.ce_aaa_server_host + community.network.ce_acl + community.network.ce_acl_advance + community.network.ce_bfd_global + community.network.ce_bfd_session + community.network.ce_bfd_view + community.network.ce_bgp + community.network.ce_bgp_af + community.network.ce_bgp_neighbor + community.network.ce_bgp_neighbor_af + community.network.ce_dldp + community.network.ce_dldp_interface + community.network.ce_eth_trunk + community.network.ce_evpn_bd_vni + community.network.ce_file_copy + community.network.ce_info_center_debug + community.network.ce_info_center_global + community.network.ce_info_center_log + community.network.ce_info_center_trap + community.network.ce_interface + community.network.ce_interface_ospf + community.network.ce_ip_interface + community.network.ce_lacp + community.network.ce_link_status + community.network.ce_lldp + community.network.ce_lldp_interface + community.network.ce_mlag_config + community.network.ce_netconf + community.network.ce_ntp + community.network.ce_ospf + community.network.ce_ospf_vrf + community.network.ce_reboot + community.network.ce_sflow + community.network.ce_snmp_community + community.network.ce_snmp_target_host + community.network.ce_snmp_user + community.network.ce_static_route + community.network.ce_static_route_bfd + community.network.ce_switchport + community.network.ce_vlan + community.network.ce_vrf + community.network.ce_vrf_af + community.network.ce_vrf_interface + community.network.ce_vrrp + community.network.ce_vxlan_tunnel + community.network.ce_vxlan_vap .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_cnos.rst b/docs/docsite/rst/network/user_guide/platform_cnos.rst index 92b1c9c40bfed5..62e1d54993a283 100644 --- a/docs/docsite/rst/network/user_guide/platform_cnos.rst +++ b/docs/docsite/rst/network/user_guide/platform_cnos.rst @@ -4,11 +4,12 @@ CNOS Platform Options *************************************** -CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. +CNOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -36,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, CNOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. Using CLI in Ansible ================================================================================ @@ -46,8 +47,8 @@ Example CLI ``group_vars/cnos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: cnos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.cnos ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -60,15 +61,15 @@ Example CLI ``group_vars/cnos.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Retrieve CNOS OS version - cnos_command: + community.network.cnos_command: commands: show version - when: ansible_network_os == 'cnos' + when: ansible_network_os == 'community.network.cnos' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_dellos10.rst b/docs/docsite/rst/network/user_guide/platform_dellos10.rst index 763d82cd4cf723..638932a275d3b1 100644 --- a/docs/docsite/rst/network/user_guide/platform_dellos10.rst +++ b/docs/docsite/rst/network/user_guide/platform_dellos10.rst @@ -4,11 +4,12 @@ Dell OS10 Platform Options *************************************** -OS10 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible. +The `dellemc.os10 `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -36,7 +37,8 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, OS10 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. + Using CLI in Ansible ================================================================================ @@ -46,8 +48,8 @@ Example CLI ``group_vars/dellos10.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: dellos10 + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os10.os10 ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -60,16 +62,16 @@ Example CLI ``group_vars/dellos10.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (dellos10) - dellos10_config: + dellemc.os10.os10_config: backup: yes register: backup_dellos10_location - when: ansible_network_os == 'dellos10' + when: ansible_network_os == 'dellemc.os10.os10' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_dellos6.rst b/docs/docsite/rst/network/user_guide/platform_dellos6.rst index 3ad45508d32f53..d315c59d93d9e4 100644 --- a/docs/docsite/rst/network/user_guide/platform_dellos6.rst +++ b/docs/docsite/rst/network/user_guide/platform_dellos6.rst @@ -4,11 +4,12 @@ Dell OS6 Platform Options *************************************** -OS6 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible. +The `dellemc.os6 `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS6 in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -36,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, OS6 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. Using CLI in Ansible ================================================================================ @@ -46,8 +47,8 @@ Example CLI ``group_vars/dellos6.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: dellos6 + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os6.os6 ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -60,16 +61,16 @@ Example CLI ``group_vars/dellos6.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (dellos6) - dellos6_config: + dellemc.os6.os6_config: backup: yes register: backup_dellso6_location - when: ansible_network_os == 'dellos6' + when: ansible_network_os == 'dellemc.os6.os6' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_dellos9.rst b/docs/docsite/rst/network/user_guide/platform_dellos9.rst index 4ceb007c3a514f..cadde62284dbcf 100644 --- a/docs/docsite/rst/network/user_guide/platform_dellos9.rst +++ b/docs/docsite/rst/network/user_guide/platform_dellos9.rst @@ -4,11 +4,12 @@ Dell OS9 Platform Options *************************************** -OS9 supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible. +The `dellemc.os9 `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS9 in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -36,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, OS9 still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. Using CLI in Ansible ================================================================================ @@ -46,8 +47,8 @@ Example CLI ``group_vars/dellos9.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: dellos9 + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: dellemc.os9.os9 ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -60,16 +61,16 @@ Example CLI ``group_vars/dellos9.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (dellos9) - dellos9_config: + dellemc.os9.os9_config: backup: yes register: backup_dellos9_location - when: ansible_network_os == 'dellos9' + when: ansible_network_os == 'dellemc.os9.os9' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_enos.rst b/docs/docsite/rst/network/user_guide/platform_enos.rst index da2ac92dea744f..58c0b83e057983 100644 --- a/docs/docsite/rst/network/user_guide/platform_enos.rst +++ b/docs/docsite/rst/network/user_guide/platform_enos.rst @@ -4,11 +4,12 @@ ENOS Platform Options *************************************** -ENOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. +ENOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -38,7 +39,7 @@ Connections Available +---------------------------+-----------------------------------------------+ -For legacy playbooks, ENOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. Using CLI in Ansible ================================================================================ @@ -48,8 +49,8 @@ Example CLI ``group_vars/enos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: enos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.enos ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -62,15 +63,15 @@ Example CLI ``group_vars/enos.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Retrieve ENOS OS version - enos_command: + community.network.enos_command: commands: show version - when: ansible_network_os == 'enos' + when: ansible_network_os == 'community.network.enos' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst index 993c9e9d8cc6f4..cdd45779e01b30 100644 --- a/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst +++ b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst @@ -4,11 +4,12 @@ ERIC_ECCLI Platform Options *************************************** -Extreme ERIC_ECCLI Ansible modules only supports CLI connections today. This page offers details on how to use ``network_cli`` on ERIC_ECCLI in Ansible. +Extreme ERIC_ECCLI is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on ERIC_ECCLI in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| not supported by ERIC_ECCLI @@ -34,7 +35,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +ERIC_ECCLI does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -44,8 +45,8 @@ Example CLI ``group_vars/eric_eccli.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: eric_eccli + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.eric_eccli ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -55,15 +56,15 @@ Example CLI ``group_vars/eric_eccli.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: run show version on remote devices (eric_eccli) - eric_eccli_command: + community.network.eric_eccli_command: commands: show version - when: ansible_network_os == 'eric_eccli' + when: ansible_network_os == 'community.network.eric_eccli' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_exos.rst b/docs/docsite/rst/network/user_guide/platform_exos.rst index 16c4ce403388c1..e27e9ae4bcf4b7 100644 --- a/docs/docsite/rst/network/user_guide/platform_exos.rst +++ b/docs/docsite/rst/network/user_guide/platform_exos.rst @@ -4,11 +4,12 @@ EXOS Platform Options *************************************** -Extreme EXOS Ansible modules support multiple connections. This page offers details on how each connection works in Ansible and how to use it. +Extreme EXOS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ @@ -26,7 +27,8 @@ Connections Available Indirect Access via a bastion (jump host) via a web proxy - Connection Settings ``ansible_connection: network_cli`` ``ansible_connection: httpapi`` + Connection Settings ``ansible_connection:`` ``ansible_connection:`` + ``ansible.netcommon.network_cli`` ``ansible.netcommon.httpapi`` |enable_mode| not supported by EXOS not supported by EXOS @@ -35,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli`` or ``ansible_connection: httpapi`` +EXOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.httpapi``. Using CLI in Ansible ==================== @@ -45,8 +47,8 @@ Example CLI ``group_vars/exos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: exos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.exos ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -56,15 +58,15 @@ Example CLI ``group_vars/exos.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Retrieve EXOS OS version - exos_command: + community.network.exos_command: commands: show version - when: ansible_network_os == 'exos' + when: ansible_network_os == 'community.network.exos' @@ -76,8 +78,8 @@ Example EXOS-API ``group_vars/exos.yml`` .. code-block:: yaml - ansible_connection: httpapi - ansible_network_os: exos + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: community.network.exos ansible_user: myuser ansible_password: !vault... proxy_env: @@ -87,15 +89,15 @@ Example EXOS-API ``group_vars/exos.yml`` - If you are accessing your host through a web proxy using ``https``, change ``http_proxy`` to ``https_proxy``. -Example EXOS-API Task +Example EXOS-API task --------------------- .. code-block:: yaml - name: Retrieve EXOS OS version - exos_command: + community.network.exos_command: commands: show version - when: ansible_network_os == 'exos' + when: ansible_network_os == 'community.network.exos' In this example the ``proxy_env`` variable defined in ``group_vars`` gets passed to the ``environment`` option of the module used in the task. diff --git a/docs/docsite/rst/network/user_guide/platform_icx.rst b/docs/docsite/rst/network/user_guide/platform_icx.rst index ed608cea1e6d51..96777f1ec60c5d 100644 --- a/docs/docsite/rst/network/user_guide/platform_icx.rst +++ b/docs/docsite/rst/network/user_guide/platform_icx.rst @@ -4,11 +4,12 @@ ICX Platform Options *************************************** -ICX supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible. +ICX is part of the `community.network `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` and ``ansible_become_password:`` @@ -44,8 +45,8 @@ Example CLI ``group_vars/icx.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: icx + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.icx ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -58,16 +59,16 @@ Example CLI ``group_vars/icx.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (icx) - icx_config: + community.network.icx_config: backup: yes register: backup_icx_location - when: ansible_network_os == 'icx' + when: ansible_network_os == 'community.network.icx' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_ironware.rst b/docs/docsite/rst/network/user_guide/platform_ironware.rst index 13b94931245320..a17141c4cdc736 100644 --- a/docs/docsite/rst/network/user_guide/platform_ironware.rst +++ b/docs/docsite/rst/network/user_guide/platform_ironware.rst @@ -4,11 +4,12 @@ IronWare Platform Options *************************************** -IronWare supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible. +IronWare is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -25,7 +26,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -37,7 +38,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -For legacy playbooks, IronWare still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. +The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` instead. Using CLI in Ansible ==================== @@ -47,8 +48,8 @@ Example CLI ``group_vars/mlx.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: ironware + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.ironware ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -61,16 +62,16 @@ Example CLI ``group_vars/mlx.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (ironware) - ironware_config: + community.network.ironware_config: backup: yes register: backup_ironware_location - when: ansible_network_os == 'ironware' + when: ansible_network_os == 'community.network.ironware' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_meraki.rst b/docs/docsite/rst/network/user_guide/platform_meraki.rst index 802f8218de8f2e..e51ca5b9120fa4 100644 --- a/docs/docsite/rst/network/user_guide/platform_meraki.rst +++ b/docs/docsite/rst/network/user_guide/platform_meraki.rst @@ -4,11 +4,12 @@ Meraki Platform Options *************************************** -Meraki only support supports the ``local`` connection type at this time. +The `cisco.meraki `_ collection only supports the ``local`` connection type at this time. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -27,12 +28,12 @@ Connections Available ==================== ========================================== -Example Meraki Task +Example Meraki task ------------------- .. code-block:: yaml - meraki_organization: + cisco.meraki.meraki_organization: auth_key: abc12345 org_name: YourOrg state: present diff --git a/docs/docsite/rst/network/user_guide/platform_netvisor.rst b/docs/docsite/rst/network/user_guide/platform_netvisor.rst index 76ec9ad038c801..57748658a71cf0 100644 --- a/docs/docsite/rst/network/user_guide/platform_netvisor.rst +++ b/docs/docsite/rst/network/user_guide/platform_netvisor.rst @@ -4,12 +4,13 @@ Pluribus NETVISOR Platform Options ********************************** -Pluribus NETVISOR Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future. -This page offers details on how to use ``network_cli`` on NETVISOR in Ansible. +Pluribus NETVISOR Ansible is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on NETVISOR in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -26,7 +27,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| not supported by NETVISOR @@ -35,7 +36,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +Pluribus NETVISOR does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -45,8 +46,8 @@ Example CLI ``group_vars/netvisor.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: netvisor + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.netcommon.netvisor ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -56,18 +57,18 @@ Example CLI ``group_vars/netvisor.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Create access list - pn_access_list: + community.network.pn_access_list: pn_name: "foo" pn_scope: "local" state: "present" register: acc_list - when: ansible_network_os == 'netvisor' + when: ansible_network_os == 'community.network.netvisor' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_nos.rst b/docs/docsite/rst/network/user_guide/platform_nos.rst index aedaa64f20f101..0ea3f529fbec79 100644 --- a/docs/docsite/rst/network/user_guide/platform_nos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nos.rst @@ -4,12 +4,13 @@ NOS Platform Options *************************************** -Extreme NOS Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future. -This page offers details on how to use ``network_cli`` on NOS in Ansible. +Extreme NOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on NOS in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -26,7 +27,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: community.netcommon.network_cli`` |enable_mode| not supported by NOS @@ -35,7 +36,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +NOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -45,8 +46,8 @@ Example CLI ``group_vars/nos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: nos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.nos ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -56,16 +57,16 @@ Example CLI ``group_vars/nos.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Get version information (nos) - nos_command: + community.network.nos_command: commands: "show version" register: show_ver - when: ansible_network_os == 'nos' + when: ansible_network_os == 'community.network.nos' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_routeros.rst b/docs/docsite/rst/network/user_guide/platform_routeros.rst index 7de02ae5c4db76..387db92d7d2562 100644 --- a/docs/docsite/rst/network/user_guide/platform_routeros.rst +++ b/docs/docsite/rst/network/user_guide/platform_routeros.rst @@ -4,9 +4,13 @@ RouterOS Platform Options *************************************** -.. contents:: Topics +RouterOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on RouterOS in Ansible. -Connections Available +.. contents:: + :local: + +Connections available ================================================================================ .. table:: @@ -23,7 +27,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.network.network_cli`` |enable_mode| not supported by RouterOS @@ -33,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -43,8 +47,8 @@ Example CLI ``group_vars/routeros.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: routeros + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.routeros ansible_user: myuser ansible_password: !vault... ansible_become: yes @@ -58,16 +62,16 @@ Example CLI ``group_vars/routeros.yml`` - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. - If you are getting timeout errors you may want to add ``+cet1024w`` suffix to your username which will disable console colors, enable "dumb" mode, tell RouterOS not to try detecting terminal capabilities and set terminal width to 1024 columns. See article `Console login process `_ in MikroTik wiki for more information. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Display resource statistics (routeros) - routeros_command: + community.network.routeros_command: commands: /system resource print register: routeros_resources - when: ansible_network_os == 'routeros' + when: ansible_network_os == 'community.network.routeros' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_slxos.rst b/docs/docsite/rst/network/user_guide/platform_slxos.rst index 815e0eb98ef74c..f433599ca3d530 100644 --- a/docs/docsite/rst/network/user_guide/platform_slxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_slxos.rst @@ -4,12 +4,13 @@ SLX-OS Platform Options *************************************** -Extreme SLX-OS Ansible modules only support CLI connections today. ``httpapi`` modules may be added in future. -This page offers details on how to use ``network_cli`` on SLX-OS in Ansible. +Extreme SLX-OS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +This page offers details on how to use ``ansible.netcommon.network_cli`` on SLX-OS in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -26,7 +27,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| not supported by SLX-OS @@ -36,7 +37,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +SLX-OS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -46,8 +47,8 @@ Example CLI ``group_vars/slxos.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: slxos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.slxos ansible_user: myuser ansible_password: !vault... ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -57,16 +58,16 @@ Example CLI ``group_vars/slxos.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Backup current switch config (slxos) - slxos_config: + community.network.slxos_config: backup: yes register: backup_slxos_location - when: ansible_network_os == 'slxos' + when: ansible_network_os == 'community.network.slxos' .. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_voss.rst b/docs/docsite/rst/network/user_guide/platform_voss.rst index a5e6e225e95f48..b532e224d5bcbf 100644 --- a/docs/docsite/rst/network/user_guide/platform_voss.rst +++ b/docs/docsite/rst/network/user_guide/platform_voss.rst @@ -4,12 +4,13 @@ VOSS Platform Options *************************************** -Extreme VOSS Ansible modules only support CLI connections today. This page offers details on how to -use ``network_cli`` on VOSS in Ansible. +Extreme VOSS is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to +use ``ansible.netcommon.network_cli`` on VOSS in Ansible. -.. contents:: Topics +.. contents:: + :local: -Connections Available +Connections available ================================================================================ .. table:: @@ -26,7 +27,7 @@ Connections Available Indirect Access via a bastion (jump host) - Connection Settings ``ansible_connection: network_cli`` + Connection Settings ``ansible_connection: ansible.netcommon.network_cli`` |enable_mode| supported: use ``ansible_become: yes`` with ``ansible_become_method: enable`` @@ -37,7 +38,7 @@ Connections Available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: network_cli``. +VOSS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. Using CLI in Ansible ==================== @@ -47,8 +48,8 @@ Example CLI ``group_vars/voss.yml`` .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: voss + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: community.network.voss ansible_user: myuser ansible_become: yes ansible_become_method: enable @@ -60,15 +61,15 @@ Example CLI ``group_vars/voss.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. -Example CLI Task +Example CLI task ---------------- .. code-block:: yaml - name: Retrieve VOSS info - voss_command: + community.network.voss_command: commands: show sys-info - when: ansible_network_os == 'voss' + when: ansible_network_os == 'community.network.voss' .. include:: shared_snippets/SSH_warning.txt 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 7200cad2aebb57..dd4b511ff1a895 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.10.rst @@ -19,7 +19,7 @@ We suggest you read this page along with the `Ansible Changelog for 2.10 `_. +* a `set of collections `_. The :ref:`porting_2.10_guide_base` is included in this porting guide. The complete list of porting guides can be found at :ref:`porting guides `. @@ -165,6 +165,71 @@ Networking No notable changes +Porting Guide for v2.10.0a8 +=========================== + +Breaking Changes +---------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- 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). +- 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). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_datastore_maintenancemode - now returns ``datastore_status`` instead of Ansible internal key ``results``. +- vmware_guest_custom_attributes - does not require VM name which was a required parameter for releases prior to Ansible 2.10. +- vmware_guest_find - the ``datacenter`` option has been removed. +- vmware_host_kernel_manager - now returns ``host_kernel_status`` instead of Ansible internal key ``results``. +- vmware_host_ntp - now returns ``host_ntp_status`` instead of Ansible internal key ``results``. +- vmware_host_service_manager - now returns ``host_service_status`` instead of Ansible internal key ``results``. +- vmware_tag - now returns ``tag_status`` instead of Ansible internal key ``results``. +- vmware_vmkernel - the options ``ip_address`` and ``subnet_mask`` have been removed; use the suboptions ``ip_address`` and ``subnet_mask`` of the ``network`` option instead. + +Removed Features +---------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- conjur_variable lookup - has been moved to the ``cyberark.conjur`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/570). +- digital_ocean_* - all DigitalOcean modules have been moved to the ``community.digitalocean`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/622). +- infini_* - all infinidat modules have been moved to the ``infinidat.infinibox`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/607). +- logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541). +- logicmonitor_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541). +- mysql_* - all MySQL modules have been moved to the ``community.mysql`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/633). +- proxysql_* - all ProxySQL modules have been moved to the ``community.proxysql`` collection. A redirection is active, which will be removed in version 2.0.0 (https://github.com/ansible-collections/community.general/pull/624). + +community.network +~~~~~~~~~~~~~~~~~ + +- onyx - all onyx modules and plugins have been moved to the mellanox.onyx collection. Redirects have been added that will be removed in community.network 2.0.0 (https://github.com/ansible-collections/community.network/pull/83). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_portgroup - removed 'inbound_policy', and 'rolling_order' deprecated options. + +Deprecated Features +------------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- The ldap_attr module has been deprecated and will be removed in a later release; use ldap_attrs instead. +- xbps - the ``force`` option never had any effect. It is now deprecated, and will be removed in 3.0.0 (https://github.com/ansible-collections/community.general/pull/568). + +community.vmware +~~~~~~~~~~~~~~~~ + +- The vmware_dns_config module has been deprecated and will be removed in a later release; use vmware_host_dns instead. +- vca - vca_fw, vca_nat, vca_app are deprecated since these modules rely on deprecated part of Pyvcloud library. +- vmware_tag_info - in a later release, the module will not return ``tag_facts`` since it does not return multiple tags with the same name and different category id. To maintain the existing behavior use ``tag_info`` which is a list of tag metadata. + Porting Guide for v2.10.0a7 =========================== @@ -283,8 +348,6 @@ community.general ~~~~~~~~~~~~~~~~~ - core - remove support for ``check_invalid_arguments`` in ``UTMModule``. -- logicmonitor - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541). -- logicmonitor_facts - the module has been removed in 1.0.0 since it is unmaintained and the API used by the module has been turned off in 2017 (https://github.com/ansible-collections/community.general/issues/539, https://github.com/ansible-collections/community.general/pull/541). - pacman - Removed deprecated ``recurse`` option, use ``extra_args=--recursive`` instead community.vmware @@ -326,7 +389,6 @@ community.general - redfish_config - the ``bios_attribute_name`` and ``bios_attribute_value`` options will be removed. To maintain the existing behavior use the ``bios_attributes`` option instead. - redfish_config and redfish_command - the behavior to select the first System, Manager, or Chassis resource to modify when multiple are present will be removed. Use the new ``resource_id`` option to specify target resource to modify. - redfish_config, redfish_command - Behavior to modify the first System, Mananger, or Chassis resource when multiple are present is deprecated. Use the new ``resource_id`` option to specify target resource to modify. -- xbps - the ``force`` option never had any effect. It is now deprecated, and will be removed in 3.0.0 (https://github.com/ansible-collections/community.general/pull/568). - zabbix_proxy - 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. community.vmware @@ -346,7 +408,6 @@ Breaking Changes * Junction points are no longer reported as ``islnk``, use ``isjunction`` to properly report these files. This behaviour matches the ansible.windows.win_stat module * Directories no longer return a ``size``, this matches the ``stat`` and ``find`` behaviour and has been removed due to the difficulties in correctly reporting the size of a directory - cisco.nxos.nxos_igmp_interface - no longer supports the deprecated ``oif_prefix`` and ``oif_source`` options. These have been superceeded by ``oif_ps``. -- community.general.pacman - the deprecated ``recurse`` option has been removed, you should use ``extra_args=--recursive`` instead. - community.grafana.grafana_dashboard - the parameter ``message`` is renamed to ``commit_message`` since ``message`` is used by Ansible Core engine internally. - community.vmware.vmware_datastore_maintenancemode - now returns ``datastore_status`` instead of Ansible internal key ``results``. - community.vmware.vmware_guest_custom_attributes - does not require VM name which was a required parameter for releases prior to Ansible 2.10. @@ -392,7 +453,6 @@ Removed Features Deprecated Features ------------------- -- The community.general.ldap_attr module has been deprecated and will be removed in a later release; use community.general.ldap_attrs instead. - The community.vmware.vmware_dns_config module has been deprecated and will be removed in a later release; use community.vmware.vmware_host_dns instead. - The vyos.vyos.vyos_static_route module has been deprecated and will be removed in a later release; use vyos.vyos.vyos_static_routes instead. - amazon.aws.cloudformation - the ``template_format`` option has been deprecated and will be removed in a later release. It has been ignored by the module since Ansible 2.3. diff --git a/docs/docsite/rst/porting_guides/porting_guide_base_2.11.rst b/docs/docsite/rst/porting_guides/porting_guide_base_2.11.rst new file mode 100644 index 00000000000000..f7bc9b6a4802c9 --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_base_2.11.rst @@ -0,0 +1,156 @@ + +.. _porting_2.11_guide_base: + +******************************* +Ansible-base 2.11 Porting Guide +******************************* + +This section discusses the behavioral changes between Ansible-base 2.10 and Ansible-base 2.11. + +It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible-base. + +We suggest you read this page along with the `Ansible-base Changelog for 2.11 `_ to understand what updates you may need to make. + +Ansible-base is mainly of interest for developers and users who only want to use a small, controlled subset of the available collections. Regular users should install ansible. + +The complete list of porting guides can be found at :ref:`porting guides `. + +.. contents:: + + +Playbook +======== + +* Fixed a bug on boolean keywords that made random strings return 'False', now they should return an error if they are not a proper boolean + Example: `diff: yes-` was returning `False`. +* A new fact, ``ansible_processor_nproc`` reflects the number of vcpus + available to processes (falls back to the number of vcpus available to + the scheduler). + + +Command Line +============ + +No notable changes + + +Deprecated +========== + +* Windows Server 2008 and 2008 R2 will no longer be supported or tested in the next Ansible release, see :ref:`windows_faq_server2008`. + + +Modules +======= + +Change to Default File Permissions +---------------------------------- + +To address CVE-2020-1736, the default permissions for certain files created by Ansible using ``atomic_move()`` were changed from ``0o666`` to ``0o600``. The default permissions value was only used for the temporary file before it was moved into its place or newly created files. If the file existed when the new temporary file was moved into place, Ansible would use the permissions of the existing file. If there was no existing file, Ansible would retain the default file permissions, combined with the system ``umask``, of the temporary file. + +Most modules that call ``atomic_move()`` also call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``, which will set the permissions of the file to what is specified in the task. + +A new warning will be displayed when all of the following conditions are true: + + - The file at the final destination, not the temporary file, does not exist + - A module supports setting ``mode`` but it was not specified for the task + - The module calls ``atomic_move()`` but does not later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()`` with a ``mode`` specified + +The following modules call ``atomic_move()`` but do not call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()`` and do not support setting ``mode``. This means for files they create, the default permissions have changed and there is no indication: + + - M(known_hosts) + - M(service) + + +Code Audit +~~~~~~~~~~ + +The code was audited for modules that use ``atomic_move()`` but **do not** later call ``set_fs_attributes_if_different()`` or ``set_mode_if_different()``. Modules that provide no means for specifying the ``mode`` will not display a warning message since there is no way for the playbook author to remove the warning. The behavior of each module with regards to the default permissions of temporary files and the permissions of newly created files is explained below. + +known_hosts +^^^^^^^^^^^ + +The M(known_hosts) module uses ``atomic_move()`` to operate on the ``known_hosts`` file specified by the ``path`` parameter in the module. It creates a temporary file using ``tempfile.NamedTemporaryFile()`` which creates a temporary file that is readable and writable only by the creating user ID. + +service +^^^^^^^ + +The M(service) module uses ``atomic_move()`` to operate on the default rc file, which is the first found of ``/etc/rc.conf``, ``/etc/rc.conf.local``, and ``/usr/local/etc/rc.conf``. Since these files almost always exist on the target system, they will not be created and the existing permissions of the file will be used. + +**The following modules were included in Ansible <= 2.9. They have moved to collections but are documented here for completeness.** + +authorized_key +^^^^^^^^^^^^^^ + +The M(authorized_key) module uses ``atomic_move()`` to operate on the the ``authorized_key`` file. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. The M(authorized_key) module manages the permissions of the the ``.ssh`` direcotry and ``authorized_keys`` files if ``managed_dirs`` is set to ``True``, which is the default. The module sets the ``ssh`` directory owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and directory permissions to ``700``. The module sets the ``authorized_key`` file owner and group to the ``uid`` and ``gid`` of the user specified in the ``user`` parameter and file permissions to ``600``. These values cannot be controlled by module parameters. + +interfaces_file +^^^^^^^^^^^^^^^ +The M(interfaces_file) module uses ``atomic_move()`` to operate on ``/etc/network/serivces`` or the ``dest`` specified by the module. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. If the file specified by ``path`` does not exist it will retain the permissions of the temporary file once moved into place. + +pam_limits +^^^^^^^^^^ + +The M(pam_limits) module uses ``atomic_move()`` to operate on ``/etc/security/limits.conf`` or the value of ``dest``. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file specified by ``dest``, or it will retain the permissions that only allow the creating user ID to read and write the file. + +pamd +^^^^ + +The M(pamd) module uses ``atomic_move()`` to operate on a file in ``/etc/pam.d``. The path and the file can be specified by setting the ``path`` and ``name`` parameters. A temporary file is created using ``tempfile.NamedTemporaryFile()``, which is only readable and writable by the creating user ID. The temporary file will inherit the permissions of the file located at ``[dest]/[name]``, or it will retain the permissions of the temporary file that only allow the creating user ID to read and write the file. + +redhat_subscription +^^^^^^^^^^^^^^^^^^^ + +The M(redhat_subscription) module uses ``atomic_move()`` to operate on ``/etc/yum/pluginconf.d/rhnplugin.conf`` and ``/etc/yum/pluginconf.d/subscription-manager.conf``. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID and the temporary file will inherit the permissions of the existing file once it is moved in to place. + +selinux +^^^^^^^ + +The M(selinux) module uses ``atomic_move()`` to operate on ``/etc/selinux/config`` on the value specified by ``configfile``. The module will fail if ``configfile`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``configfile`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place. + +sysctl +^^^^^^ + +The M(sysctl) module uses ``atomic_move()`` to operate on ``/etc/sysctl.conf`` or the value specified by ``sysctl_file``. The module will fail if ``sysctl_file`` does not exist before any temporary data is written to disk. A temporary file is created with ``tempfile.mkstemp()`` before being moved into place. The temporary file is readable and writable only by the creating user ID. Since the file specified by ``sysctl_file`` must exist, the temporary file will inherit the permissions of that file once it is moved in to place. + +.. warning:: + + Links on this page may not point to the most recent versions of modules. We will update them when we can. + + +Noteworthy module changes +------------------------- + +* Ansible modules created with ``add_file_common_args=True`` added a number of undocumented arguments which were mostly there to ease implementing certain action plugins. The undocumented arguments ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode`` are now no longer added. Modules relying on these options to be added need to specify them by themselves. +* Ansible no longer looks for Python modules in the current working directory (typically the ``remote_user``'s home directory) when an Ansible module is run. This is to fix becoming an unprivileged user on OpenBSD and to mitigate any attack vector if the current working directory is writable by a malicious user. Install any Python modules needed to run the Ansible modules on the managed node in a system-wide location or in another directory which is in the ``remote_user``'s ``$PYTHONPATH`` and readable by the ``become_user``. + + +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_``. ``2.10`` brings consistency to ``lookup()`` and ``with_`` to be both case-sensitive. + +Noteworthy plugin changes +------------------------- + +* Cache plugins in collections can be used to cache data from inventory plugins. Previously, cache plugins in collections could only be used for fact caching. +* Some undocumented arguments from ``FILE_COMMON_ARGUMENTS`` have been removed; plugins using these, in particular action plugins, need to be adjusted. The undocumented arguments which were removed are ``src``, ``follow``, ``force``, ``content``, ``backup``, ``remote_src``, ``regexp``, ``delimiter``, and ``directory_mode``. + +Action plugins which execute modules should use fully-qualified module names +---------------------------------------------------------------------------- + +* Action plugins that call modules should pass explicit, fully-qualified module names to ``_execute_module()`` whenever possible (eg, ``ansible.builtin.file`` rather than ``file``). This ensures that the task's collection search order is not consulted to resolve the module. Otherwise, a module from a collection earlier in the search path could be used when not intended. + +Porting custom scripts +====================== + +No notable changes + + +Networking +========== + +No notable changes diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index 627cd2528b6618..618b8473110e13 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -12,6 +12,7 @@ Please note that this is not a complete list. If you believe any extra informati :maxdepth: 1 :glob: + porting_guide_base_2.11 porting_guide_2.10 porting_guide_base_2.10 porting_guide_2.9 diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index bca1ef970ad9c6..5dfa8a72c12ccf 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -20,55 +20,201 @@ backup_file ``````````` For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created. + .. code-block:: console + + "backup_file": "./foo.txt.32729.2020-07-30@06:24:19~" + + changed ``````` A boolean indicating if the task had to make changes. + .. code-block:: console + + "changed": true + diff ```` - Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view. + .. code-block:: console + + "diff": [ + { + "after": "", + "after_header": "foo.txt (content)", + "before": "", + "before_header": "foo.txt (content)" + }, + { + "after_header": "foo.txt (file attributes)", + "before_header": "foo.txt (file attributes)" + } + failed `````` A boolean that indicates if the task was failed or not. + .. code-block:: console + + "failed": false + invocation `````````` Information on how the module was invoked. + .. code-block:: console + + "invocation": { + "module_args": { + "_original_basename": "foo.txt", + "attributes": null, + "backup": true, + "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709", + "content": null, + "delimiter": null, + "dest": "./foo.txt", + "directory_mode": null, + "follow": false, + "force": true, + "group": null, + "local_follow": null, + "mode": "666", + "owner": null, + "regexp": null, + "remote_src": null, + "selevel": null, + "serole": null, + "setype": null, + "seuser": null, + "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source", + "unsafe_writes": null, + "validate": null + } + msg ``` A string with a generic message relayed to the user. + .. code-block:: console + + "msg": "line added" + rc `` Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains 'return code' of these utilities. + .. code-block:: console + + "rc": 257 + results ``````` If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item. + .. code-block:: console + + "results": [ + { + "ansible_loop_var": "item", + "backup": "foo.txt.83170.2020-07-30@07:03:05~", + "changed": true, + "diff": [ + { + "after": "", + "after_header": "foo.txt (content)", + "before": "", + "before_header": "foo.txt (content)" + }, + { + "after_header": "foo.txt (file attributes)", + "before_header": "foo.txt (file attributes)" + } + ], + "failed": false, + "invocation": { + "module_args": { + "attributes": null, + "backrefs": false, + "backup": true + } + }, + "item": "foo", + "msg": "line added" + }, + { + "ansible_loop_var": "item", + "backup": "foo.txt.83187.2020-07-30@07:03:05~", + "changed": true, + "diff": [ + { + "after": "", + "after_header": "foo.txt (content)", + "before": "", + "before_header": "foo.txt (content)" + }, + { + "after_header": "foo.txt (file attributes)", + "before_header": "foo.txt (file attributes)" + } + ], + "failed": false, + "invocation": { + "module_args": { + "attributes": null, + "backrefs": false, + "backup": true + } + }, + "item": "bar", + "msg": "line added" + } + ] + skipped ``````` A boolean that indicates if the task was skipped or not + .. code-block:: console + + "skipped": true + stderr `````` Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities. + .. code-block:: console + + "stderr": "ls: foo: No such file or directory" + stderr_lines ```````````` When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original. + .. code-block:: console + + "stderr_lines": [ + "ls: doesntexist: No such file or directory" + ] + stdout `````` Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities. + .. code-block:: console + + "stdout": "foo!" + stdout_lines ```````````` When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output. + .. code-block:: console + + "stdout_lines": [ + "foo!" + ] + .. _internal_return_values: diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 656d1bb48b6cca..c544a8d8e0206a 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -283,6 +283,20 @@ There are a few common errors that one might run into when trying to execute Ans zos1 ansible_shell_executable=/usr/lpp/bash/bin/bash +Running under fakeroot +---------------------- + +Some issues arise as ``fakeroot`` does not create a full nor POSIX compliant system by default. +It is known that it will not correctly expand the default tmp directory Ansible uses (:file:`~/.ansible/tmp`). +If you see module failures, this is likely the problem. +The simple workaround is to set ``remote_tmp`` to a path that will expand correctly (see documentation of the shell plugin you are using for specifics). + +For example, in the ansible config file (or via environment variable) you can set:: + + remote_tmp=$HOME/.ansible/tmp + + + .. _use_roles: What is the best way to make content reusable/redistributable? diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_2_10.rst b/docs/docsite/rst/roadmap/COLLECTIONS_2_10.rst new file mode 100644 index 00000000000000..5353804dee2eaa --- /dev/null +++ b/docs/docsite/rst/roadmap/COLLECTIONS_2_10.rst @@ -0,0 +1,39 @@ +==================== +Ansible project 2.10 +==================== + +This release schedule includes dates for the `ansible `_ package, with a few dates for the `ansible-base `_ package as well. All dates are subject to change. See :ref:`base_roadmap_2_10` for the most recent updates on ansible-base. + +.. contents:: + :local: + +Release Schedule +---------------- + +.. note:: Dates subject to change. +.. note:: We plan to post weekly alpha releases to the `PyPI ansible project `_ for testing. + +- 2020-06-23: ansible-2.10 alpha freeze. + No net new collections will be added to the ``ansible-2.10`` package after this date. +- 2020-07-10: Ansible collections freeze date for content shuffling. + Content should be in its final collection for the ansible-2.10 series of releases. No more content should move out of the ``community.general`` or ``community.network`` collections. +- 2020-08-13: ansible-base 2.10 Release date, see :ref:`base_roadmap_2_10`. +- 2020-08-14: final ansible-2.10 alpha. +- 2020-08-18: Ansible 2.10 beta freeze. + - No new modules or major features will be added after this date. In practice this means we will freeze the semver collection versions to compatible release versions. For example, if the version of community.crypto on this date was community-crypto-1.1.0; ansible-2.10.0 could ship with community-crypto-1.1.1. It would not ship with community-crypto-1.2.0. +- 2020-09-01: ansible-2.10.0 beta1. +- 2020-09-08: ansible-2.10 final freeze/rc1. + - After this date only changes blocking a release are accepted. + - Collections will only be updated to a new version if a blocker is approved. Collection owners should discuss any blockers at a community IRC meeting (on 9-10 and 9-17) to decide whether to bump the version of the collection for a fix. See the `Community IRC meeting agenda `_. + +** Additional release candidates to be published as needed as blockers are fixed ** + +- 2020-09-22: ansible-2.10 GA release date. + +Ansible-2.10.x patch releases will occur roughly every three weeks if changes to collections have been made or if it is deemed necessary to force an upgrade to a later ansible-base-2.10.x. Ansible-2.10.x patch releases may contain new features but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed (example: Ansible-2.10 ships with community-crypto-1.1.0; ansible-2.10.1 may ship with community-crypto-1.2.0 but would not ship with community-crypto-2.0.0). + +Breaking changes may be introduced in ansible-2.11.0 although we encourage collection owners to use deprecation periods that will show up in at least one Ansible release before being changed incompatibly. + +The rough schedule for Ansible-2.11 and beyond (such as how many months we'll aim for between versions) is still to be discussed and likely will be made after 2.10.0 has been released. + +For more information, reach out on a mailing list or an IRC channel - see :ref:`communication` for more details. diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_10.rst b/docs/docsite/rst/roadmap/ROADMAP_2_10.rst index 38fa104b66a68f..be965365404e13 100644 --- a/docs/docsite/rst/roadmap/ROADMAP_2_10.rst +++ b/docs/docsite/rst/roadmap/ROADMAP_2_10.rst @@ -1,3 +1,5 @@ +.. _base_roadmap_2_10: + ================= Ansible-base 2.10 ================= @@ -19,8 +21,10 @@ PRs must be raised well in advance of the dates below to have a chance of being - 2020-06-16 Beta 1 **Feature freeze** No new functionality (including modules/plugins) to any code -- 2020-07-14 Release Candidate 1 -- 2020-??-?? Release Candidate 2 if needed +- 2020-07-21 Release Candidate 1 (bumped from 2020-07-14) +- 2020-07-24 Release Candidate 2 +- 2020-07-25 Release Candidate 3 +- 2020-07-30 Release Candidate 4 - 2020-08-13 Release Release Manager diff --git a/docs/docsite/rst/roadmap/index.rst b/docs/docsite/rst/roadmap/index.rst index a288530a8736f6..9abc1b532af5a3 100644 --- a/docs/docsite/rst/roadmap/index.rst +++ b/docs/docsite/rst/roadmap/index.rst @@ -24,6 +24,7 @@ See :ref:`Ansible communication channels ` for details on how to :glob: :caption: Ansible Release Roadmaps + COLLECTIONS_2_10 ROADMAP_2_10 ROADMAP_2_9 ROADMAP_2_8 diff --git a/docs/docsite/rst/scenario_guides/guide_vmware.rst b/docs/docsite/rst/scenario_guides/guide_vmware.rst index 92e458b75f07b2..3a257e0b36be34 100644 --- a/docs/docsite/rst/scenario_guides/guide_vmware.rst +++ b/docs/docsite/rst/scenario_guides/guide_vmware.rst @@ -18,6 +18,7 @@ To get started, please select one of the following topics. vmware_scenarios/vmware_requirements vmware_scenarios/vmware_inventory vmware_scenarios/vmware_inventory_vm_attributes + vmware_scenarios/vmware_inventory_hostnames vmware_scenarios/vmware_scenarios vmware_scenarios/vmware_troubleshooting vmware_scenarios/vmware_external_doc_links diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst new file mode 100644 index 00000000000000..ac8dfaf1bccb43 --- /dev/null +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst @@ -0,0 +1,127 @@ +.. _vmware_ansible_inventory_using_hostnames: + +************************************************* +Using VMware dynamic inventory plugin - Hostnames +************************************************* + +.. contents:: Topics + +VMware dynamic inventory plugin - Customizing hostnames +======================================================= + + +VMware inventory plugin allows you to configure hostnames using the ``hostnames`` configuration parameter. + +In this scenario guide we will see how you configure hostnames from the given VMware guest in the inventory. + +Requirements +------------ + +To use the VMware dynamic inventory plugins, you must install `pyVmomi `_ +on your control node (the host running Ansible). + +To include tag-related information for the virtual machines in your dynamic inventory, you also need the `vSphere Automation SDK `_, which supports REST API features such as tagging and content libraries, on your control node. +You can install the ``vSphere Automation SDK`` following `these instructions `_. + +.. code-block:: bash + + $ pip install pyvmomi + +Starting in Ansible 2.10, the VMware dynamic inventory plugin is available in the ``community.vmware`` collection included Ansible. +To install the latest ``community.vmware`` collection: + +.. code-block:: bash + + $ ansible-galaxy collection install community.vmware + +To use this VMware dynamic inventory plugin: + + 1. Enable it first by specifying the following in the ``ansible.cfg`` file: + +.. code-block:: ini + + [inventory] + enable_plugins = community.vmware.vmware_vm_inventory + + 2. Create a file that ends in ``.vmware.yml`` or ``.vmware.yaml`` in your working directory. + +The ``vmware_vm_inventory`` inventory plugin takes in the same authentication information as any other VMware modules does. + +Here's an example of a valid inventory file with custom hostname for the given VMware guest: + +.. code-block:: yaml + + plugin: community.vmware.vmware_vm_inventory + strict: False + hostname: 10.65.223.31 + username: administrator@vsphere.local + password: Esxi@123$% + validate_certs: False + with_tags: False + hostnames: + - config.name + + +Here, we have configured a custom hostname by setting the ``hostnames`` parameter to ``config.name``. This will retrieve +the ``config.name`` property from the virtual machine and populate it in the inventory. + +You can check all allowed properties for the given virtual machine at :ref:`vmware_inventory_vm_attributes`. + +Executing ``ansible-inventory --list -i .vmware.yml`` will create a list of the virtual machines that are ready to be configured using Ansible. + +What to expect +-------------- + +You will notice that instead of default behavior of representing the hostname as ``config.name + _ + config.uuid``, +the inventory hosts show value as ``config.name``. + + +.. code-block:: yaml + + { + "_meta": { + "hostvars": { + "template_001": { + "config.name": "template_001", + "guest.toolsRunningStatus": "guestToolsNotRunning", + ... + "guest.toolsStatus": "toolsNotInstalled", + "name": "template_001" + }, + "vm_8046": { + "config.name": "vm_8046", + "guest.toolsRunningStatus": "guestToolsNotRunning", + ... + "guest.toolsStatus": "toolsNotInstalled", + "name": "vm_8046" + }, + ... + } + +Troubleshooting +--------------- + +If the custom property specified in ``hostnames`` fails: + +- Check if the values provided for username and password are correct. +- Make sure it is a valid property, see :ref:`vmware_inventory_vm_attributes`. +- Use ``strict: True`` to get more information about the error. +- Please make sure that you are using latest version VMware collection. + + +.. seealso:: + + `pyVmomi `_ + The GitHub Page of pyVmomi + `pyVmomi Issue Tracker `_ + The issue tracker for the pyVmomi project + `vSphere Automation SDK GitHub Page `_ + The GitHub Page of vSphere Automation SDK for Python + `vSphere Automation SDK Issue Tracker `_ + The issue tracker for vSphere Automation SDK for Python + :ref:`vmware_inventory_vm_attributes` + Using Virtual machine attributes in VMware dynamic inventory plugin + :ref:`working_with_playbooks` + An introduction to playbooks + :ref:`playbooks_vault` + Using Vault in playbooks diff --git a/docs/docsite/rst/user_guide/intro_getting_started.rst b/docs/docsite/rst/user_guide/intro_getting_started.rst index 0ce64b538776bb..6379f5c5b9e9b0 100644 --- a/docs/docsite/rst/user_guide/intro_getting_started.rst +++ b/docs/docsite/rst/user_guide/intro_getting_started.rst @@ -124,6 +124,10 @@ also has powerful configuration management and deployment features. Examples of basic commands :ref:`working_with_playbooks` Learning Ansible's configuration management language + `Ansible Demos `_ + Demonstrations of different Ansible usecases + `RHEL Labs `_ + Labs to provide further knowledge on different topics `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups `irc.freenode.net `_ diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 99fdc54d4c3239..87cf00d5d9d9e6 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -240,6 +240,24 @@ for example:: - set_fact: myvar: "{{ result.stdout | from_json }}" + +Filter `to_json` and Unicode support +------------------------------------ + +By default `to_json` and `to_nice_json` will convert data received to ASCII, so:: + + {{ 'München'| to_json }} + +will return:: + + 'M\u00fcnchen' + +To keep Unicode characters, pass the parameter `ensure_ascii=False` to the filter:: + + {{ 'München'| to_json(ensure_ascii=False) }} + + 'München' + .. versionadded:: 2.7 To parse multi-document YAML strings, the ``from_yaml_all`` filter is provided. diff --git a/docs/docsite/rst/user_guide/playbooks_tests.rst b/docs/docsite/rst/user_guide/playbooks_tests.rst index cb74de53ef262c..0a1aa8d91ffdc6 100644 --- a/docs/docsite/rst/user_guide/playbooks_tests.rst +++ b/docs/docsite/rst/user_guide/playbooks_tests.rst @@ -59,7 +59,9 @@ To match strings against a substring or a regular expression, use the ``match``, msg: "matched pattern 4" when: url is regex("example.com/\w+/foo") -``match`` succeeds if it finds the pattern at the beginning of the string, while ``search`` succeeds if it finds the pattern anywhere within string. By default, ``regex`` works like ``search``, but ``regex`` can be configured to perform other tests as well. +``match`` succeeds if it finds the pattern at the beginning of the string, while ``search`` succeeds if it finds the pattern anywhere within string. By default, ``regex`` works like ``search``, but ``regex`` can be configured to perform other tests as well, by passing the ``match_type`` keyword argument. In particular, ``match_type`` determines the ``re`` method that gets used to perform the search. The full list can be found in the relevant Python documentation `here `_. + +All of the string tests also take optional ``ignorecase`` and ``multiline`` arguments. These correspond to ``re.I`` and ``re.M`` from Python's ``re`` library, respectively. .. _testing_vault: diff --git a/docs/docsite/rst/user_guide/playbooks_vars_facts.rst b/docs/docsite/rst/user_guide/playbooks_vars_facts.rst index 08a8d90291545c..799230073d35e4 100644 --- a/docs/docsite/rst/user_guide/playbooks_vars_facts.rst +++ b/docs/docsite/rst/user_guide/playbooks_vars_facts.rst @@ -491,6 +491,15 @@ To reference the system hostname:: You can use facts in conditionals (see :ref:`playbooks_conditionals`) and also in templates. You can also use facts to create dynamic groups of hosts that match particular criteria, see the :ref:`group_by module ` documentation for details. +.. _fact_requirements: + +Package requirements for fact gathering +--------------------------------------- + +On some distros, you may see missing fact values or facts set to default values because the packages that support gathering those facts are not installed by default. You can install the necessary packages on your remote hosts using the OS package manager. Known dependencies include: + +* Linux Network fact gathering - Depends on the ``ip`` binary, commonly included in the ``iproute2`` package. + .. _fact_caching: Caching facts diff --git a/lib/ansible/executor/task_executor.py b/lib/ansible/executor/task_executor.py index 573e09a2d0276e..61cf6e6e74abf3 100644 --- a/lib/ansible/executor/task_executor.py +++ b/lib/ansible/executor/task_executor.py @@ -514,7 +514,7 @@ def _execute(self, variables=None): try: # TODO: remove play_context as this does not take delegation into account, task itself should hold values # for connection/shell/become/terminal plugin options to finalize. - # Kept for now for backwards compatiblity and a few functions that are still exclusive to it. + # Kept for now for backwards compatibility and a few functions that are still exclusive to it. # apply the given task's information to the connection info, # which may override some fields already set by the play or diff --git a/lib/ansible/plugins/connection/__init__.py b/lib/ansible/plugins/connection/__init__.py index 0b44295fc2734a..b172c4cedd22e4 100644 --- a/lib/ansible/plugins/connection/__init__.py +++ b/lib/ansible/plugins/connection/__init__.py @@ -232,7 +232,7 @@ def reset(self): # NOTE: these password functions are all become specific, the name is # confusing as it does not handle 'protocol passwords' # DEPRECATED: - # These are kept for backwards compatiblity + # These are kept for backwards compatibility # Use the methods provided by the become plugins instead def check_become_success(self, b_output): display.deprecated( diff --git a/lib/ansible/plugins/httpapi/__init__.py b/lib/ansible/plugins/httpapi/__init__.py index d13f641dfceb92..0773921fb6e360 100644 --- a/lib/ansible/plugins/httpapi/__init__.py +++ b/lib/ansible/plugins/httpapi/__init__.py @@ -62,8 +62,9 @@ def handle_httperror(self, exc): * True if the code has been handled in a way that the request may be resent without changes. * False if the error cannot be handled or recovered from by the - plugin. This will result in the HTTPError being returned to the - caller to deal with as appropriate. + plugin. This will result in the HTTPError being raised as an + exception for the caller to deal with as appropriate (most likely + by failing). * Any other value returned is taken as a valid response from the server without making another request. In many cases, this can just be the original exception. diff --git a/lib/ansible/template/__init__.py b/lib/ansible/template/__init__.py index 0881f8623bed41..603e8df3a32362 100644 --- a/lib/ansible/template/__init__.py +++ b/lib/ansible/template/__init__.py @@ -179,7 +179,7 @@ def is_template(data, jinja_env): comment = False d2 = jinja_env.preprocess(data) - # This wraps a lot of code, but this is due to lex returing a generator + # This wraps a lot of code, but this is due to lex returning a generator # so we may get an exception at any part of the loop try: for token in jinja_env.lex(d2): diff --git a/lib/ansible/utils/vars.py b/lib/ansible/utils/vars.py index 0dd49ca87f163d..17ef2df9de86d6 100644 --- a/lib/ansible/utils/vars.py +++ b/lib/ansible/utils/vars.py @@ -288,7 +288,7 @@ def _isidentifier_PY2(ident): * True, False and None are reserved keywords (these are reserved keywords on Python 3 as opposed to Python 2) -:arg ident: A text string of indentifier to check. Note: It is callers +:arg ident: A text string of identifier to check. Note: It is callers responsibility to convert ident to text if it is not already. Originally posted at http://stackoverflow.com/a/29586366 diff --git a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/ps_argspec.ps1 b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/ps_argspec.ps1 index bf3b1f0370d9f3..5ceb9d50b7df52 100755 --- a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/ps_argspec.ps1 +++ b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/ps_argspec.ps1 @@ -69,7 +69,7 @@ $powershell = [PowerShell]::Create() $powershell.Runspace.SessionStateProxy.SetVariable("ErrorActionPreference", "Stop") # Load the PowerShell module utils as the module may be using them to refer to shared module options. Currently we -# can only load the PowerShell utils due to cross platform compatiblity issues. +# can only load the PowerShell utils due to cross platform compatibility issues. if ($manifest.Contains('ps_utils')) { foreach ($util_info in $manifest.ps_utils.GetEnumerator()) { $util_name = $util_info.Key