Getting Started with Ansible and AOS-CX
Ansible: a link that elegantly and effortlessly bridges the gap between programmer and network engineer
Ansible is an open-source automation framework that was created by Ansible and now maintained by RedHat. Ansible is an orchestration tool that automates provisioning, configuration management, and application deployment.
In 2019, HPE Aruba Networking became an official Ansible partner, and currently supports Ansible for both the AOS-Switch and AOS-CX operating systems.
How Ansible Works
Ansible is an agentless automation tool architected on Python.
Ansible requires a "control node," a Linux (or MacOS) workstation on which Ansible Engine is installed. Ansible Engine, the core of Ansible, provides a command-line interface through which Ansible commands are executed and on which the execution results are displayed, along with other relevant output. Ansible Engine also contains the Ansible modules and plugins, Python code used to connect to and configure target systems.
Ansible modules typically connect to target devices via SSH. Our AOS-CX and AOS-Switch modules leverage the REST APIs on those respective operating systems to communicate.
Already Using Ansible?
If you are familiar with Ansible and have already deployed it in your environment, skip ahead to the sections that cover installing the AOS-CX Ansible Collection.
GitHub & Ansible Galaxy
Find the AOS-CX Collection on GitHub and for the most recent HPE Aruba Networking Ansible content visit Ansible Galaxy.
Installing Ansible
Refer to Ansible Installation Guide
Please refer to the Ansible Installation Guide for up-to-date information regarding installation, or if you are having trouble installing Ansible.
Prerequisites for Ansible Installation
Main point of requirement is a "Control Node" which is essentially a Linux machine. Some Linux distributions come with Python2 and/or Python3 pre-installed. Ansible requires Python2.7 or Python3.5 or later.
Due to the HPE Aruba Networking AOS-CX Collection requires Python 3.5 or later, further instructions on this page will be specific to Python3.5+
Check the Python version on the desired control machine and verify the output:
administrator@Ansible-Ubuntu:~$ python3 --version
Python 3.6.9
If Python is not installed, install Python through the package installer of your Linux distribution. The following commands apply to Ubuntu 18.04 or later:
- Python3.5 or later:
sudo apt install python3.5
sudo apt install python3.6
sudo apt install python3.7
sudo apt install python3.8
Installing Ansible on Ubuntu 18.04 LTS or 20.04 LTS
Ansible and Windows
Ansible is only compatible with Unix-like operating systems, such as Linux or macOS. Windows is not supported. For instructions on how to install Ansible on other operating systems, please see the Ansible Installation Guide linked above.
Installing Ansible using apt-get (or another package installer if you're using another operating system) :
- First, you’ll need to get the latest updates for the Linux distribution:
sudo apt update
sudo apt -y upgrade
- Then, you’ll need to add the repository to your package installer:
sudo apt-add-repository --yes --update ppa:ansible/ansible
- Then, you can install Ansible:
sudo apt-get install ansible
Validate the Ansible Installation
Check the Ansible version on the terminal and verify the output. Below is an example install with Ansible v2.11 running Python 3.8:
administrator@administrator-virtual-machine:~$ ansible --version
ansible [core 2.11.5]
config file = /etc/ansible/ansible.cfg
configured module search path = ['/home/administrator/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python3/dist-packages/ansible
ansible collection location = /home/administrator/.ansible/collections:/usr/share/ansible/collections
executable location = /usr/bin/ansible
python version = 3.8.10 (default, Jun 2 2021, 10:49:15) [GCC 9.4.0]
jinja version = 2.10.1
libyaml = True
Another quick way to validate that your Ansible installation is successful is to use the 'ansible' command to ping the server itself.
ansible localhost -m ping
Below is an example command and successful result.
administrator@administrator-virtual-machine:~$ ansible localhost -m ping
localhost | SUCCESS => {
"changed": false,
"ping": "pong"
}
Installing the HPE Aruba Networking AOS-CX Collection
Our AOS-CX Ansible modules are packaged in the AOS-CX collection.
The AOS-CX Ansible modules are also hosted on the HPE Aruba Networking public GitHub repository aoscx-ansible-collection. This repo is useful to look at additional documentation as well as installing prerequisite Python libraries from the 'requirements.txt' file.
Requirements of the AOS-CX Collection
- Python 3.5 or later
- Ansible 2.9.0 or later
- Minimum supported AOS-CX firmware version 10.04
- Enable REST on your AOS-CX device with the following commands:
switch(config)# https-server rest access-mode read-write
switch(config)# https-server vrf mgmt
In version 3.0.0+ of the AOS-CX collection, we've redesigned the collection to make use of our Python SDK for AOS-CX Pyaoscx v2 to handle all REST-API based calls and modules.
This requires the pyaoscx
package version 2.6.0 or later, as well as additional libraries mentioned in the 'requirements.txt' file.
Users can manually install a specific version of the pyaoscx package with the command:
pip3 install pyaoscx>=2.6.0
.
For a detailed description of requirements and installation steps refer to the documentation of the AOS-CX collection.
Installation Process
- Install the collection, with the
ansible-galaxy
command:
ansible-galaxy collection install arubanetworks.aoscx
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Starting collection install process
Installing 'ansible.netcommon:2.4.0' to '/home/administrator/.ansible/collections/ansible_collections/ansible/netcommon'
Installing 'arubanetworks.aoscx:3.0.1' to '/home/administrator/.ansible/collections/ansible_collections/arubanetworks/aoscx'
Installing 'ansible.utils:2.4.1' to '/home/administrator/.ansible/collections/ansible_collections/ansible/utils'
- After installing the collection using the
ansible-galaxy
command, change into the collections directory where the AOS-CX Ansible collection (arubanetworks.aoscx) was installed. To find the installation location of the collection executeansible-galaxy collection list
.
ansible-control-machine$cd /home/administrator/.ansible/collections/ansible_collections
ansible-control-machine$ansible-galaxy collection list
# /home/administrator/.ansible/collections/ansible_collections
Collection Version
------------------------ -------
ansible.netcommon 2.3.0
ansible.posix 1.1.1
ansible.utils 2.3.1
arubanetworks.aos_switch 1.4.0
arubanetworks.aoscx 3.0.1
ansible-control-machine$cd /home/administrator/.ansible/collections/ansible_collections/arubanetworks/aoscx/
ansible-control-machine$ls
CONTRIBUTING.md FILES.json meta README.md requirements.yml
docs MANIFEST.json plugins requirements.txt
ansible-control-machine$
-
In the collections directory, install all Ansible requirements with the following command:
ansible-galaxy install -r requirements.yml
-
In the collections directory, install all the Python requirements in the requirements.txt file with the following command:
python3 -m pip install -r requirements.txt
- Alternatively, these pre-requisite libraries can be installed using pip3 from the repo:
python3 -m pip install -r https://raw.githubusercontent.com/aruba/aoscx-ansible-collection/master/requirements.txt
- Once all the requirements are installed change back into your working directory and begin automating!
AOS-CX Collection and Ansible Automation Platform
If you plan on using the AOS-CX collection in the Ansible Automation Platform, please see our guide on Using AOS-CX Collection in the Ansible Automation Platform.
Upgrading Existing HPE Aruba Networking AOS-CX Collection
To upgrade your existing installation of the collection to the latest updated collection, simply re-run the appropriate "ansible-galaxy" command listed above with the -f
option. Ansible will check to see if the existing collection is out of date and if so, install the latest version.
ansible-galaxy collection install arubanetworks.aoscx -f
Validate AOS-CX Collection Installation
Here is a quick example playbook to validate that the AOS-CX collection has been correctly installed. Below is a sample inventory that will be used in the playbook. More information on inventories can be found in the Ansible Inventories page.
In this below workflow you will:
- Create a Sample Inventory
- Create a Sample Playbook
- Run the Sample Playbook
Sandbox Environment
It is recommended to be in a test or working directory, in the below example we created a folder named test_ansible on the Desktop where Ansible is installed:
~/Desktop/test_ansible
Sample Inventory
In order for Ansible to configure your AOS-CX switch we need to define the necessary attributes Ansible needs in order to communicate with the device. This is done through the inventory file. Copy the below contents into a new file on your Ansible control node, modify the following values to match your AOS-CX device:
ansible_host
: IP address of switch inA.B.C.D
format. For IPv6 hosts use a string and enclose in square brackets E.G.'[2001::1]'
.ansible_user
: Username for switch inplaintext
formatansible_password
: Password for switch inplaintext
format
all:
hosts:
aoscx_1:
ansible_host: 10.0.0.1
ansible_user: admin
ansible_password: password
ansible_network_os: arubanetworks.aoscx.aoscx
ansible_connection: arubanetworks.aoscx.aoscx # REST API via pyaoscx connection method
ansible_aoscx_validate_certs: False
ansible_aoscx_use_proxy: False
ansible_acx_no_proxy: True
Sample Playbook
This playbook uses REST API to configure a VLAN on the switch, REST API must be enabled on your AOS-CX device before executing the playbook. Do not execute on a production switch, ensure your device is in a state that can be tested. Copy the contents of the below file onto your machine and save the file.
- hosts: all
collections:
- arubanetworks.aoscx
gather_facts: False
tasks:
- name: Create VLAN 300 with description and name
aoscx_vlan:
vlan_id: 300
name: UPLINK_VLAN
description: This is VLAN 300
Run the sample playbook
Run the ansible-playbook
command below in order to run the Sample Playbook against the specified Sample Inventory. In this example, the playbook and inventory files are in the same directory:
ansible-playbook sample_playbook.yml -i sample_inventory.yml
administrator@administrator-virtual-machine:~/Desktop/test_ansible$ ansible-playbook sample_playbook.yml -i sample_inventory.yml
PLAY [all] *********************************************************************
TASK [Create VLAN 300 with description and name] *******************************
changed: [aoscx_1]
PLAY RECAP *********************************************************************
aoscx_1 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Once the playbook has completed, you should be able to see the new VLAN 300 on your CX switch!
vlan 300
name UPLINK_VLAN
description This is VLAN 300
Additional AOS-CX Workflows
For more practice using Ansible with the AOS-CX Collection - check out our ready-to-use workflows on our AOS-CX Ansible Workflows Github!
Additional HPE Aruba Networking Ansible support
For issues regarding the collection submit on the AOS-CX Collection GitHub.
Installation of AOS-Switch modules can be found through Ansible Galaxy.
Updated about 2 months ago