From 9922014441ce03124e767eb3ba89081c7f05ba12 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 10 Jan 2020 16:06:49 -0500 Subject: [PATCH] add details on network gather facts improvements (#66220) * add details on network gather facts improvements, implement feedback --- .../getting_started/first_inventory.rst | 2 +- .../getting_started/first_playbook.rst | 48 ++++++++++++++++++- .../rst/porting_guides/porting_guide_2.9.rst | 5 ++ 3 files changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index a963baa47e6..8119b822dfe 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -2,7 +2,7 @@ Build Your Inventory *********************************************** -A fully-featured inventory file can serve as the source of truth for your network. Using an inventory file, a single playbook can maintain hundreds of network devices with a single command. This page shows you how to build an inventory file, step by step. +Running a playbook without an inventory requires several command-line flags. Also, running a playbook against a single device is not a huge efficiency gain over making the same change manually. The next step to harnessing the full power of Ansible is to use an inventory file to organize your managed nodes into groups with information like the ``ansible_network_os`` and the SSH user. A fully-featured inventory file can serve as the source of truth for your network. Using an inventory file, a single playbook can maintain hundreds of network devices with a single command. This page shows you how to build an inventory file, step by step. .. contents:: Topics diff --git a/docs/docsite/rst/network/getting_started/first_playbook.rst b/docs/docsite/rst/network/getting_started/first_playbook.rst index 84b9b2ca815..677eaeb98ba 100644 --- a/docs/docsite/rst/network/getting_started/first_playbook.rst +++ b/docs/docsite/rst/network/getting_started/first_playbook.rst @@ -150,4 +150,50 @@ The extended first playbook has four tasks in a single play. Run it with the sam vyos.example.net : ok=6 changed=1 unreachable=0 failed=0 -This playbook is useful. However, running it still requires several command-line flags. Also, running a playbook against a single device is not a huge efficiency gain over making the same change manually. The next step to harnessing the full power of Ansible is to use an inventory file to organize your managed nodes into groups with information like the ``ansible_network_os`` and the SSH user. + +.. _network_gather_facts: + +Gathering facts from network devices +==================================== + +The ``gather_facts`` keyword now supports gathering network device facts in standardized key/value pairs. You can feed these network facts into further tasks to manage the network device. + +You can also use the new ``gather_network_resources`` parameter with the network ``*_facts`` modules (such as :ref:`eos_facts `) to return just a subset of the device configuration, as shown below. + +.. code-block:: yaml + + - hosts: arista + gather_facts: True + gather_subset: min + module_defaults: + eos_facts: + gather_network_resources: interfaces + +The playbook returns the following interface facts: + +.. code-block:: yaml + + ansible_facts: + ansible_network_resources: + interfaces: + - enabled: true + name: Ethernet1 + mtu: '1476' + - enabled: true + name: Loopback0 + - enabled: true + name: Loopback1 + - enabled: true + mtu: '1476' + name: Tunnel0 + - enabled: true + name: Ethernet1 + - enabled: true + name: Tunnel1 + - enabled: true + name: Ethernet1 + + +Note that this returns a subset of what is returned by just setting ``gather_subset: interfaces``. + +You can store these facts and use them directly in another task, such as with the :ref:`eos_interfaces ` resource module. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.9.rst b/docs/docsite/rst/porting_guides/porting_guide_2.9.rst index 7738fa0ec60..6e4b7152150 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.9.rst @@ -725,6 +725,11 @@ Network resource modules Ansible 2.9 introduced the first batch of network resource modules. Sections of a network device's configuration can be thought of as a resource provided by that device. Network resource modules are intentionally scoped to configure a single resource and you can combine them as building blocks to configure complex network services. The older modules are deprecated in Ansible 2.9 and will be removed in Ansible 2.13. You should scan the list of deprecated modules above and replace them with the new network resource modules in your playbooks. See `Ansible Network Features in 2.9 `_ for details. +Improved ``gather_facts`` support for network devices +----------------------------------------------------- + +In Ansible 2.9, the ``gather_facts`` keyword now supports gathering network device facts in standardized key/value pairs. You can feed these network facts into further tasks to manage the network device. You can also use the new ``gather_network_resources`` parameter with the network ``*_facts`` modules (such as :ref:`eos_facts `) to return just a subset of the device configuration. See :ref:`network_gather_facts` for an example. + Top-level connection arguments removed in 2.9 ---------------------------------------------