In this Cisco Ansible tutorial for beginners I will take you from the very beginning, installing Ansible on Ubuntu, to setting up the folders and running through a simple playbook which will backup the configuration of a Cisco router. I will say that I am not a Linux expert so if you notice any Linux errors or better ways of doing things please comment and I will update this article.
Ansible is a simple automation language that can perfectly describe and IT application or network infrastructure in Ansible Playbooks. It’s an automation engine that runs Ansible Playbooks.
Ansible is a free-software platform for configuring and managing computers or network devices which combines multi-node software deployment, ad hoc task execution, and configuration management. (description taken from wikipedia)
It can also be used for network management. The beauty of Ansible is that it is does not require an agent on the host system it uses SSH for transport. As long as Ansible can make an SSH connection to the target device you are good to go. Ansible used to be primarily used for server administration but in the last few years more and more network modules have been added to the software and Ansible is a skill that all Network Engineers should be getting up to speed on.
There are two versions, free and paid. The paid version is called Ansbile Tower which is an enterprise framework for controlling, securing and managing your Ansible automation with a GUI and Restful API.
This Ansible tutorial will cover the free version installed on an Ubuntu desktop.
Ansible Tutorial Step 1 – How to Install Ansible on Ubuntu
You can install Ansible on many versions of Linux but for this tutorial I will using Ubuntu 16.04 LTS running within VMWorkstation Pro
For my lab I am running this on on my laptop. I will run 2 VMs, the first is Ubuntu Desktop to run Ansible and the other will be a Cisco CSR1000V router.
From this point on I am assuming that you have a clean version of Ubuntu installed.
There will be a few enhancements I make to Ubuntu to make running Ansible easier which will be detailed along the way.
Installing Ansible
Before we start lets just establish that Ansible is not already installed on this system.
You can do this with the ansible –version command
1 2 3 |
roger@ubuntu:~$ ansible --version The program 'ansible' is currently not installed. You can install it by typing: sudo apt install ansible |
The best way to get Ansible for Ubuntu is to add the project’s PPA (personal package archive) to your system.
Open a terminal and run the command:
1 |
sudo apt-get update |
Then run the command
1 |
sudo apt-get install software-properties-common |
Now the package is installed you can install Ansible by entering the following command.
1 |
sudo apt-add-repository ppa:ansible/ansible |
You will need to press ENTER to accept the PPA addition.
Next run the command
1 |
sudo apt-get update |
Finally to install Ansible run the command
1 |
sudo apt-get install ansible |
Ansible is now installed and can be verified with the command
1 |
ansible --version |
At the time of writing the current Ansible version is 2.2.1.0
1 2 3 4 5 |
roger@ubuntu:~$ ansible --version ansible 2.2.1.0 config file = /etc/ansible/ansible.cfg configured module search path = Default w/o overrides roger@ubuntu:~$ |
Ok so now we have Ansible installed lets start using it.
Enable Colorful Terminal in Debian and Ubuntu
One of the extras I have enable in my Ubuntu install is the colorful terminal as shown below
To get the coloured prompt you need to edit the file .bashrc
This process is described here
Start using Ansible
The first thing to do is to drop into the Ansible folder and explore the default folder structure.
From your home prompt run the command
1 |
cd /etc/ansible |
then issue a dir and let’s see whats in there
In the default Ansible installation there are two files and a directory
ansible.cfg contains all the default values and the main ones are listed below
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# some basic default values... #inventory = /etc/ansible/hosts #library = /usr/share/my_modules/ #remote_tmp = ~/.ansible/tmp #local_tmp = ~/.ansible/tmp #forks = 5 #poll_interval = 15 #sudo_user = root #ask_sudo_pass = True #ask_pass = True #transport = smart #remote_port = 22 #module_lang = C #module_set_locale = False |
For this tutorial we are not going to touch the Ansible.cfg file but you just need to be aware of it’s location.
For this tutorial we just need to be aware that the default inventory file location is /etc/ansible/hosts
This file defines all the hosts you will be connecting to – so let’s look at that file.
From within the Ansible directory lets edit the hosts file
1 |
vi hosts |
You can see all hosts in the default file are commented out
For our backup Cisco Router playbook we just need to add one router in there so I am going to add a group called CSR-Routers and add one router.
My hosts files now looks like this
1 2 3 |
# Ex 2: A collection of hosts belonging to the CSR-Routers' group [CSR-Routers] CSR-01 ansible_host=192.168.244.129 |
You can enter names of devices in here if your Ubuntu host can resolve them in DNS but for this basic tutorial I am just using the ansible_host command
I can now reference this host in one of two ways. Either by calling CSR-Routers or CSR-01. If I call CSR-Routers my playbook will action on every device within the CSR-Routers group if I call CSR-01 in my playbook then it will only action on that single device.
What is an Ansible Playbook?
Before we go any further I just need to define one term that you will be using every day whilst working with Ansible and that is a playbook. In simple terms a playbook is a file formatted in YAML
YAML stands for YAML Ain’t Markup Language but is also referred to as Yet Another Markup Language. Basically YAML is a very readable code that defines all the actions and tasks that your playbook will perform. Let’s look at the finished playbook below to backup a cisco router and go through each line step by step in a very quick Ansible playbook tutorial.
Ansible Playbook Example to Backup Cisco Router
My playbook is called backup_cisco_router.yaml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
--- - hosts: CSR-01 gather_facts: true connection: local tasks: - name: show run ios_command: commands: - show run host: "{{ ansible_host }}" username: roger password: KanKu009 register: config - name: save output to /etc/ansible/backups copy: content: "{{ config.stdout[0] }}" dest: "/etc/ansible/backups/show_run_{{ inventory_hostname }}.txt" |
I have this saved in a folder called playbooks /etc/ansible/playbooks
I have also created a folder called backups in /etc/ansible/backups
Let’s step through each line
— the first line of any YAML file has to start with three dashes – this denotes it as a YAML file
– hosts: CSR-01 the next line starts with a single dash and defines the hosts that this playbook should run agains, in this case our single CSR router
gather_facts: true this line needs to be here to define we are collecting information
connection: local this defines the connection will be made from this box
tasks: we now start to define the actual task that will run
– name: show run – this is the name of our first task
ios_command: this is an ansible module and is some code within the Ansible core that can be used to run commands in ios – more info here
commands: what follows here is the command that will be run
– show run in our case show run
host: “{{ ansible_host }}” this defines the connection variables for the ansible host – username / password etc
username: local username defined on the router
password: local password defined on the router
register: config Once Ansible has connected to the router and run the show run command it registers that information to a variable called config (you can call this what you want)
-name save output to /etc/ansible/backups – this is the name of the next task and is just a description
copy: this is calling another Ansible Module called copy
content: “{{ config.stdout[0] }}” this registers the config to a format called stdout
dest: “/etc/ansibe/backups/show_run_{{ inventory_hostname }}.txt” – this defines the destination and filename format which will be show_run_hostname.txt
Running the Ansible Playbook
So we now have an Ansible playbook written, we have defined a host and we now need to run the playbook.
I have a CSR1000v router running so lets see what happens
To run an Ansible Playbook you run the command
ansible-playbook <playbook name>
so in our case
ansible-playbook backup_cisco_router.yaml
You can see the descriptions of each task and if the play was successful.
In this case the playbook failed as it failed to connect to the router 192.168.244.129:22
The problem in this case is the password was wrong on the router – I am going to change the password and run the play again
This time you can see the playbook ran successfully and the task status has moved to changed=1
This means the backup file has changed.
If we now go to /etc/ansible/backups we can see our backup file
Conclusion
So we have successfully created an Ansible Playbook that will backup a single Cisco router, you can hopefully see that this could easily be scaled out to perform this task on 100’s or 1000’s of devices and also to run other commands like sh ip int brief, sh log, sh ip ospf neighbor etc.
Ansible is a very powerful tool and is going to change the way network engineers work in the future.
I hope you enjoyed this simple tutorial and there will be more to come.
For all my posts relating to Ansible – please check out the Ansible for Network Engineers Posts Here
Look here for a more specific post detailing an Ansible ios_command example
Check out my AnsibleFest London 2017 Review
Can Ansible be installed on Windows?
The short answer is No, can Ansible run on windows is one of the most common questions I get and sadly at this point in time it is Linux only.
Who created Ansible?
You can read about the origins of Ansible here – https://www.ansible.com/blog/2013/12/08/the-origins-of-ansible
Who owns Ansible?
Ansible was bought by Red Hat in October 2015, it is now referred to as Ansible by Red Hat
Why is Ansible better than Chef or Puppet?
The big debate about is Ansible better than Chef or Puppet will go on, but in a sentence, the main advantage Ansible has over Puppet and Chef is that it is agentless. For managing servers using Chef and Puppet you need to install an agent onto the server, which is not a big task and I have seen some people using Ansible to do that!
But for managing network devices, in the most part you are not able to install an agent on a Cisco Switch, so for the network engineer Ansible is better.
What is Ansible written in?
Python
What is Ansible Galaxy?
Ansible Galaxy is Ansible’s official community hub for sharing Ansible roles. A role is the Ansible way of bundling automation content and making it reusable.
https://galaxy.ansible.com/intro
What is Ansible Tower?
Ansible Tower (formerly ‘AWX’) is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds. It’s designed to be the hub for all of your automation tasks. Tower is free for usage for up to 10 nodes, and comes bundled with amazing support from Ansible, Inc.
http://docs.ansible.com/ansible/latest/tower.html
What is Ansible Engine?
Ansible Engine is the same Ansible Core you get when running the free version but with Ansible Engine you pay for support. Ansible Engine is developed by Red Hat with the explicit intent of being used as an enterprise IT platform.
What is Ansible AWX
The AWX project is the open source version of Ansible Tower. AWX is the upstream project from which the Red Hat Ansible Tower offering is ultimately derived.
You can run AWX for free with as many nodes as you want, however is does not come with any support, but the code is what Ansible Tower is based on.
The product is pretty much the same.
https://www.ansible.com/awx-project-faq
I’m new to this (using your tutorial for my first attempt), but it appears that the spacing in your yaml files is way off. it’s creating problems when trying to run the playbook.
I imagine its to do with the formatting of the text on the website
Take it from here instead
https://github.com/rogerperkin/playbooks/blob/master/backup_cisco_router.yaml
Also, your use of the COPY module does not use the correct syntax according to the ansible docs: http://docs.ansible.com/ansible/latest/copy_module.html
hello,
I am facing below error message while running playbook
“msg”: “unable to open shell. Please see: https://docs.ansible.com/ansible/network_debug_troubleshooting.html#unable-to-open-shell“,
any SOLUTION you have
Can you SSH to your device from the Ansible host?
ssh -l
Hi,
Am facing below Error
TASK [show run] ************************************************************************************************************************************************
fatal: [CSR-01]: FAILED! => {“changed”: false, “failed”: true, “msg”: “unable to open shell. Please see: https://docs.ansible.com/ansible/network_debug_troubleshooting.html#unable-to-open-shell“}
to retry, use: –limit @/etc/ansible/router1.retry
PLAY RECAP *****************************************************************************************************************************************************
CSR-01 : ok=1 changed=0 unreachable=0 failed=1
root@ansible-virtual-machine:/etc/ansible#
Can you SSH to the device from your host machine?
This is typically a password problem or connectivity to the target device.
If you can get to it from your host machine then verify password details are correct.
i’m able to take ssh to a device from my host machine, but still it shows the same error
Can you run the playbook with -vvv at the end and see if you can see any further error messages?
IT DOESN’T SHOW ANY FURTHER ERROR MESSAGES
sTILL RECEIVING THE SAME ERROR
TASK [show run] ****************************************************************
task path: /etc/ansible/backup_router.yaml:7
using connection plugin network_cli
failed: [CSR-01] (item=3YAlNucrK8gylvMwH9HQ) => {
“changed”: false,
“failed”: true,
“item”: “3YAlNucrK8gylvMwH9HQ”,
“msg”: “unable to open shell. Please see: https://docs.ansible.com/ansible/network_debug_troubleshooting.html#unable-to-open-shell”
}
to retry, use: –limit @/etc/ansible/backup_router.retry
PLAY RECAP *********************************************************************
CSR-01 : ok=1 changed=0 unreachable=0 failed=1
Can you run the playbook with -vvv at the end and send me the output
i have an invetory list of devices and i am trying to backup running configs. There is no error few of the running config files for respective hosts remains empty. Why ?
Run your playbook with -vvv at the end and this will log all the activity – you should be able to spot the issue there.