Using AWX to run Cisco IOS Ansible playbook

6 min readJul 7, 2021

This article is for the user that not familiar with the AWX installed on top of the Minikube (K8S) and facing issue to run your first Ansible playbook.

Before starting the setup in AWX WEB GUI, we have to complete the below setup in the AWX server first. You may skip the steps if you already known how to do it.

Creating PV/PVC

For storing the Ansible playbook permanently, we must create the persistence storage for the pods mount the/var/lib/awx/projects folder to the PVC.

# Create the pvc yaml file.
$ vi awx-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: awx-pvc #This is the name of pv/pvc, can be changed
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 8Gi #This can be changed based on your requirement.# Create the PVC using the "kubectl create -f" command
# PV will be created automatically and bound to the PVC
$ kubectl create -f awx-pvc.yaml# To check the PV and PVC using "kubectl" command
$ kubectl get pvc,pv

You should see the PVC/PV by issuing the kubectl command and both of them should be bound state.

$ kubectl get pvc,pv | grep awx-pvc
persistentvolumeclaim/awx-pvc                        Bound    pvc-e2f126e6-115f-4f20-99da-40ed97306eb0   8Gi        RWX            standard       27d
persistentvolume/pvc-e2f126e6-115f-4f20-99da-40ed97306eb0   8Gi        RWX            Delete           Bound    default/awx-pvc                        standard                27d

Verify PV is created

Switch to “sudo” or “root” and then
cd /var/lib/docker/volumes/minikube/_data/hostpath-provisioner/default , you should see awx-pvc folder is created.
We will configure the volume mount in the AWX pods so that the pods can use this folder for store the project (Ansible playbook).

# cd /var/lib/docker/volumes/minikube/_data/hostpath-provisioner/default
# ls
awx-pvc

Volume mount on AWX pod

Remember that there is a awx-demo.yaml used for setup the AWX deployment? We have to open it up again and edit the storage option so that the pods can mount to the PVC volume we created.

# Added the last 2 lines to your awx-demo.yaml
$ vi awx-demo.yaml 
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx-demo
spec:
  service_type: nodeport
  ingress_type: none
  hostname: awx-demo.example.com
  projects_persistence: true
  projects_existing_claim: awx-pvc# To recreate the pod with the volume mount we set
$ kubectl delete -f awx-demo.yaml
$ kubectl create -f awx-demo.yaml# Describe the awx-demo pod 
# you should see the /var/lib/awx/projects mount to the awx-pvc
$ kubectl describe pod awx-demo-57c8bb4484-2c5m5 | egrep awx-demo-projects: -A 3
  awx-demo-projects:
    Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName:  awx-pvc
    ReadOnly:   false

Copy modules from Ansible Galaxy Collection

To use Cisco IOS and netcommon module, we have to download the tarball from the Ansible Galaxy website and then untar them to the “ansible-collection” folder in the AWX server.

2 ways to download the tarball:

Download the tarball from Ansible Galaxy website:
https://galaxy.ansible.com/cisco/ios
https://galaxy.ansible.com/ansible/netcommon

Download page of Cisco IOS module tarball

Download page of netcommon module tarball

Click “Download tarball” from the website and then upload to your offline AWX server.

2. Using wget to download the tarball if your AWX server can access internet

$ wget https://galaxy.ansible.com/download/cisco-ios-2.3.0.tar.gz
$ wget https://galaxy.ansible.com/download/ansible-netcommon-2.2.0.tar.gz

Copy the module to the ‘ansible-collection’ folder

Use find to search for the path of ansible-collection

$ sudo find / -name ansible_collections

The path name to untar the module tarball should be similar like:

/var/lib/docker/volumes/minikube/_data/lib/docker/overlay2/23447b8d007542df8a83599f03de1ed20246da67f88999b34e2e65812c488a63/diff/usr/share/ansible/collections/ansible_collections/amazon

** The bold font should be different from your AWX server; the correct path should be the one with ‘minikube’

Create the directories and untar the Cisco IOS and netcommon module to that folder:

# To create directories for Cisco IOS and netcommon
$ sudo mkdir -p /var/lib/docker/volumes/minikube/_data/lib/docker/overlay2/23447b8d007542df8a83599f03de1ed20246da67f88999b34e2e65812c488a63/diff/usr/share/ansible/collections/ansible_collections/cisco/ios$ sudo mkdir -p /var/lib/docker/volumes/minikube/_data/lib/docker/overlay2/23447b8d007542df8a83599f03de1ed20246da67f88999b34e2e65812c488a63/diff/usr/share/ansible/collections/ansible_collections/ansible/netcommon# Untar the tarball to the directories
$ sudo tar -xvf cisco-ios-2.3.0.tar.gz --directory /var/lib/docker/volumes/minikube/_data/lib/docker/overlay2/23447b8d007542df8a83599f03de1ed20246da67f88999b34e2e65812c488a63/diff/usr/share/ansible/collections/ansible_collections/cisco/ios$ sudo tar -xvf ansible-netcommon-2.2.0.tar.gz --directory /var/lib/docker/volumes/minikube/_data/lib/docker/overlay2/23447b8d007542df8a83599f03de1ed20246da67f88999b34e2e65812c488a63/diff/usr/share/ansible/collections/ansible_collections/ansible/netcommon

Cool! We can proceed to setup in AWX WEB GUI now.

Inventories

Setup the inventory from “Inventories” option

Hosts

Setup the hosts from “Hosts” option. The host in this example is a Cisco IOS router (IP address is 192.168.99.2).
Assigned this host to the “Inventory” that we created in previous step (“awx-demo”).

---
ansible_host: 192.168.99.2
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: cisco.ios.ios

** Change the 192.168.99.2 to your router IP address.

Credentials

To create the credential for the Cisco IOS

Credential type: Machine
Privilege Escalation Method: enable
Privilege Escalation Password: <your enable password>

Projects

To create the project, you must create a new folder in your PV (in this case is awx-pvc).
Below is the example for creating a new folder “awx-demo-project”.

$ sudo -i
# mkdir -p /var/lib/docker/volumes/minikube/_data/hostpath-provisioner/default/awx-pvc/awx-demo-project

** Ansible playbook should be put under this folder.

Go to the AWX WEB GUI, select the “Projects” option. In this page, the “Playbook Directory” drop down list should show the folder we created in previous step (in this case is “awx-demo-project”).
Select this directory and “Save”.

Job Template

Before creating the job template, let us create a simple Ansible playbook first.
This Ansible playbook will be created in the folder we created in the previous “Project” section (“awx-demo-project”)

$ cd /var/lib/docker/volumes/minikube/_data/hostpath-provisioner/default/awx-pvc/awx-demo-project$ sudo nano awx-demo-playbook.yaml
- name: cisco_sh_ver
  hosts: all
  gather_facts: true 
  tasks:
  - name: run show version on remote devices
    cisco.ios.ios_command:
     commands:
     - show version       
  - name: show run on remote devices
    become: true
    cisco.ios.ios_command:
     commands: 
     - show run

To run the Ansible playbook we created, select the option “Templates” and then click on the “Add” to show the drop down list.
Select the “Add job template” from the drop down list.

Inventory: awx-demo (created in the Inventories section)
Project: awx-demo-project (created in the Project section)
Playbook: awx-demo-playbook.yaml (created in the previous step)
Credential: awx-demo-credential (created in the Credentials section)
Verbosity: 3 (Debug) (for getting more information to verify our playbook is working)

Click “Save”.

Run job

Horray, all set and let us verify our playbook can be run correctly.
Let’s click on the “Templates” and then click on the rocket sign of the job template “awx-show-command-demo”