An ``inventory`` file is an INI-like configuration file that defines the mapping of hosts into groups.
In our example, the inventory file defines the groups ``eos``, ``ios``, ``vyos`` and a "group of groups" called ``switches``. Further details about subgroups and inventory files can be found in the :ref:`Ansible inventory Group documentation <subgroups>`.
In our example, the inventory file defines the groups ``eos``, ``ios``, ``vyos`` and a "group of groups" called ``switches``. Further details about subgroups and inventory files can be found in the :ref:`Ansible inventory Group documentation <subgroups>`.
Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using the ``[my_group:vars]`` capability in your inventory file. Here's what it would look like if you specified your ssh passwords (encrypted with Ansible Vault) among your variables:
Because Ansible is a flexible tool, there are a number of ways to specify connection information and credentials. We recommend using the ``[my_group:vars]`` capability in your inventory file. Here's what it would look like if you specified your SSH passwords (encrypted with Ansible Vault) among your variables:
..code-block:: ini
..code-block:: ini
@ -122,13 +96,21 @@ Because Ansible is a flexible tool, there are a number of ways to specify connec
If you use ssh-agent, you do not need the ``ansible_password`` lines. If you use ssh keys, but not ssh-agent, and you have multiple keys, specify the key to use for each connection in the ``[group:vars]`` section with ``ansible_ssh_private_key_file=/path/to/correct/key``. For more information on ``ansible_ssh_`` options see the :ref:`behavioral_parameters`.
If you use ssh-agent, you do not need the ``ansible_password`` lines. If you use ssh keys, but not ssh-agent, and you have multiple keys, specify the key to use for each connection in the ``[group:vars]`` section with ``ansible_ssh_private_key_file=/path/to/correct/key``. For more information on ``ansible_ssh_`` options see :ref:`behavioral_parameters`.
.. FIXME FUTURE Gundalow - Link to network auth & proxy page (to be written)
.. FIXME FUTURE Gundalow - Link to network auth & proxy page (to be written)
..warning:: Never store passwords in plain text.
..warning:: Never store passwords in plain text.
The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :doc:`../../user_guide/playbooks_vault` for more information.
Ansible vault for password encryption
-------------------------------------
The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information.
Common inventory variables
--------------------------
The following variables are common for all platforms in the inventory, though they can be overwritten for a particular inventory group or host.
:ansible_connection:
:ansible_connection:
@ -145,9 +127,9 @@ The "Vault" feature of Ansible allows you to keep sensitive data such as passwor
Which type of `become` should be used, for ``network_cli`` the only valid choice is ``enable``.
Which type of `become` should be used, for ``network_cli`` the only valid choice is ``enable``.
Privilege escalation
Privilege escalation
^^^^^^^^^^^^^^^^^^^^
--------------------
Certain network platforms, such as eos and ios, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible version 2.5 added support for``become`` when using ``connection: network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here:
Certain network platforms, such as Arista EOS and Cisco IOS, have the concept of different privilege modes. Certain network modules, such as those that modify system state including users, will only work in high privilege states. Ansible supports``become`` when using ``connection: network_cli``. This allows privileges to be raised for the specific tasks that need them. Adding ``become: yes`` and ``become_method: enable`` informs Ansible to go into privilege mode before executing the task, as shown here:
..code-block:: ini
..code-block:: ini
@ -161,15 +143,12 @@ For more information, see the :ref:`using become with network modules<become_net
Jump hosts
Jump hosts
^^^^^^^^^^
----------
If the Ansible Controller doesn't have a direct route to the remote device and you need to use a Jump Host, please see the :ref:`Ansible Network Proxy Command <network_delegate_to_vs_ProxyCommand>` guide for details on how to achieve this.
If the Ansible Controller doesn't have a direct route to the remote device and you need to use a Jump Host, please see the :ref:`Ansible Network Proxy Command <network_delegate_to_vs_ProxyCommand>` guide for details on how to achieve this.
Playbook
Example 1: collecting facts and creating backup files with a playbook
Ansible facts modules gather system information 'facts' that are available to the rest of your playbook.
Ansible facts modules gather system information 'facts' that are available to the rest of your playbook.
@ -179,13 +158,10 @@ Ansible's "Network Fact modules" gather information from the system and store th
To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the group defined in the inventory file, for more information on the use of conditionals in Ansible Playbooks see :ref:`the_when_statement`.
To ensure we call the correct mode (``*_facts``) the task is conditionally run based on the group defined in the inventory file, for more information on the use of conditionals in Ansible Playbooks see :ref:`the_when_statement`.
Example
=======
In this example, we will create an inventory file containing some network switches, then run a playbook to connect to the network devices and return some information about them.
In this example, we will create an inventory file containing some network switches, then run a playbook to connect to the network devices and return some information about them.
**Create an inventory file**
Step 1: Creating the inventory
------------------------------
First, create a file called ``inventory``, containing:
First, create a file called ``inventory``, containing:
@ -206,7 +182,8 @@ First, create a file called ``inventory``, containing:
vyos01.example.net
vyos01.example.net
**Create a playbook**
Step 2: Creating the playbook
-----------------------------
Next, create a playbook file called ``facts-demo.yml`` containing the following:
Next, create a playbook file called ``facts-demo.yml`` containing the following:
@ -307,8 +284,8 @@ Next, create a playbook file called ``facts-demo.yml`` containing the following:
If you have two or more network platforms in your environment, you can use the network agnostic modules to simplify your playbooks. You can use network agnostic modules such as ``cli_command`` or ``cli_config`` in place of the platform-specific modules such as ``eos_config``, ``ios_config``, and ``junos_config``. This reduces the number of tasks and conditionals you need in your playbooks.
..note::
Network agnostic modules require the :ref:`network_cli <network_cli_connection>` connection plugin.
Sample playbook with platform-specific modules
----------------------------------------------
This example assumes three platforms, Arista EOS, Cisco NXOS, and Juniper JunOS. Without the network agnostic modules, a sample playbook might contain the following three tasks with platform-specific commands:
..code-block:: yaml
---
- name: Run Arista command
eos_command:
commands: show ip int br
when: ansible_network_os == 'eos'
- name: Run Cisco NXOS command
nxos_command:
commands: show ip int br
when: ansible_network_os == 'nxos'
- name: Run Vyos command
vyos_command:
commands: show interface
when: ansible_network_os == 'vyos'
Simplified playbook with ``cli_command`` network agnostic module
You can replace these platform-specific modules with the network agnostic ``cli_command`` module as follows:
..code-block:: yaml
---
- hosts: network
gather_facts: false
connection: network_cli
tasks:
- name: Run cli_command on Arista and display results
block:
- name: Run cli_command on Arista
cli_command:
command: show ip int br
register: result
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'eos'
- name: Run cli_command on Cisco IOS and display results
block:
- name: Run cli_command on Cisco IOS
cli_command:
command: show ip int br
register: result
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'ios'
- name: Run cli_command on Vyos and display results
block:
- name: Run cli_command on Vyos
cli_command:
command: show interfaces
register: result
- name: Display result to terminal window
debug:
var: result.stdout_lines
when: ansible_network_os == 'vyos'
If you use groups and group_vars by platform type, this playbook can be further simplified to :
..code-block:: yaml
---
- name: Run command and print to terminal window
hosts: routers
gather_facts: false
tasks:
- name: Run show command
cli_command:
command: "{{show_interfaces}}"
register: command_output
You can see a full example of this using group_vars and also a configuration backup example at `Network agnostic examples <https://github.com/network-automation/agnostic_example>`_.
Using multiple prompts with the ``cli_command``
------------------------------------------------
The ``cli_command`` also supports multiple prompts.
..code-block:: yaml
---
- name: Change password to default
cli_command:
command: "{{ item }}"
prompt:
- "New password"
- "Retype new password"
answer:
- "mypassword123"
- "mypassword123"
check_all: True
loop:
- "configure"
- "rollback"
- "set system root-authentication plain-text-password"
- "commit"
See the :ref:`cli_command <cli_command_module>` for full documentation on this command.
Implementation Notes
Implementation Notes
@ -366,14 +475,10 @@ Note that when using variables from tasks in this way we use double quotes (``"`
Troubleshooting
Troubleshooting
===============
===============
If you receive an connection error please double check the inventory and Playbook for typos or missing lines. If the issue still occurs follow the debug steps in :doc:`network_debug_troubleshooting`.
If you receive an connection error please double check the inventory and playbook for typos or missing lines. If the issue still occurs follow the debug steps in :ref:`network_debug_troubleshooting`.
..seealso::
..seealso::
* :ref:`network_guide`
* :ref:`network_guide`
* :doc:`../../user_guide/intro_inventory`
* :ref:`intro_inventory`
* :ref:`Vault best practices <best_practices_for_variables_and_vaults>`
* :ref:`Vault best practices <best_practices_for_variables_and_vaults>`
Sandra McCann
6 years ago
committed by