Getting Started with Ansible and AOS-CX

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) :

1. First, you’ll need to get the latest updates for the Linux distribution:
   sudo apt update
sudo apt -y upgrade
2. Then, you’ll need to add the repository to your package installer:
   sudo apt-add-repository --yes --update ppa:ansible/ansible
3. 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

1. 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'

2. 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 execute ansible-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$

3. In the collections directory, install all Ansible requirements with the following command:
   ansible-galaxy install -r requirements.yml

4. 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

5. 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:

1. Create a Sample Inventory
2. Create a Sample Playbook
3. 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 in A.B.C.D format. For IPv6 hosts use a string and enclose in square brackets E.G. '[2001::1]'.
• ansible_user: Username for switch in plaintext format
• ansible_password: Password for switch in plaintext 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.