From b72960fdd4addbdbce2c7a28c4193e2d3f136cc8 Mon Sep 17 00:00:00 2001 From: Alicia Cozine Date: Tue, 27 Mar 2018 14:59:04 -0500 Subject: [PATCH] revises network portion of 2.5 porting guide (#37938) * revises network portion of 2.5 porting guide --- .../rst/porting_guides/porting_guide_2.5.rst | 83 +++++++++++++------ 1 file changed, 59 insertions(+), 24 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst index b04d2638f0c..ee0adc4b0d3 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -199,12 +199,21 @@ Porting custom scripts No notable changes. -Networking -========== +Network +======= + +Expanding documentation +----------------------- + +We're expanding the network documentation. There's new content and a :ref:`new Ansible Network landing page`. We will continue to build the network-related documentation moving forward. +Top-level connection arguments will be removed in 2.9 +----------------------------------------------------- + +Top-level connection arguments like ``username``, ``host``, and ``password`` are deprecated and will be removed in version 2.9. + +**OLD** In Ansible < 2.4 -Change in deprecation notice of top-level connection arguments --------------------------------------------------------------- .. code-block:: yaml - name: example of using top-level options for connection properties @@ -216,36 +225,62 @@ Change in deprecation notice of top-level connection arguments authorize: yes auth_pass: cisco -**OLD** In Ansible 2.4: +The deprecation warnings reflect this schedule. The task above, run in Ansible 2.5, will result in: -Will result in: +.. code-block:: yaml + + [DEPRECATION WARNING]: Param 'username' is deprecated. See the module docs for more information. This feature will be removed in version + 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. + [DEPRECATION WARNING]: Param 'password' is deprecated. See the module docs for more information. This feature will be removed in version + 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. + [DEPRECATION WARNING]: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9. + Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. + +We recommend using the new connection types ``network_cli`` and ``netconf`` (see below), using standard Ansible connection properties, and setting those properties in inventory by group. As you update your playbooks and inventory files, you can easily make the change to ``become`` for privilege escalation (on platforms that support it). For more information, see the :ref:`using become with network modules` guide and the :ref:`platform documentation`. + +Adding persistent connection types ``network_cli`` and ``netconf`` +------------------------------------------------------------------ + +Ansible 2.5 introduces two top-level persistent connection types, ``network_cli`` and ``netconf``. With ``connection: local``, each task passed the connection parameters, which had to be stored in your playbooks. With ``network_cli`` and ``netconf`` the playbook passes the connection parameters once, so you can pass them at the command line if you prefer. We recommend you use ``network_cli`` and ``netconf`` whenever possible. +Note that eAPI and NX-API still require ``local`` connections with ``provider`` dictionaries. See the :ref:`platform documentation` for more information. Unless you need a ``local`` connection, update your playbooks to use ``network_cli`` or ``netconf`` and to specify your connection variables with standard Ansible connection variables: + +**OLD** In Ansible 2.4 .. code-block:: yaml - [WARNING]: argument username has been deprecated and will be removed in a future version - [WARNING]: argument host has been deprecated and will be removed in a future version - [WARNING]: argument password has been deprecated and will be removed in a future version + --- + vars: + cli: + host: "{{ inventory_hostname }}" + username: operator + password: secret + transport: cli + tasks: + - nxos_config: + src: config.j2 + provider: "{{ cli }}" + username: admin + password: admin -**NEW** In Ansible 2.5: +**NEW** In Ansible 2.5 + +.. code-block:: ini + [nxos:vars] + ansible_connection=network_cli + ansible_network_os=nxos + ansible_user=operator + ansible_password=secret .. code-block:: yaml - [DEPRECATION WARNING]: Param 'username' is deprecated. See the module docs for more information. This feature will be removed in version - 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. - [DEPRECATION WARNING]: Param 'password' is deprecated. See the module docs for more information. This feature will be removed in version - 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. - [DEPRECATION WARNING]: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9. - Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg. + tasks: + - nxos_config: + src: config.j2 -Notice when using provider dictionary with new persistent connection types --------------------------------------------------------------------------- +Using a provider dictionary with either ``network_cli`` or ``netconf`` will result in a warning. -Using a provider dictionary with one of the new persistent connection types for networking -(network_cli, netconf, etc.) will result in a warning. When using these connections -the standard Ansible infrastructure for controlling connections should be used. -(Link to basic inventory documentation?) Developers: Shared Module Utilities Moved ----------------------------------------- @@ -258,13 +293,13 @@ Beginning with Ansible 2.5, shared module utilities for network modules moved to If your module uses shared module utilities, you must update all references. For example, change: -OLD In Ansible 2.4 +**OLD** In Ansible 2.4 .. code-block:: python from ansible.module_utils.vyos import get_config, load_config -NEW In Ansible 2.5 +**NEW** In Ansible 2.5 .. code-block:: python