1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
.. _first_network_playbook:
***************************************************
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::
:local:
Prerequisites
==================================================
Before you work through this tutorial you need:
- 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
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.10):
.. code-block:: bash
ansible --version
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:
.. code-block:: bash
ssh my_vyos_user@vyos.example.net
show config
exit
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
==================================================
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 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)
- the inventory (-i, the device or devices to target - without the trailing comma -i points to an inventory file)
- 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, 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.
.. note::
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
==================================================
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: 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.vyos.vyos first_playbook.yml
The playbook contains one play with two tasks, and should generate output like this:
.. code-block:: shell
$ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook.yml
PLAY [Network Getting Started First Playbook]
***************************************************************************************************************************
TASK [Get config for VyOS devices]
***************************************************************************************************************************
ok: [vyos.example.net]
TASK [Display the config]
***************************************************************************************************************************
ok: [vyos.example.net] => {
"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:
.. literalinclude:: sample_files/first_playbook_ext.yml
:language: YAML
The extended first playbook has five tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:
.. code-block:: shell
$ ansible-playbook -i vyos.example.net, -u ansible -k -e ansible_network_os=vyos.vyos.vyos first_playbook_ext.yml
PLAY [Network Getting Started First Playbook Extended]
************************************************************************************************************************************
TASK [Get config for VyOS devices]
**********************************************************************************************************************************
ok: [vyos.example.net]
TASK [Display the config]
*************************************************************************************************************************************
ok: [vyos.example.net] => {
"msg": "The hostname is vyos and the OS is VyOS 1.1.8"
}
TASK [Update the hostname]
*************************************************************************************************************************************
changed: [vyos.example.net]
TASK [Get changed config for VyOS devices]
*************************************************************************************************************************************
ok: [vyos.example.net]
TASK [Display the changed config]
*************************************************************************************************************************************
ok: [vyos.example.net] => {
"msg": "The new hostname is vyos-changed and the OS is VyOS 1.1.8"
}
PLAY RECAP
************************************************************************************************************************************
vyos.example.net : ok=5 changed=1 unreachable=0 failed=0
.. _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:`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: interfaces
module_defaults:
arista.eos.eos_facts:
gather_network_resources: interfaces
The playbook returns the following interface facts:
.. code-block:: yaml
"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 <ansible_collections.arista.eos.eos_interfaces_module>` resource module.
|
