From f79a7c558574a44016d2ff978aaddf00f241a08c Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 18 Aug 2020 15:14:32 -0400 Subject: [PATCH] Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments --- docs/docsite/rst/network/dev_guide/index.rst | 2 +- .../getting_started/first_inventory.rst | 354 +++++++++++++----- .../getting_started/first_playbook.rst | 93 +++-- .../rst/network/getting_started/index.rst | 4 +- .../network_connection_options.rst | 4 +- .../getting_started/network_differences.rst | 71 +--- .../getting_started/network_resources.rst | 3 +- .../network/getting_started/network_roles.rst | 52 +-- .../sample_files/first_playbook.yml | 4 +- .../sample_files/first_playbook_ext.yml | 10 +- docs/docsite/rst/network/user_guide/index.rst | 2 +- .../rst/shared_snippets/basic_concepts.txt | 7 +- 12 files changed, 362 insertions(+), 244 deletions(-) diff --git a/docs/docsite/rst/network/dev_guide/index.rst b/docs/docsite/rst/network/dev_guide/index.rst index 4e6cef5bbca..5f0e7924ec0 100644 --- a/docs/docsite/rst/network/dev_guide/index.rst +++ b/docs/docsite/rst/network/dev_guide/index.rst @@ -1,7 +1,7 @@ .. _network_developer_guide: ********************************** -Network Automation Developer Guide +Network Developer Guide ********************************** Welcome to the Developer Guide for Ansible Network Automation! diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index 8119b822dfe..d3d1528efc0 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -4,9 +4,10 @@ Build Your Inventory 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 +.. contents:: + :local: -Basic Inventory +Basic inventory ================================================== First, group your inventory logically. Best practice is to group servers and network devices by their What (application, stack or microservice), Where (datacenter or region), and When (development stage): @@ -19,6 +20,45 @@ Avoid spaces, hyphens, and preceding numbers (use ``floor_19``, not ``19th_floor This tiny example data center illustrates a basic group structure. You can group groups using the syntax ``[metagroupname:children]`` and listing groups as members of the metagroup. Here, the group ``network`` includes all leafs and all spines; the group ``datacenter`` includes all network devices plus all webservers. +.. code-block:: yaml + + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + + datacenter: + children: + network: + webservers: + + + +You can also create this same inventory in INI format. + .. code-block:: ini [leafs] @@ -42,140 +82,270 @@ This tiny example data center illustrates a basic group structure. You can group webservers -Add Variables to Inventory +Add variables to the inventory ================================================================================ -Next, you can set values for many of the variables you needed in your first Ansible command in the inventory, so you can skip them in the ansible-playbook command. In this example, the inventory includes each network device's IP, OS, and SSH user. If your network devices are only accessible by IP, you must add the IP to the inventory file. If you access your network devices using hostnames, the IP is not necessary. - -.. code-block:: ini - - [leafs] - leaf01 ansible_host=10.16.10.11 ansible_network_os=vyos ansible_user=my_vyos_user - leaf02 ansible_host=10.16.10.12 ansible_network_os=vyos ansible_user=my_vyos_user - - [spines] - spine01 ansible_host=10.16.10.13 ansible_network_os=vyos ansible_user=my_vyos_user - spine02 ansible_host=10.16.10.14 ansible_network_os=vyos ansible_user=my_vyos_user - - [network:children] - leafs - spines +Next, you can set values for many of the variables you needed in your first Ansible command in the inventory, so you can skip them in the ``ansible-playbook`` command. In this example, the inventory includes each network device's IP, OS, and SSH user. If your network devices are only accessible by IP, you must add the IP to the inventory file. If you access your network devices using hostnames, the IP is not necessary. - [servers] - server01 ansible_host=10.16.10.15 ansible_user=my_server_user - server02 ansible_host=10.16.10.16 ansible_user=my_server_user - - [datacenter:children] - leafs - spines - servers +.. code-block:: yaml -Group Variables within Inventory + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + leaf02: + ansible_host: 10.16.10.12 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + spine02: + ansible_host: 10.16.10.14 + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user + + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + ansible_user: my_server_user + webserver02: + ansible_host: 10.16.10.16 + ansible_user: my_server_user + + datacenter: + children: + network: + webservers: + + +Group variables within inventory ================================================================================ When devices in a group share the same variable values, such as OS or SSH user, you can reduce duplication and simplify maintenance by consolidating these into group variables: -.. code-block:: ini - - [leafs] - leaf01 ansible_host=10.16.10.11 - leaf02 ansible_host=10.16.10.12 +.. code-block:: yaml - [leafs:vars] - ansible_network_os=vyos - ansible_user=my_vyos_user + --- - [spines] - spine01 ansible_host=10.16.10.13 - spine02 ansible_host=10.16.10.14 + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + vars: + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user - [spines:vars] - ansible_network_os=vyos - ansible_user=my_vyos_user + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + vars: + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user - [network:children] - leafs - spines + network: + children: + leafs: + spines: + + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + vars: + ansible_user: my_server_user - [servers] - server01 ansible_host=10.16.10.15 - server02 ansible_host=10.16.10.16 + datacenter: + children: + network: + webservers: - [datacenter:children] - leafs - spines - servers - -Variable Syntax +Variable syntax ================================================================================ -The syntax for variable values is different in inventory, in playbooks and in ``group_vars`` files, which are covered below. Even though playbook and ``group_vars`` files are both written in YAML, you use variables differently in each. +The syntax for variable values is different in inventory, in playbooks, and in the ``group_vars`` files, which are covered below. Even though playbook and ``group_vars`` files are both written in YAML, you use variables differently in each. -- In an ini-style inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos``. -- In any file with the ``.yml`` or ``.yaml`` extension, including playbooks and ``group_vars`` files, you **must** use YAML syntax: ``key: value`` +- In an ini-style inventory file you **must** use the syntax ``key=value`` for variable values: ``ansible_network_os=vyos.vyos.vyos``. +- In any file with the ``.yml`` or ``.yaml`` extension, including playbooks and ``group_vars`` files, you **must** use YAML syntax: ``key: value``. - - In ``group_vars`` files, use the full ``key`` name: ``ansible_network_os: vyos``. - - In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network_os: vyos`` +- In ``group_vars`` files, use the full ``key`` name: ``ansible_network_os: vyos.vyos.vyos``. +- In playbooks, use the short-form ``key`` name, which drops the ``ansible`` prefix: ``network_os: vyos.vyos.vyos``. -Group Inventory by Platform +Group inventory by platform ================================================================================ As your inventory grows, you may want to group devices by platform. This allows you to specify platform-specific variables easily for all devices on that platform: -.. code-block:: ini - - [vyos_leafs] - leaf01 ansible_host=10.16.10.11 - leaf02 ansible_host=10.16.10.12 - - [vyos_spines] - spine01 ansible_host=10.16.10.13 - spine02 ansible_host=10.16.10.14 +.. code-block:: yaml - [vyos:children] - vyos_leafs - vyos_spines + --- + + leafs: + hosts: + leaf01: + ansible_host: 10.16.10.11 + leaf02: + ansible_host: 10.16.10.12 + + spines: + hosts: + spine01: + ansible_host: 10.16.10.13 + spine02: + ansible_host: 10.16.10.14 + + network: + children: + leafs: + spines: + vars: + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos + ansible_user: my_vyos_user - [vyos:vars] - ansible_connection=network_cli - ansible_network_os=vyos - ansible_user=my_vyos_user + webservers: + hosts: + webserver01: + ansible_host: 10.16.10.15 + webserver02: + ansible_host: 10.16.10.16 + vars: + ansible_user: my_server_user - [network:children] - vyos + datacenter: + children: + network: + webservers: - [servers] - server01 ansible_host=10.16.10.15 - server02 ansible_host=10.16.10.16 +With this setup, you can run ``first_playbook.yml`` with only two flags: - [datacenter:children] - vyos - servers +.. code-block:: console -With this setup, you can run first_playbook.yml with only two flags: + ansible-playbook -i inventory.yml -k first_playbook.yml -.. code-block:: console +With the ``-k`` flag, you provide the SSH password(s) at the prompt. Alternatively, you can store SSH and other secrets and passwords securely in your group_vars files with ``ansible-vault``. See :ref:`network_vault` for details. - ansible-playbook -i inventory -k first_playbook.yml +Verifying the inventory +========================= -With the ``-k`` flag, you provide the SSH password(s) at the prompt. Alternatively, you can store SSH and other secrets and passwords securely in your group_vars files with ``ansible-vault``. +You can use the :ref:`ansible-inventory` CLI command to display the inventory as Ansible sees it. +.. code-block:: console -Protecting Sensitive Variables with ``ansible-vault`` + $ ansible-inventory -i test.yml --list + { + "_meta": { + "hostvars": { + "leaf01": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.11", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "leaf02": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.12", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "spine01": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.13", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "spine02": { + "ansible_connection": "ansible.netcommon.network_cli", + "ansible_host": "10.16.10.14", + "ansible_network_os": "vyos.vyos.vyos", + "ansible_user": "my_vyos_user" + }, + "webserver01": { + "ansible_host": "10.16.10.15", + "ansible_user": "my_server_user" + }, + "webserver02": { + "ansible_host": "10.16.10.16", + "ansible_user": "my_server_user" + } + } + }, + "all": { + "children": [ + "datacenter", + "ungrouped" + ] + }, + "datacenter": { + "children": [ + "network", + "webservers" + ] + }, + "leafs": { + "hosts": [ + "leaf01", + "leaf02" + ] + }, + "network": { + "children": [ + "leafs", + "spines" + ] + }, + "spines": { + "hosts": [ + "spine01", + "spine02" + ] + }, + "webservers": { + "hosts": [ + "webserver01", + "webserver02" + ] + } + } + +.. _network_vault: + +Protecting sensitive variables with ``ansible-vault`` ================================================================================ The ``ansible-vault`` command provides encryption for files and/or individual variables like passwords. This tutorial will show you how to encrypt a single SSH password. You can use the commands below to encrypt other sensitive information, such as database passwords, privilege-escalation passwords and more. First you must create a password for ansible-vault itself. It is used as the encryption key, and with this you can encrypt dozens of different passwords across your Ansible project. You can access all those secrets (encrypted values) with a single password (the ansible-vault password) when you run your playbooks. Here's a simple example. -Create a file and write your password for ansible-vault to it: +1. Create a file and write your password for ansible-vault to it: .. code-block:: console echo "my-ansible-vault-pw" > ~/my-ansible-vault-pw-file -Create the encrypted ssh password for your VyOS network devices, pulling your ansible-vault password from the file you just created: +2. Create the encrypted ssh password for your VyOS network devices, pulling your ansible-vault password from the file you just created: .. code-block:: console @@ -210,8 +380,8 @@ This is an example using an extract from a YAML inventory, as the INI format do vyos: # this is a group in yaml inventory, but you can also do under a host vars: - ansible_connection: network_cli - ansible_network_os: vyos + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: vyos.vyos.vyos ansible_user: my_vyos_user ansible_password: !vault | $ANSIBLE_VAULT;1.2;AES256;my_user diff --git a/docs/docsite/rst/network/getting_started/first_playbook.rst b/docs/docsite/rst/network/getting_started/first_playbook.rst index 677eaeb98ba..b09814cd64c 100644 --- a/docs/docsite/rst/network/getting_started/first_playbook.rst +++ b/docs/docsite/rst/network/getting_started/first_playbook.rst @@ -7,14 +7,15 @@ Run Your First Command and Playbook Put the concepts you learned to work with this quick tutorial. Install Ansible, execute a network configuration command manually, execute the same command with Ansible, then create a playbook so you can execute the command any time on multiple network devices. -.. contents:: Topics +.. contents:: + :local: Prerequisites ================================================== Before you work through this tutorial you need: -- Ansible 2.5 (or higher) installed +- Ansible 2.10 (or higher) installed - One or more network devices that are compatible with Ansible - Basic Linux command line knowledge - Basic knowledge of network switch & router configuration @@ -24,14 +25,14 @@ Install Ansible Install Ansible using your preferred method. See :ref:`installation_guide`. Then return to this tutorial. -Confirm the version of Ansible (must be >= 2.5): +Confirm the version of Ansible (must be >= 2.10): .. code-block:: bash ansible --version -Establish a Manual Connection to a Managed Node +Establish a manual connection to a managed node ================================================== To confirm your credentials, connect to a network device manually and retrieve its configuration. Replace the sample user and device name with your real credentials. For example, for a VyOS router: @@ -45,14 +46,14 @@ To confirm your credentials, connect to a network device manually and retrieve i This manual connection also establishes the authenticity of the network device, adding its RSA key fingerprint to your list of known hosts. (If you have connected to the device before, you have already established its authenticity.) -Run Your First Network Ansible Command +Run your first network Ansible command ================================================== Instead of manually connecting and running a command on the network device, you can retrieve its configuration with a single, stripped-down Ansible command: .. code-block:: bash - ansible all -i vyos.example.net, -c network_cli -u my_vyos_user -k -m vyos_facts -e ansible_network_os=vyos + ansible all -i vyos.example.net, -c ansible.netcommon.network_cli -u my_vyos_user -k -m vyos.vyos.vyos_facts -e ansible_network_os=vyos.vyos.vyos The flags in this command set seven values: - the host group(s) to which the command should apply (in this case, all) @@ -60,7 +61,7 @@ The flags in this command set seven values: - the connection method (-c, the method for connecting and executing ansible) - the user (-u, the username for the SSH connection) - the SSH connection method (-k, please prompt for the password) - - the module (-m, the ansible module to run) + - the module (-m, the Ansible module to run, using the fully qualified collection name (FQCN)) - an extra variable ( -e, in this case, setting the network OS value) NOTE: If you use ``ssh-agent`` with ssh keys, Ansible loads them automatically. You can omit ``-k`` flag. @@ -70,29 +71,29 @@ NOTE: If you use ``ssh-agent`` with ssh keys, Ansible loads them automatically. If you are running Ansible in a virtual environment, you will also need to add the variable ``ansible_python_interpreter=/path/to/venv/bin/python`` -Create and Run Your First Network Ansible Playbook +Create and run your first network Ansible Playbook ================================================== -If you want to run this command every day, you can save it in a playbook and run it with ansible-playbook instead of ansible. The playbook can store a lot of the parameters you provided with flags at the command line, leaving less to type at the command line. You need two files for this - a playbook and an inventory file. +If you want to run this command every day, you can save it in a playbook and run it with ``ansible-playbook`` instead of ``ansible``. The playbook can store a lot of the parameters you provided with flags at the command line, leaving less to type at the command line. You need two files for this - a playbook and an inventory file. 1. Download :download:`first_playbook.yml `, which looks like this: .. literalinclude:: sample_files/first_playbook.yml :language: YAML -The playbook sets three of the seven values from the command line above: the group (``hosts: all``), the connection method (``connection: network_cli``) and the module (in each task). With those values set in the playbook, you can omit them on the command line. The playbook also adds a second task to show the config output. When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. The debug task here lets you see the results in your shell. +The playbook sets three of the seven values from the command line above: the group (``hosts: all``), the connection method (``connection: ansible.netcommon.network_cli``) and the module (in each task). With those values set in the playbook, you can omit them on the command line. The playbook also adds a second task to show the config output. When a module runs in a playbook, the output is held in memory for use by future tasks instead of written to the console. The debug task here lets you see the results in your shell. 2. Run the playbook with the command: .. code-block:: bash - ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook.yml + ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml The playbook contains one play with two tasks, and should generate output like this: .. code-block:: bash - $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook.yml + $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml PLAY [First Playbook] *************************************************************************************************************************** @@ -104,7 +105,7 @@ The playbook contains one play with two tasks, and should generate output like t TASK [Display the config] *************************************************************************************************************************** ok: [vyos.example.net] => { - "msg": "The hostname is vyos and the OS is VyOS" + "msg": "The hostname is vyos and the OS is VyOS 1.1.8" } 3. Now that you can retrieve the device config, try updating it with Ansible. Download :download:`first_playbook_ext.yml `, which is an extended version of the first playbook: @@ -116,7 +117,7 @@ The extended first playbook has four tasks in a single play. Run it with the sam .. code-block:: bash - $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos first_playbook_ext.yml + $ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook_ext.yml PLAY [First Playbook] ************************************************************************************************************************************ @@ -128,7 +129,7 @@ The extended first playbook has four tasks in a single play. Run it with the sam TASK [Display the config] ************************************************************************************************************************************* ok: [vyos.example.net] => { - "msg": "The hostname is vyos and the OS is VyOS" + "msg": "The hostname is vyos and the OS is VyOS 1.1.8" } TASK [Update the hostname] @@ -142,12 +143,12 @@ The extended first playbook has four tasks in a single play. Run it with the sam TASK [Display the changed config] ************************************************************************************************************************************* ok: [vyos.example.net] => { - "msg": "The hostname is vyos-changed and the OS is VyOS" + "msg": "The new hostname is vyos-changed and the OS is VyOS 1.1.8" } PLAY RECAP ************************************************************************************************************************************ - vyos.example.net : ok=6 changed=1 unreachable=0 failed=0 + vyos.example.net : ok=5 changed=1 unreachable=0 failed=0 @@ -158,42 +159,54 @@ 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. +You can also use the new ``gather_network_resources`` parameter with the network ``*_facts`` modules (such as :ref:`arista.eos.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 + gather_subset: interfaces module_defaults: - eos_facts: + arista.eos.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 + "network_resources": { + "interfaces": [ + { + "description": "test-interface", + "enabled": true, + "mtu": "512", + "name": "Ethernet1" + }, + { + "enabled": true, + "mtu": "3000", + "name": "Ethernet2" + }, + { + "enabled": true, + "name": "Ethernet3" + }, + { + "enabled": true, + "name": "Ethernet4" + }, + { + "enabled": true, + "name": "Ethernet5" + }, + { + "enabled": true, + "name": "Ethernet6" + }, + ] + } 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. +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/network/getting_started/index.rst b/docs/docsite/rst/network/getting_started/index.rst index c491ed1a398..d9638a5c9a6 100644 --- a/docs/docsite/rst/network/getting_started/index.rst +++ b/docs/docsite/rst/network/getting_started/index.rst @@ -1,10 +1,10 @@ .. _network_getting_started: ********************************** -Network Automation Getting Started +Network Getting Started ********************************** -Ansible modules support a wide range of vendors, device types, and actions, so you can manage your entire network with a single automation tool. With Ansible, you can: +Ansible collections support a wide range of vendors, device types, and actions, so you can manage your entire network with a single automation tool. With Ansible, you can: - Automate repetitive tasks to speed routine network changes and free up your time for more strategic work - Leverage the same simple, powerful, and agentless automation tool for network tasks that operations and development use diff --git a/docs/docsite/rst/network/getting_started/network_connection_options.rst b/docs/docsite/rst/network/getting_started/network_connection_options.rst index 2ae0b1aa470..c23e7307a9d 100644 --- a/docs/docsite/rst/network/getting_started/network_connection_options.rst +++ b/docs/docsite/rst/network/getting_started/network_connection_options.rst @@ -4,7 +4,7 @@ Working with network connection options *************************************** -Network modules can support multiple connection protocols, such as ``network_cli``, ``netconf``, and ``httpapi``. These connections include some common options you can set to control how the connection to your network device behaves. +Network modules can support multiple connection protocols, such as ``ansible.netcommon.network_cli``, ``ansible.netcommon.netconf``, and ``ansible.netcommon.httpapi``. These connections include some common options you can set to control how the connection to your network device behaves. Common options are: @@ -27,7 +27,7 @@ Using vars (per task): .. code-block:: yaml - name: save running-config - ios_command: + cisco.ios.ios_command: commands: copy running-config startup-config vars: ansible_command_timeout: 30 diff --git a/docs/docsite/rst/network/getting_started/network_differences.rst b/docs/docsite/rst/network/getting_started/network_differences.rst index a3b380203ef..76b18aa424f 100644 --- a/docs/docsite/rst/network/getting_started/network_differences.rst +++ b/docs/docsite/rst/network/getting_started/network_differences.rst @@ -4,16 +4,17 @@ How Network Automation is Different Network automation leverages the basic Ansible concepts, but there are important differences in how the network modules work. This introduction prepares you to understand the exercises in this guide. -.. contents:: Topics +.. contents:: + :local: -Execution on the Control Node +Execution on the control node ================================================================================ Unlike most Ansible modules, network modules do not run on the managed nodes. From a user's point of view, network modules work like any other modules. They work with ad-hoc commands, playbooks, and roles. Behind the scenes, however, network modules use a different methodology than the other (Linux/Unix and Windows) modules use. Ansible is written and executed in Python. Because the majority of network devices can not run Python, the Ansible network modules are executed on the Ansible control node, where ``ansible`` or ``ansible-playbook`` runs. Network modules also use the control node as a destination for backup files, for those modules that offer a ``backup`` option. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, usually in the `backup` directory under the playbook root directory. -Multiple Communication Protocols +Multiple communication protocols ================================================================================ Because network modules execute on the control node instead of on the managed nodes, they can support multiple communication protocols. The communication protocol (XML over SSH, CLI over SSH, API over HTTPS) selected for each network module depends on the platform and the purpose of the module. Some network modules support only one protocol; some offer a choice. The most common protocol is CLI over SSH. You set the communication protocol with the ``ansible_connection`` variable: @@ -22,26 +23,26 @@ Because network modules execute on the control node instead of on the managed no :header: "Value of ansible_connection", "Protocol", "Requires", "Persistent?" :widths: 30, 10, 10, 10 - "network_cli", "CLI over SSH", "network_os setting", "yes" - "netconf", "XML over SSH", "network_os setting", "yes" - "httpapi", "API over HTTP/HTTPS", "network_os setting", "yes" + "ansible.netcommon.network_cli", "CLI over SSH", "network_os setting", "yes" + "ansible.netcommon.netconf", "XML over SSH", "network_os setting", "yes" + "ansible.netcommon.httpapi", "API over HTTP/HTTPS", "network_os setting", "yes" "local", "depends on provider", "provider setting", "no" .. note:: - ``httpapi`` deprecates ``eos_eapi`` and ``nxos_nxapi``. See :ref:`httpapi_plugins` for details and an example. + ``ansible.netcommon.httpapi`` deprecates ``eos_eapi`` and ``nxos_nxapi``. See :ref:`httpapi_plugins` for details and an example. -Beginning with Ansible 2.6, we recommend using one of the persistent connection types listed above instead of ``local``. With persistent connections, you can define the hosts and credentials only once, rather than in every task. You also need to set the ``network_os`` variable for the specific network platform you are communicating with. For more details on using each connection type on various platforms, see the :ref:`platform-specific ` pages. +The ``ansible_connection: local`` has been deprecated. Please use one of the persistent connection types listed above instead. With persistent connections, you can define the hosts and credentials only once, rather than in every task. You also need to set the ``network_os`` variable for the specific network platform you are communicating with. For more details on using each connection type on various platforms, see the :ref:`platform-specific ` pages. -Modules Organized by Network Platform +Collections organized by network platform ================================================================================ -A network platform is a set of network devices with a common operating system that can be managed by a collection of modules. The modules for each network platform share a prefix, for example: +A network platform is a set of network devices with a common operating system that can be managed by an Ansible collection, for example: -- Arista: ``eos_`` -- Cisco: ``ios_``, ``iosxr_``, ``nxos_`` -- Juniper: ``junos_`` -- VyOS ``vyos_`` +- Arista: `arista.eos `_ +- Cisco: `cisco.ios `_, `cisco.iosxr `_, `cisco.nxos `_ +- Juniper: `junipernetworks.junos `_ +- VyOS `vyos.vyos `_ All modules within a network platform share certain requirements. Some network platforms have specific differences - see the :ref:`platform-specific ` documentation for details. @@ -50,52 +51,18 @@ All modules within a network platform share certain requirements. Some network p Privilege Escalation: ``enable`` mode, ``become``, and ``authorize`` ================================================================================ -Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. On network devices this is called ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. For details of which platforms support ``enable`` mode, with examples of how to use it, see the :ref:`platform-specific ` documentation. +Several network platforms support privilege escalation, where certain tasks must be done by a privileged user. On network devices this is called the ``enable`` mode (the equivalent of ``sudo`` in \*nix administration). Ansible network modules offer privilege escalation for those network devices that support it. For details of which platforms support ``enable`` mode, with examples of how to use it, see the :ref:`platform-specific ` documentation. Using ``become`` for privilege escalation ----------------------------------------- -As of Ansible 2.6, you can use the top-level Ansible parameter ``become: yes`` with ``become_method: enable`` to run a task, play, or playbook with escalated privileges on any network platform that supports privilege escalation. You must use either ``connection: network_cli`` or ``connection: httpapi`` with ``become: yes`` with ``become_method: enable``. If you are using ``network_cli`` to connect Ansible to your network devices, a ``group_vars`` file would look like: +Use the top-level Ansible parameter ``become: yes`` with ``become_method: enable`` to run a task, play, or playbook with escalated privileges on any network platform that supports privilege escalation. You must use either ``connection: network_cli`` or ``connection: httpapi`` with ``become: yes`` with ``become_method: enable``. If you are using ``network_cli`` to connect Ansible to your network devices, a ``group_vars`` file would look like: .. code-block:: yaml - ansible_connection: network_cli - ansible_network_os: ios + ansible_connection: ansible.netcommon.network_cli + ansible_network_os: cisco.ios.ios ansible_become: yes ansible_become_method: enable -Legacy playbooks: ``authorize`` for privilege escalation ------------------------------------------------------------------ - -If you are running Ansible 2.5 or older, some network platforms support privilege escalation but not ``network_cli`` or ``httpapi`` connections. This includes all platforms in versions 2.4 and older, and HTTPS connections using ``eapi`` in version 2.5. With a ``local`` connection, you must use a ``provider`` dictionary and include ``authorize: yes`` and ``auth_pass: my_enable_password``. For that use case, a ``group_vars`` file looks like: - -.. code-block:: yaml - - ansible_connection: local - ansible_network_os: eos - # provider settings - eapi: - authorize: yes - auth_pass: " {{ secret_auth_pass }}" - port: 80 - transport: eapi - use_ssl: no - -And you use the ``eapi`` variable in your task(s): - -.. code-block:: yaml - - tasks: - - name: provider demo with eos - eos_banner: - banner: motd - text: | - this is test - of multiline - string - state: present - provider: "{{ eapi }}" - -Note that while Ansible 2.6 supports the use of ``connection: local`` with ``provider`` dictionaries, this usage will be deprecated in the future and eventually removed. - For more information, see :ref:`Become and Networks` diff --git a/docs/docsite/rst/network/getting_started/network_resources.rst b/docs/docsite/rst/network/getting_started/network_resources.rst index c0fbd7b2a9c..3451c476da7 100644 --- a/docs/docsite/rst/network/getting_started/network_resources.rst +++ b/docs/docsite/rst/network/getting_started/network_resources.rst @@ -32,9 +32,8 @@ Ansible hosts module code, examples, demonstrations, and other content on GitHub - `Network-Automation `_ is an open community for all things network automation. Have an idea, some playbooks, or roles to share? Email ansible-network@redhat.com and we will add you as a contributor to the repository. -- `Ansible `_ is the main codebase, including code for network modules +- `Ansible collections `_ is the main repository for Ansible-maintained and community collections, including collections for network devices. -- `ansible-network `_ is the main codebase for the Ansible network team roles IRC and Slack diff --git a/docs/docsite/rst/network/getting_started/network_roles.rst b/docs/docsite/rst/network/getting_started/network_roles.rst index a0e4b8d8490..b77d06119ac 100644 --- a/docs/docsite/rst/network/getting_started/network_roles.rst +++ b/docs/docsite/rst/network/getting_started/network_roles.rst @@ -27,18 +27,18 @@ To demonstrate the concept of what a role is, the example ``playbook.yml`` below --- - name: configure cisco routers hosts: routers - connection: network_cli + connection: ansible.netcommon.network_cli gather_facts: no vars: dns: "8.8.8.8 8.8.4.4" tasks: - name: configure hostname - ios_config: + cisco.ios.ios_config: lines: hostname {{ inventory_hostname }} - name: configure DNS - ios_config: + cisco.ios.ios_config: lines: ip name-server {{dns}} If you run this playbook using the ``ansible-playbook`` command, you'll see the output below. This example used ``-l`` option to limit the playbook to only executing on the **rtr1** node. @@ -113,11 +113,11 @@ Next, move the content of the ``vars`` and ``tasks`` sections from the original [user@ansible system-demo]$ cat tasks/main.yml --- - name: configure hostname - ios_config: + cisco.ios.ios_config: lines: hostname {{ inventory_hostname }} - name: configure DNS - ios_config: + cisco.ios.ios_config: lines: ip name-server {{dns}} Next, move the variables into the ``vars/main.yml`` file: @@ -135,7 +135,7 @@ Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars --- - name: configure cisco routers hosts: routers - connection: network_cli + connection: ansible.netcommon.network_cli gather_facts: no roles: @@ -211,7 +211,7 @@ Add a new ``vars`` section to the playbook to override the default behavior (whe --- - name: configure cisco routers hosts: routers - connection: network_cli + connection: ansible.netcommon.network_cli gather_facts: no vars: dns: 1.1.1.1 @@ -252,39 +252,6 @@ The result on the Cisco IOS XE router will only contain the highest precedence s How is this useful? Why should you care? Extra vars are commonly used by network operators to override defaults. A powerful example of this is with Red Hat Ansible Tower and the Survey feature. It is possible through the web UI to prompt a network operator to fill out parameters with a Web form. This can be really simple for non-technical playbook writers to execute a playbook using their Web browser. See `Ansible Tower Job Template Surveys `_ for more details. -Ansible supported network roles -=============================== - -The Ansible Network team develops and supports a set of `network-related roles `_ on Ansible Galaxy. You can use these roles to jump start your network automation efforts. These roles are updated approximately every two weeks to give you access to the latest Ansible networking content. - -These roles come in the following categories: - -* **User roles** - User roles focus on tasks, such as managing your configuration. Use these roles, such as `config_manager `_ and `cloud_vpn `_, directly in your playbooks. These roles are platform/provider agnostic, allowing you to use the same roles and playbooks across different network platforms or cloud providers. -* **Platform provider roles** - Provider roles translate between the user roles and the various network OSs, each of which has a different API. Each provider role accepts input from a supported user role and translates it for a specific network OS. Network user roles depend on these provider roles to implement their functions. For example, the `config_manager `_ user role uses the `cisco_ios `_ provider role to implement tasks on Cisco IOS network devices. -* **Cloud provider and provisioner roles** - Similarly, cloud user roles depend on cloud provider and provisioner roles to implement cloud functions for specific cloud providers. For example, the `cloud_vpn `_ role depends on the `aws `_ provider role to communicate with AWS. - - -You need to install at least one platform provider role for your network user roles, and set ``ansible_network_provider`` to that provider (for example, ``ansible_network_provider: ansible-network.cisco_ios``). Ansible Galaxy automatically installs any other dependencies listed in the role details on Ansible Galaxy. - -For example, to use the ``config_manager`` role with Cisco IOS devices, you would use the following commands: - -.. code-block:: bash - - [user@ansible]$ ansible-galaxy install ansible-network.cisco_ios - [user@ansible]$ ansible-galaxy install ansible-network.config_manager - -Roles are fully documented with examples in Ansible Galaxy on the **Read Me** tab for each role. - -Network roles release cycle -=========================== - -The Ansible network team releases updates and new roles every two weeks. The role details on Ansible Galaxy lists the role versions available, and you can look in the GitHub repository to find the changelog file (for example, the ``cisco_ios`` `CHANGELOG.rst `_ ) that lists what has changed in each version of the role. - -The Ansible Galaxy role version has two components: - -* Major release number - (for example, 2.6) which shows the Ansible engine version this role supports. -* Minor release number (for example .1) which denotes the role release cycle and does not reflect the Ansible engine minor release version. - Update an installed role ------------------------ @@ -292,12 +259,9 @@ The Ansible Galaxy page for a role lists all available versions. To update a loc .. code-block:: bash - [user@ansible]$ ansible-galaxy install ansible-network.network_engine,v2.7.0 --force - [user@ansible]$ ansible-galaxy install ansible-network.cisco_nxos,v2.7.1 --force + [user@ansible]$ ansible-galaxy install mynamespace.my_role,v2.7.1 --force .. seealso:: `Ansible Galaxy documentation `_ Ansible Galaxy user guide - `Ansible supported network roles `_ - List of Ansible-supported network and cloud roles on Ansible Galaxy diff --git a/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml b/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml index 32f3195e15e..908b89f9ae3 100644 --- a/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml +++ b/docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml @@ -1,13 +1,13 @@ --- - name: Network Getting Started First Playbook - connection: network_cli + connection: ansible.netcommon.network_cli gather_facts: false hosts: all tasks: - name: Get config for VyOS devices - vyos_facts: + vyos.vyos.vyos_facts: gather_subset: all - name: Display the config diff --git a/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml b/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml index 8731947ab91..2d5f6a5f1f1 100644 --- a/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml +++ b/docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml @@ -1,13 +1,13 @@ --- - name: Network Getting Started First Playbook Extended - connection: network_cli + connection: ansible.netcommon.network_cli gather_facts: false hosts: all tasks: - name: Get config for VyOS devices - vyos_facts: + vyos.vyos.vyos_facts: gather_subset: all - name: Display the config @@ -15,15 +15,15 @@ msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" - name: Update the hostname - vyos_config: + vyos.vyos.vyos_config: backup: yes lines: - set system host-name vyos-changed - name: Get changed config for VyOS devices - vyos_facts: + vyos.vyos.vyos_facts: gather_subset: all - name: Display the changed config debug: - msg: "The hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" + msg: "The new hostname is {{ ansible_net_hostname }} and the OS is {{ ansible_net_version }}" diff --git a/docs/docsite/rst/network/user_guide/index.rst b/docs/docsite/rst/network/user_guide/index.rst index fc51281fd42..628b194d26e 100644 --- a/docs/docsite/rst/network/user_guide/index.rst +++ b/docs/docsite/rst/network/user_guide/index.rst @@ -1,7 +1,7 @@ .. _network_advanced: ********************************** -Network Automation Advanced Topics +Network Advanced Topics ********************************** Once you have mastered the basics of network automation with Ansible, as presented in :ref:`network_getting_started`, use this guide understand platform-specific details, optimization, and troubleshooting tips for Ansible for network automation. diff --git a/docs/docsite/rst/shared_snippets/basic_concepts.txt b/docs/docsite/rst/shared_snippets/basic_concepts.txt index db490ecbfd7..e10e2d4f2cf 100644 --- a/docs/docsite/rst/shared_snippets/basic_concepts.txt +++ b/docs/docsite/rst/shared_snippets/basic_concepts.txt @@ -13,10 +13,15 @@ Inventory A list of managed nodes. An inventory file is also sometimes called a "hostfile". Your inventory can specify information like IP address for each managed node. An inventory can also organize managed nodes, creating and nesting groups for easier scaling. To learn more about inventory, see :ref:`the Working with Inventory` section. +Collections +=========== + +Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. You can install and use collections through `Ansible Galaxy `_. To learn more about collections, see :ref:`collections`. + Modules ======= -The units of code Ansible executes. Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of all modules `. +The units of code Ansible executes. Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device. You can invoke a single module with a task, or invoke several different modules in a playbook. Starting in Ansible 2.10, modules are grouped in collections. For an idea of how many collections Ansible includes, take a look at the :ref:`list_of_collections`. Tasks =====