The Ansible EOS Role¶

SSH Connection¶

When operating in this mode, Ansible will connect to the destination host using an encrypted SSH session. The SSH connection is established using either the hosts native SSH binary or using the Paramiko library. Since it uses SSH as the transport, the Ansible connection needs to be able to authenticate to the remote system and expects to operate in a Linux shell environment.

Local connections¶

When a host or task is operating with a local connection, tasks are executed from the Ansible host where the job was initiated. Local connections allow Ansible to make use of API transports and remove the need for establishing an SSH connection to the target device.

Accelerated mode¶

Ansible supported (since v0.8) a mode of operation known as Fireball mode. Fireball mode has since been depreciated in favor of accelerated mode (as of v1.3). Accelerated mode connects to the destination node and starts a daemon that is used for the remainder of the transaction.

In addition to the connection types discussed above, Ansible also supports a pull model. The pull model works in conjunction with SCM systems to perform its duties locally on the node. The pull model executes a local utility that retrieves the configuration data and proceeds to execute all of the activity locally on the node.

Integration with the Python Client for eAPI¶

The Ansible Role for EOS builds on the Python Client for eAPI to provide automation of the management plane. Using eAPI as the underlying tranport, Ansible can be configured to interface with Arista EOS using either SSH based connections or HTTP based connections.

Topologies¶

Above, we discussed how Ansible is typically used to control a node. These principles remain true for Arista EOS nodes, however, there are some nuances that are important to understand when using the Ansible EOS role. Next, we will discuss the two main methods used to control an Arista EOS node using Ansible.

The illustration above demonstrates a typical scenario. You, as the user, want to execute an Ansible Playbook on one (or many) of your Arista nodes. From the user’s perspective the interaction with the Ansible Control Host is the same, from your shell you would type:

ansible-playbook eos.yaml

Notice in the diagram a few things remain constant:

• pyeapi is always required (whether on the control host or EOS node), and
• pyeapi is ultimately responsible for making the eAPI calls to modify the node’s configuration

While the overall flow is similar, the way in which the playbook is executed will differ between Option A and Option B. Let’s discuss those differences below.

Option A¶

This method follows the traditional Ansible control procedure, namely:

1. Execute ansible-playbook eos.yaml from the Ansible Control Host
2. Collect Fact information from the node
3. Download the module to the node
4. Execute the module on the node
5. pyeapi commands run locally to modify configuration
6. Read stdout and parse it into JSON
7. Return the result to the Ansible Control Host

Assumption 1 You’ll notice that this method uses SSH to communicate with the node. This implies that you have already included the Ansible Control Host’s public SSH key in the nodes authorized_keys file, or you are providing a password when the playbook executes.

Assumption 2 Pyeapi is used by the Ansible EOS role modules to make configuration changes on the node. This implies that pyeapi is already installed on the node. The pyeapi module is NOT installed on Arista EOS nodes by default, so installation would be required by the user.

- name: eos nodes
  hosts: eos_switches

  tasks:
  - name: Configure EOS VLAN resources
    eos_vlan: vlanid=100
              name=mynewamazingvlan100
              username={{ username }}
              password={{ password }}
              transport={{ transport }}

[eos_switches]
192.168.0.50
192.168.0.51
192.168.0.52
192.168.0.53

[eos_switches:vars]
ansible_ssh_user=ansible
# Used for eapi connection once SSH'd in
username=eapi
password=password
transport=https

# empty file. This file is not needed on the EOS device.

- name: eos nodes
  hosts: eos_switches

  tasks:
  - name: Configure EOS VLAN resources
    eos_vlan: vlanid=100
              name=mynewamazingvlan100
              connection={{ connection }}

[eos_switches]
spine-1
spine-2
tor-1
tor-2

[eos_switches:vars]
connection=localhost
ansible_ssh_user=ansible

[connection:localhost]
username: admin
password: password
transport: https

Option B¶

This method uses the connection: local feature within the eos.yaml playbook. This causes the transport method to be an eAPI connection (HTTP[S]) versus SSH. This changes how the playbook gets executed in the following way:

1. Include connection: local in eos.yaml
2. Execute ansible-playbook eos.yaml from the Ansible Control Host
3. pyeapi consults the local ~/.eapi.conf file which provides node connection information
4. Collect Fact information from the node
5. Execute the module on the Ansible Control Host
6. pyeapi commands run over the network to modify configuration
7. Read stdout and parse it into JSON
8. Present the result on the Ansible Control Host

Assumption 1 Here, the connection between the Ansible Control Host and the Arista node is an eAPI connection. This implies that you have an eapi.conf file on your Ansible Control Host that contains the connection parameters for this node, or you pass the connection parameters as meta arguments. The caveat when using eapi.conf is that the password for the eAPI connection is stored as plaintext. See Is there any intention to encrypt passwords we put into eapi.conf? for more information.

- name: eos nodes
  hosts: eos_switches
  connection: local

  tasks:
  - name: Configure EOS VLAN resources
    eos_vlan: vlanid=100
              name=mynewamazingvlan100
              host={{ inventory_hostname }}
              username={{ username }}
              password={{ password }}
              transport={{ transport }}

[eos_switches]
192.168.0.50
192.168.0.51
192.168.0.52
192.168.0.53

[eos_switches:vars]
username=eapi
password=password
transport=https

# empty file

- name: eos nodes
  hosts: eos_switches
  connection: local

  tasks:
  - name: Configure EOS VLAN resources
    eos_vlan: vlanid=100
              name=mynewamazingvlan100
              connection={{ inventory_hostname }}

[eos_switches]
spine-1
spine-2
tor-1
tor-2

[connection:spine-1]
host: 192.168.0.50
username: admin
password: password
transport: https

[connection:spine-2]
host: 192.168.0.51
username: admin
password: password
transport: https

[connection:tor-1]
host: 192.168.0.52
username: admin
password: password
transport: https

[connection:tor-2]
host: 192.168.0.53
username: admin
password: password
transport: https

1. Enabling EOS Command API¶

The modules provided in the Arista EOS role require command API (aka eAPI) to be enabled on the switch. The modules use eAPI to communicate with EOS. Since eAPI is not enabled by default, it must be initially enabled before the EOS modules can be used.

The steps below provide the basic steps to enable eAPI. For more advanced configurations, please consult the EOS User Guide.

As you may have learned in The Ansible EOS Role, when you connect to your node over SSH, Ansible will copy the Python module code to the switch and then execute it locally using Pyeapi APIs. Therefore, you have a few options when it comes to which protocol is enabled for eAPI.

Therefore, it is recommended to use socket if you are running a recent version of EOS. Otherwise, use HTTP or HTTPS depending upon your security model.

Step 1.1. Login to the destination node and enter configuration mode

switch> enable
switch# configure
switch(config)#

Step 1.2a. Enable eAPI for Unix Sockets and Disable HTTP/s

switch(config)# management api http-commands
switch(config-mgmt-api-http-cmds)# no shutdown
switch(config-mgmt-api-http-cmds)# protocol unix-socket
switch(config-mgmt-api-http-cmds)# no protocol https

Step 1.2a. Enable eAPI for HTTP Local

This will only expose port 8080 at the loopback (localhost)

switch(config)# management api http-commands
switch(config-mgmt-api-http-cmds)# no shutdown
switch(config-mgmt-api-http-cmds)# no protocol https
switch(config-mgmt-api-http-cmds)# protocol http localhost

Step 1.2a. Enable eAPI for Standard HTTP/S

switch(config)# management api http-commands
switch(config-mgmt-api-http-cmds)# no shutdown

The configuration above enables eAPI with the default settings. This enables eAPI to listen for connections on HTTPS port 443 by default.

Step 1.3. Create a local user The user created in this step is different than the shell account to be created in the Preparing EOS for Ansible section. Please see the section Understanding the Security Model for more details.

switch(config)# username eapi secret icanttellyou

The username (eapi) and password (icanttellyou) can be any valid string value.

2. Preparing EOS for Ansible¶

In order to successfully execute playbook tasks the EOS node must be configured to allow the Ansible control node to directly attach to the Linux shell. The following steps provide a walk through for setting up password-less access to EOS nodes for use with Ansible.

Step 2.1. Login to the destination node and enter the Linux shell

veos> enable
veos# bash

Arista Networks EOS shell

Step 2.2. Create the user to use with Ansible, create the home directory and prepare for uploading your SSH key. In the below example we will create a user called ansible. The second command will create a temporary password for the user but we will be switching to using SSH keys and the password will be removed

# create the user 'ansible' with temporary password 'password'
[admin@veos ~]$ sudo useradd -d /persist/local/ansible -G eosadmin ansible
[admin@veos ~]$ echo password | sudo passwd --stdin ansible
Changing password for user ansible.
passwd: all authentication tokens updated successfully.

# prepare the home directory so we can upload an ssh key
[admin@veos ~]$ sudo mkdir /persist/local/ansible/.ssh
[admin@veos ~]$ sudo chmod 700 /persist/local/ansible/.ssh
[admin@veos ~]$ sudo chown ansible:eosadmin /persist/local/ansible/.ssh
[admin@veos ~]$ sudo ls -lah /persist/local/ansible

# exit the Linux shell and disconnect
[admin@veos01 ~]$ logout
veos#logout
Connection to veos01 closed.

Step 2.3. Upload the SSH key to use from your Ansible control host and verify access from remote host

ansible@hub:~$ scp ~/.ssh/id_rsa.pub ansible@veos01:.ssh/authorized_keys
Password:

ansible@hub:~$ ssh ansible@veos01

Arista Networks EOS shell

[ansible@veos ~]$

Step 2.4. Configure EOS to create user on reboot with no password assigned. This will only allow the Ansible user to login with keys.

[ansible@veos ~]$ vi /mnt/flash/rc.eos

#!/bin/sh
useradd -d /persist/local/ansible -G eosadmin ansible

Step 2.5. Reboot the EOS node and start automating with Ansible

[ansible@veos ~]$ sudo reboot

3. Install pyeapi¶

As mentioned earlier, the Ansible EOS role uses pyeapi on the Arista node that will be configured. Follow the pyeapi installation guide to install the package.

4. A Simple Playbook¶

If you are new to Ansible it might seem like a lot is going on, but this step will show you how easy it is to manage your Arista device. The power of Ansible lies in the Playbook. We will just skim the surface of what’s possible in a playbook, but this should serve as a good launching point.

Step 4.1. Create an Ansible Inventory File

Each Ansible play references one or more nodes. You define these nodes in an Ansible hosts file.

ansible@hub:~$ mkdir ~/myfirstplaybook
ansible@hub:~$ cd ~/myfirstplaybook
ansible@hub:~$ vi hosts

and add the connection info for your node substituting the IP or FQDN of your node as well as the name of the user created in Step 2.2 above:

[eos_switches]
<node>
# Add more entries here for additional devices you want to
# keep in the eos_switches group

[eos_switches:vars]
ansible_ssh_user=<user>
# Information from step 1.2. Used for eapi connection once Ansible SSHes in.
transport=https
username=eapi
password=icanttellyou
port=<port-if-non-default>

Example

[eos_switches]
veos01
veos02
veos03
veos04

[eos_switches:vars]
ansible_ssh_user=ansible
transport=https
username=eapi
password=icanttellyou

Step 4.2. Create playbook

Let’s create Vlan150 using the eos_vlan module:

ansible@hub:~$ vi my-test-eos-playbook.yml

Then paste in the following

---
- hosts: eos_switches
  gather_facts: no

  roles:
    - arista.eos

  tasks:
    - name: configures vlan 150
      eos_vlan:
        vlanid=150
        name=newVlan150
        transport={{ transport }}
        username={{ username }}
        password={{ password }}
        debug=yes
      register: vlan_cfg_output

    - debug: var=vlan_cfg_output

Step 4.3. Run playbook

Simply execute from your Ansible Host and review output:

ansible@hub:~$ ansible-playbook -i hosts my-test-eos-playbook.yml

Result:

You should see JSON output containing any changes, along with the current and desired state. So what really happened?

1. We execute the command and Ansible goes to our inventory to find the specified nodes in group eos_switches.
2. Ansible is told to connect via SSH with user ansible from ansible_ssh_user=ansible.
3. Ansible creates a temp directory in the ansible user’s home directory
4. Ansible copies eos_vlan.py to the temp directory created above.
5. Ansible executes eos_vlan.py with the specified arguments
6. eos_vlan.py uses pyeapi to configure the new Vlan.
7. Ansible cleans up the temp folder and returns output to the control host.

You should notice that Ansible reports configuration has changed. If you ran this command again it should report no changes due to idempotency.

1. Enabling EOS Command API¶

The modules provided in the Arista EOS role require command API (aka eAPI) to be enabled on the switch. The modules use eAPI to communicate with EOS. Since eAPI is not enabled by default, it must be initially enabled before the EOS modules can be used.

The steps below provide the basic steps to enable eAPI. For more advanced configurations, please consult the EOS User Guide.

Step 1.1. Login to the destination node and enter configuration mode

switch> enable
switch# configure
switch(config)#

Step 1.2. Enable eAPI

switch(config)# management api http-commands
switch(config-mgmt-api-http-cmds)# no shutdown

The configuration above enables eAPI with the default settings. This enables eAPI to listen for connections on HTTPS port 443 by default.

Step 1.3. Create a local user The user created in this step is used by pyeapi to run configuration commands.

switch(config)# username eapi secret icanttellyou

The username (eapi) and password (icanttellyou) can be any string value. The values are then used in either eapi.conf or passed in through the module meta arguments to authenticate to eAPI.

2. Install pyeapi¶

As mentioned earlier, the Ansible EOS role uses pyeapi on the Arista node that will be configured. Follow the `pyeapi http://pyeapi.readthedocs.org/en/latest/install.html>`_ installation guide to install the package.

Create local pyeapi.conf file

[ansible@hub ~]$ vi ~/.eapi.conf

with credentials you created in Step 1.3. The connection:<NAME> should match the entry in hosts, Step 3.1 below:

[connection:veos01]
host: <ip-or-fqdn>
transport: https
username: eapi
password: icanttellyou
port: <port-if-non-default>

3. A Simple Playbook¶

If you are new to Ansible it might seem like a lot is going on, but this step will show you how easy it is to manage your Arista device. The power of Ansible lies in the Playbook. We will just skim the surface of what’s possible in a playbook, but this should serve as a good launching point.

Step 3.1. Create an Ansible Inventory File

Let’s add the details of our test node to an Ansible Inventory file.

ansible@hub:~$ mkdir ~/myfirstplaybook
ansible@hub:~$ cd ~/myfirstplaybook
ansible@hub:~$ vi hosts

and add the connection info for your node substituting the IP or FQDN of your node under our eos_switches group. This should match the connection parameter in your ~/.eapi.conf:

[eos_switches]
<node>

Example

[eos_switches]
veos01

Step 4.2. Create playbook

Let’s create Vlan150 using the eos_vlan module:

ansible@hub:~$ vi my-test-eos-playbook.yml

Then paste in the following

---
- hosts: eos_switches
  gather_facts: no
  connection: local

  roles:
    - arista.eos

  tasks:
    - name: Add Vlan 150 to my switches
      eos_vlan:
        vlanid=150
        name=newVlan150
        connection={{ inventory_hostname }}
        debug=yes
      register: vlan_cfg_output

    - debug: var=vlan_cfg_output

Step 4.3. Run playbook

Simply execute from your Ansible Host:

ansible@hub:~$ ansible-playbook -i hosts my-test-eos-playbook.yml

Result:

You should see JSON output containing any changes, along with the current and desired state. So what really happened?

1. We execute the command and Ansible goes to our inventory to find the specified nodes that match group eos_switches.
2. Ansible is told to use connection:local so no SSH connection will be established to the node.
3. Ansible substitutes the host name from hosts into the {{ inventory_hostname }} parameter. This creates the link to the [connection:veos01] in ~/.eapi.conf.
4. Ansible creates a temp directory in the user’s home directory, eg $HOME/.ansible/tmp/.
5. Ansible copies eos_vlan.py to the temp directory created above.
6. Ansible executes eos_vlan.py with the specified arguments
7. eos_vlan.py uses pyeapi to configure the Vlan.
8. pyeapi consults ~/.eapi.conf to find connection named veos01
9. Ansible cleans up the temp folder and returns output to the control host.

You should notice that Ansible reports configuration has changed. If you ran this command again it should report no changes due to idempotency.

Installing via YUM¶

Ansible is provided via standard RPM installations from EPEL 6 and Fedora repositories. Simply run Yum with appropriate permissions to install the latest version of Ansible.

$ sudo yum install ansible

Installing via Apt (Ubuntu)¶

In order to install directly from Apt, the Ansible PPA will need to be added to Apt’s sources. Ansible binaries are installed from this PPA. Once the PPA has been added to the Apt sources list execute the following commands to install Ansible.

sudo apt-get install software-properties-common
sudo apt-add-repository ppa:ansible/ansible
sudo apt-get update
sudo apt-get install ansible

Installing via PIP¶

Ansible can be installed using Python PIP. To install Ansible with PIP, simply enter the following command from a shell prompt.

sudo pip install ansible

Install Using Ansible Galaxy¶

From your Ansible Control Host, type:

sudo ansible-galaxy install arista.eos

Then you can use the role in your play as:

#my-playbook.yml
---
- hosts: eos_switches
  gather_facts: no

  roles:
    - arista.eos

  tasks:
    - name: configure Vlan150
      eos_vlan:
        vlanid=150

Installing from GitHub (for active development)¶

To get started, download the latest Arista EOS modules from Github using the clone command. From a terminal on the Ansible control system issue the following command:

git clone https://github.com/arista-eosplus/ansible-eos.git

The command above will create a new directory called ‘ansible-eos’ and clone the entire repository. Currently, the ansible-eos folder contains the “develop” branch which provides the latest code. Since the “develop” branch is still a work in progress, it might be necessary to switch to a released version of the EOS modules. In order to switch to a specific release version, change directories to the ansible-eos directory and enter the following command.

git tag
git checkout tags/<tag name>

The first command above “git tag” provides a list of all available tags. Each release has a corresponding tag that denotes the released code. To switch to a specific release simply use the name of the tag in the second command as the <tag name>.

For instance, to use the v1.0.0 release, enter the command

git checkout tags/v1.0.0

At any point in time switching to a different release is as easy as changing to the ansible-eos directory and re-issuing the “git checkout” command.

You will need to make Ansible aware of this new role if you want to use the included modules in your plays. You have a few options:

Option 1: Create Symlink (preferred)

We will create a symlink in /etc/ansible/roles/ to make Ansible aware of the ansible-eos role. Notice that the symlink name is arista.eos. This is because the Ansible Galaxy role is named arista.eos:

# create soft symlink
cd /etc/ansible/roles
sudo ln -s /path/to/where/your/git/clone/is/ansible-eos arista.eos

Then you can use the role in your play as:

#my-playbook.yml
---
- hosts: eos_switches
  gather_facts: no

  roles:
    - arista.eos

  tasks:
    - name: configure Vlan150
      eos_vlan:
        vlanid=150

Option 2: Edit ansible.cfg roles_path

Here, you can edit /etc/ansible/ansible.cfg to make Ansible look for the ansible-eos directory:

# open the config file in an editor
sudo vi /etc/ansible/ansible.cfg

# if roles_path exists add a colon and the new path
# if the variable doesn't exist, create it under [defaults] section
[defaults]
roles_path=/path/to/where/your/git/clone/is/ansible-eos

Then you can use the role in your play as:

#my-playbook.yml
---
- hosts: eos_switches
  gather_facts: no

  roles:
    - ansible-eos

  tasks:
    - name: configures the hostname on tor1
      eos_vlan:
        vlanid=150

What are the basic requirements for using the EOS role for Ansible?¶

This varies a little bit based upon how you communicate with your node. The two options are explained in Topologies.

Regardless of connection method you need the following:

• Ansible 1.9 or later
• Arista EOS 4.13.7M or later running on your node
• EOS Command API enabled (see 1. Enabling EOS Command API for more information)

In addition to the above, there are other connection-specific requirements:

If you connect to your node via SSH:

• You need the Python Client for eAPI 0.3.0 or later installed on your EOS node (see 3. Install pyeapi for more information)
• Linux shell account on your EOS node (see 2. Preparing EOS for Ansible for more information)

If you connect to your node via eAPI:

• You need the Python Client for eAPI 0.3.0 or later installed on your Ansible server (see 2. Install pyeapi for more information)

Is there any intention to encrypt passwords we put into eapi.conf?¶

No, we are working on support for certificates but we cannot encrypt the password in eapi.conf. The best alternative is to use Ansible vault or prompt for password at runtime of the playbook.

Is pyeapi required on both the Ansible control host and the EOS node?¶

It depends on if using (or want to use) connection local. The Python client for eAPI (pyeapi) must be installed where ever the Ansible module is executed from. The pyeapi client is a dependency of the common module code for all of the modules.

Do I have to use the pyeapi eapi.conf file?¶

No, it is not a absolute requirement. All EOS modules will accept connection parameters for configuring the eAPI transport properties. Using eapi.conf is convenient but not necessary.

Does the EOS role work with Ansible Tower?¶

Yes, the Ansible EOS role works fine with implementations that utilize Ansible Tower for management.

Does the Ansible EOS role work with all version of Arista EOS?¶

The Ansible EOS role is tested to work with EOS 4.13.7M or later releases. Any EOS release prior to 4.13.7M is not guaranteed to work with the EOS role.

Is there any requirement to put changes into ansible.cfg?¶

No, it works with all the Ansible defaults.

Is there something like a rollback function available in ansible?¶

Yes, it’s all in the implementation. When working with a tool like Ansible, the node configuration should be kept under version control. As such, rolling back a nodes configuration is a matter of reverting the config. It’s an implementation detail, not necessarily a module or feature. We have successfully demonstrated rollback many times using Ansible.