Using Docker as an Ansible and Python platform for Network Engineers
A quick start guide for using the purpose built Docker images for Ansible and Python
Built for Network Engineers by a Network Engineer
Over the last few years I've built up a repository of Docker images to help me learn Ansible. If you are new to Ansible you may not know that while Ansible can control all manner of devices (Windows, Linux, Network, Virtual or Bare Metal, Cloud, etc.) the Ansible control server itself only runs on Linux. If you are trying to get started, you first have to stand up a control server. Depending on your familiarity with Linux and Virtualization technology you can spend quite a bit of time going down different avenues just to get to the point where you can run a playbook.
Docker was the answer for me.
These Ansible Docker images have been built over the years to provide a quick alternative to running an Ansible Control server on a local virtualization VM (VirtualBox or VMware) on my laptop or desktop. A container is also handy if you need an Ansible Control server to use via a VPN connection. You will see that many of the test playbooks are playbooks designed to perform discovery on a set of devices (aka run lots of show commands and save the output) and so a common practice is to VPN in (or connect directly) to a client network and quickly perform this discovery task.
I've kept the various images with different Ansible versions so I can test playbooks on specific versions. In many cases I work with clients who use a specific version of Ansible and so it's handy to be able to test locally on the version they use.
This "Quick Start" cheat sheet is intended to get you up and running quickly with the various Ansible containers (the running image).
The following Docker images are available on Docker Hub
Docker Images providing an Ansible and Python environment for Network Engineers - Complete List
Select a specific Ansible Version:
- Disco Immigrant (Ubuntu 19.04 Disco Dingo) and Ansible 2.9 Immigrant Song
- Bionic Immigrant (Ubuntu 18.04 LTS Bionic Beaver) and Ansible 2.9 Immigrant Song *
- Cosmic More Time (Ubuntu 18.10 Cosmic Cuttlefish) and Ansible 2.8 More Time
- Cosmic Light (Ubuntu 18.10 Cosmic Cuttlefish) and Ansible 2.7 In the Light
- Cosmic Hearthbreaker (Ubuntu 18.10 Cosmic Cuttlefish) and Ansible 2.6 Heartbreaker
- Xenial Ansible (Ubuntu 16.04Xenial Xerus) and Ansible 2.4
- Trusty Ansible (Ubuntu 14.04 Trusty Tahr) and Ansible 2.2
* if you are not sure which image to use, go with Bionic Immigrant! It's the most mature, based on Ubuntu 18.04 Long Term Support (LTS), supports the automated Documentation examples you may have seen, and includes the Batfish client, Batfish Ansible module/role, and Ansible Network Engine role. It is also the image that will run all of my shared repositories.
Installing Docker
To run any Docker image you will need to install Docker Desktop on your Mac or Windows system (see note below about Docker Desktop for Windows and consider Docker Toolbox if you run other virtualization software) or Docker Engine on your linux host. You can use the free Docker Community Edition.
The instructions below focus on Mac and Windows operating systems as those tend to be the most prevalent among Network Engineers (at least the ones I know!).
Install on your Operating System of choice
Installing Docker Desktop on Mac
Installing Docker Desktop on Windows
WARNING: The Docker Desktop application is only supported on Windows 10 Pro (or better) 64-bit and requires Hyper-V and the Containers Window features to be enabled.
This means that other Virtualization software that does not support HyperV will not work work (i.e. VMware Workstation and VirtualBox) while you have Hyper-V enabled and Docker Desktop won't work when you have have Hyper-V disabled (but VirtualBox and VMware will).
If you have existing Virtualization software installed and which you use, Docker Toolbox for Windows is still available.
For the Linux aficionados:
Installing Docker Engine Community version on Linux
Getting Started on Mac with Docker Desktop
Environment:
- Mac OS X (macOS Sierra Version 10.12.6)
- Intel based iMac
- Intel Core i7 4GHz 32 GB Memory
Summary of Steps
- Make sure Docker Desktop is installed and running
- Open a terminal window and launch your container with the docker run command
- Look around the ready built repositories which are cloned into the container to get you started quickly (always remember to git pull to get the latest).
Details
Using Docker Desktop on Mac OS X Video ~13min
1 Before starting make sure that Docker is installed and running on your Mac.
2 Open a terminal window and use the docker run -it command to start the container on your Mac.
Full command to start an interactive session
docker run -it cldeluna/disco-immigrant
The first time you execute this command, the docker image will download and then put you into an interactive bash shell in the container.
-i, --interactive Keep STDIN open even if not attached
-t, --tty Allocate a pseudo-TTY
This will basically take over your terminal window so if you need to do something else on your system open up a new or different terminal window. Check the command cheat sheet for alternatives like using the -dit option to run in the background and the docker exec command to "attach" to the running container.
If you have not downloaded the image using the docker pull <image> command the docker run command will know and pull it down for your. Once the download is complete and the container is running you will notice that the prompt in your terminal window has changed.
It will look something like "root@c421cab61f1f:/ansible_local".
Claudias-iMac:disco-immigrant claudia$ docker run -it cldeluna/disco-immigrant root@c421cab61f1f:/ansible_local#
3 Start looking around!
Check the version of ansible on the container. In the example below we are using the disco-immigrant image which comes with ansible 2.9.1.
Several repositories are cloned into the container to get you started quickly. Check out the Ansible playbook repositories and change directory into one to see the example playbooks and try one!...you can find details in the "Run one of the ready built Playbooks!" At this point, once you are in a working docker CLI the process is basically the same across all operating systems.
Always do a "git pull" in any of the cloned repositories to make sure you are running the latest scripts and playbooks.
Run your first playbook! You don't need to bring up any device as many of the playbooks use the DevNet AlwaysOn Sandbox devices.
If you cd or change directory into the cisco_ios directory you can get started with some basic Playbooks.
Claudias-iMac:disco-immigrant claudia$ docker run -it cldeluna/disco-immigrant root@c421cab61f1f:/ansible_local# root@c421cab61f1f:/ansible_local# ls ansible2_4_base cisco_aci cisco_ios root@c421cab61f1f:/ansible_local# cd cisco_ios root@c421cab61f1f:/ansible_local/cisco_ios# ls ansible.cfg ios_all_vrf_arp.yml ios_show_cmdlist_zip.yml logs filter_plugins ios_facts_lab.yml ios_show_lab.yml nxos_facts_lab.yml group_vars ios_facts_report.yml ios_show_lab25.yml nxos_show_cmdlist.yml hosts ios_show_cmdlist.yml ios_show_lab_brief.yml templates root@c421cab61f1f:/ansible_local/cisco_ios#
Using Docker Desktop on Mac OS X Video ~13min
Getting Started with Docker Toolbox on Windows
Environment:
- Microsoft Windows 10 Pro
- x64-based PC
- Intel(R) Core(TM)i7-6700K CPU @ 4.00GHz, 4008 Mhz, 4Core(s)...
Summary of Steps
- Make sure Docker Desktop is installed and running
- Open a terminal window or "default" VirtualBox VM console
- Look around the ready built repositories which are cloned in the container to get you started quickly.
Details
- Docker Toolbox is quirky, no question about it. The desktop shortcuts often don't work for me but going directly to the VirtualBox VM typically does. Open up VirtualBox and make sure the Docker Toolbox VM is running (it is actually called "default"!)
- For me, what generally works is opening up the default VM console directly. Double-click on 1 in the image below to start the default container and open up the container VM console.
- Start looking around! Check the version of ansible on the container. In the example below we are using the disco-immigrant image which comes with ansible 2.9.1. Check out the Ansible playbook repositories and change directory into one to see the example playbooks and try one!...you can find details in the "Run one of the ready built Playbooks!" At this point, once you are in a working docker CLI the process is basically the same across all operating systems.
- Always do a "git pull" in any of the cloned repositories to make sure you are running the latest scripts and playbooks.
- Run your first playbook! You don't need to bring up any device as most use the DevNet AlwaysOn Sandbox devices.
Using Docker Toolbox on Windows Video ~13min
Run one of the ready built Playbooks!
Summary of Steps
- Select a repository to try. In this example we will try the cisco_ios playbook repository
- Enter the git pull command in your container terminal to make sure the repository has the latest code
- Try one of the ready made Playbooks
- Take one of the example playbooks and modify it to suit your needs or create a new Playbook.
Details
1 Move into the desired playbook repository by issuing the change directory command cd cisco_ios from the ansible_local directory
2 Before you try any of the playbooks, its a good idea to execute a git pull so that you have the latest version of the repository.
Example of updated repository:
root@c421cab61f1f:/ansible_local/cisco_ios# git pull remote: Enumerating objects: 5, done. remote: Counting objects: 100% (5/5), done. remote: Compressing objects: 100% (1/1), done. remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0 Unpacking objects: 100% (3/3), done. From https://github.com/cldeluna/cisco_ios 275f642..a8f951f master -> origin/master Updating 275f642..a8f951f Fast-forward ios_show_lab_brief.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) root@c421cab61f1f:/ansible_local/cisco_ios#
This means that updates were made to the repository since the time the Docker image was built
Example of repository already up to date:
root@c421cab61f1f:/ansible_local/cisco_ios# git pull Already up to date. root@c421cab61f1f:/ansible_local/cisco_ios#
*This means that no updates have been made to the repository since the time the Docker image was built
3 Execute the ios_show_lab_brief.yml Playbook.
The comments in the playbook explain in some detail what the playbook is doing and how to execute it.
root@c421cab61f1f:/ansible_local/cisco_ios# ansible-playbook -i hosts ios_show_lab_brief.yml
You will see that the playbook saves different types of output into different text files.
cd to the logs directory and review the results.
root@c421cab61f1f:/ansible_local/cisco_ios# cd logs root@c421cab61f1f:/ansible_local/cisco_ios/logs# tree . |-- ios-xe-mgmt.cisco.com-config.txt |-- ios-xe-mgmt.cisco.com-raw-output.txt |-- ios-xe-mgmt.cisco.com-readable-show-output.txt `-- output_directory 0 directories, 4 files
4 At this point, you can start making these playbooks your own.
Update the hosts file and create your own group of devices. Update the show commands. Start your own Playbook now that you have an Ansible Control server you are ready to go!
Since this is a container, it will leverage your systems network connection so if you VPN into your lab for example, you can use the Control Server on your system to run playbooks against your lab devices and ultimately your production ones!
For additional details please see the full article on The Gratuitous Arp.