cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update Network Getting Started for FQCN/collection world (#71188)

Browse source 
* 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
This commit is contained in:
Sandra McCann 2020-08-18 15:14:32 -04:00 committed by GitHub
parent 5073cfc8bc
commit f79a7c5585
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 354 additions and 236 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docsite/rst/network/dev_guide/index.rst
View file

@ -1,7 +1,7 @@
.. _network_developer_guide:
**********************************
Network Automation Developer Guide
Network Developer Guide
**********************************
Welcome to the Developer Guide for Ansible Network Automation!

338
docs/docsite/rst/network/getting_started/first_inventory.rst
View file

@ -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.
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
.. code-block:: yaml
[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
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
[network:children]
leafs
spines
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
[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
network:
children:
leafs:
spines:
[datacenter:children]
leafs
spines
servers
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
Group Variables within Inventory
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
.. code-block:: yaml
[leafs]
leaf01 ansible_host=10.16.10.11
leaf02 ansible_host=10.16.10.12
---
[leafs:vars]
ansible_network_os=vyos
ansible_user=my_vyos_user
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]
spine01 ansible_host=10.16.10.13
spine02 ansible_host=10.16.10.14
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
[spines:vars]
ansible_network_os=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
.. code-block:: yaml
[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
leafs:
hosts:
leaf01:
ansible_host: 10.16.10.11
leaf02:
ansible_host: 10.16.10.12
[vyos:children]
vyos_leafs
vyos_spines
spines:
hosts:
spine01:
ansible_host: 10.16.10.13
spine02:
ansible_host: 10.16.10.14
[vyos:vars]
ansible_connection=network_cli
ansible_network_os=vyos
ansible_user=my_vyos_user
network:
children:
leafs:
spines:
vars:
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: vyos.vyos.vyos
ansible_user: my_vyos_user
[network:children]
vyos
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]
vyos
servers
With this setup, you can run first_playbook.yml with only two flags:
With this setup, you can run ``first_playbook.yml`` with only two flags:
.. code-block:: console
ansible-playbook -i inventory -k first_playbook.yml
ansible-playbook -i inventory.yml -k first_playbook.yml
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``.
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.
Verifying the inventory
=========================
Protecting Sensitive Variables with ``ansible-vault``
You can use the :ref:`ansible-inventory` CLI command to display the inventory as Ansible sees it.
.. code-block:: console
$ 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

93
docs/docsite/rst/network/getting_started/first_playbook.rst
View file

@ -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 <sample_files/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 <sample_files/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 <eos_facts_module>`) 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 <ansible_collections.arista.eos.eos_facts_module>`) 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 <eos_interfaces_module>` resource module.
You can store these facts and use them directly in another task, such as with the :ref:`eos_interfaces <ansible_collections.arista.eos.eos_interfaces_module>` resource module.

4
docs/docsite/rst/network/getting_started/index.rst
View file

@ -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

4
docs/docsite/rst/network/getting_started/network_connection_options.rst
View file

@ -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

71
docs/docsite/rst/network/getting_started/network_differences.rst
View file

@ -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 <platform_options>` 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 <platform_options>` 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 <https://galaxy.ansible.com/arista/eos>`_
- Cisco: `cisco.ios <https://galaxy.ansible.com/cisco/ios>`_, `cisco.iosxr <https://galaxy.ansible.com/cisco/iosxr>`_, `cisco.nxos <https://galaxy.ansible.com/cisco/nxos>`_
- Juniper: `junipernetworks.junos <https://galaxy.ansible.com/junipernetworks/junos>`_
- VyOS `vyos.vyos <https://galaxy.ansible.com/vyos/vyos>`_
All modules within a network platform share certain requirements. Some network platforms have specific differences - see the :ref:`platform-specific <platform_options>` 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 <platform_options>` 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 <platform_options>` 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<become_network>`

3
docs/docsite/rst/network/getting_started/network_resources.rst
View file

@ -32,9 +32,8 @@ Ansible hosts module code, examples, demonstrations, and other content on GitHub
- `Network-Automation <https://github.com/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 <https://github.com/ansible/ansible>`_ is the main codebase, including code for network modules
- `Ansible collections <https://github.com/ansible-collections>`_ is the main repository for Ansible-maintained and community collections, including collections for network devices.
- `ansible-network <https://github.com/ansible-network>`_ is the main codebase for the Ansible network team roles
IRC and Slack

52
docs/docsite/rst/network/getting_started/network_roles.rst
View file

@ -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 <https://docs.ansible.com/ansible-tower/latest/html/userguide/workflow_templates.html#surveys>`_ for more details.
Ansible supported network roles
===============================
The Ansible Network team develops and supports a set of `network-related roles <https://galaxy.ansible.com/ansible-network>`_ 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 <https://galaxy.ansible.com/ansible-network/config_manager>`_ and `cloud_vpn <https://galaxy.ansible.com/ansible-network/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 <https://galaxy.ansible.com/ansible-network/config_manager>`_ user role uses the `cisco_ios <https://galaxy.ansible.com/ansible-network/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 <https://galaxy.ansible.com/ansible-network/cloud_vpn>`_ role depends on the `aws <https://galaxy.ansible.com/ansible-network/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 <https://github.com/ansible-network/cisco_ios/blob/devel/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 <https://galaxy.ansible.com/docs/>`_
Ansible Galaxy user guide
`Ansible supported network roles <https://galaxy.ansible.com/ansible-network>`_
List of Ansible-supported network and cloud roles on Ansible Galaxy

4
docs/docsite/rst/network/getting_started/sample_files/first_playbook.yml
View file

@ -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

10
docs/docsite/rst/network/getting_started/sample_files/first_playbook_ext.yml
View file

@ -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 }}"

2
docs/docsite/rst/network/user_guide/index.rst
View file

@ -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.

7
docs/docsite/rst/shared_snippets/basic_concepts.txt
View file

@ -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<intro_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 <https://galaxy.ansible.com>`_. 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 <modules_by_category>`.
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
=====