AOS-CX

The AOS-CX Developer Hub

Welcome to the AOS-CX developer hub. You'll find comprehensive guides and documentation to help you start working with AOS-CX as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Using the AOS-CX Ansible Role

Installing and using the AOS-CX role and setting up the AOS-CX switch

There are two approaches to using the AOS-CX modules: role and collection. A guide for the former is detailed here. For the alternative method, see the instructions for using the AOS-CX Ansible Collection.

In order to use the AOS-CX Ansible role to configure AOS-CX hosts, REST API access must be enabled on each host. Please follow the steps outlined here: Enabling the AOS-CX API.

Watch this video to learn all about AOS-CX role and how to use it in Ansible to configure your AOS-CX switch!

What is an Ansible Role?

In Ansible, a role is used to automatically load certain variables, tasks, and even templates based on a known file structure. Oftentimes, a role is used to configure a target system for a specific purpose (i.e. to play a role), such as a DHCP server. To achieve that, the role can contain all the variables, playbooks, and other files required to configure the host as desired.

Installing the Role

Our AOS-CX Ansible modules are packaged in the AOS-CX role. They are also packaged in the AOS-CX collection. For instructions on installing and using the modules with the alternative collection approach, please see this page.

The AOS-CX role was created solely for the sake of bundling up the AOS-CX Ansible modules for easy distribution and consumption. To install the role, issue the "ansible-galaxy" command: ansible-galaxy install arubanetworks.aoscx_role

If you plan on using the AOS-CX role in an Ansible Tower environment, make sure to provide the full path to a location in which Ansible Tower looks for installed roles. Ansible Tower looks in multiple places for installed roles. For example, one such path is /etc/ansible/roles/ :
ansible-galaxy install arubanetworks.aoscx_role --roles-path /etc/ansible/roles/

To install the latest updated role, simply re-run any of the previous commands. Ansible Galaxy will check to see if the existing role is out of date and install the latest version.

AOS-CX Module Support and Compatibility

All of Aruba's Ansible modules can be run with both Ansible Engine and the Ansible GUIs (Ansible Tower and AWX). The sole requirement is Ansible version 2.8.1 or later.

Module
8400
8325
8320
6400
6300

aoscx_acl

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_acl_interface

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_acl_vlan

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_backup_config

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_banner

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_boot_firmware

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_checkpoint

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_command

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_config

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_dns

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_facts

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_l2_interface

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_l3_interface

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_static_route

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_upload_config

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_upload_firmware

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_vlan

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_vlan_interface

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

aoscx_vrf

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

:white-check-mark+:

Platform
Firmware

8400

XL.10.03.001 and later

8325

GL.10.03.001 and later

8320

TL.10.03.001 and later

6400

FL.10.04.001 and later

6300

FL.10.04.001 and later

SSH/CLI Modules

All of our modules in the AOS-CX role are written to use REST API for connection and configuration with a few exceptions, save for a couple of exceptions. The modules aoscx_config and aoscx_command use SSH to connect to the AOS-CX switch to execute CLI commands. These modules can be used in addition to or instead of the REST API modules provided in the role.

  • To use the SSH/CLI modules aoscx_config and aoscx_command, SSH access must be enabled on your AOS-CX device. It is enabled by default.
    • If necessary, re-enable SSH access on the device with the following command:
      switch(config)# ssh server vrf mgmt
  • The control machine's known_hosts file must contain the target device's public key.
    • Alternatively, host key checking by the control machine may be disabled, although this is not recommended. To disable host key checking, modify the ansible.cfg file (located by default at /etc/ansible/ansible.cfg) to include:
      host_key_checking = false

Limitations and Notes

  • The default command timeout is 30 seconds. If a command takes more than 30
    seconds to execute, the task will time out.
    • If you regularly encounter the command timeout triggered, timeout value is 30 secs error, consider setting the environment variable
      ANSIBLE_PERSISTENT_COMMAND_TIMEOUT to a greater value. See Ansible documentation here.

Inventory Setup

In addition to installing the AOS-CX role, you must also add any AOS-CX hosts to the Ansible inventory. For each AOS-CX switch, the following inventory variables must be defined:

  • ansible_host: IP address of the switch in A.B.C.D format; for IPv6 hosts use a string and enclose the IP address in square brackets (e.g. '[2001::1]')
  • ansible_user: Username for the switch in plaintext
  • ansible_password: Password for the switch in plaintext
  • ansible_network_os: Must always be set to aoscx
  • ansible_connection: Set to httpapi to use REST API modules, and to network_cli to use SSH/CLI modules
    • See below for info on using both REST API modules and SSH/CLI modules on a host
  • ansible_httpapi_use_ssl: (Only required for REST API modules) Must always be True as AOS-CX uses port 443 for REST
  • ansible_httpapi_validate_certs: May be set to either True or False depending on whether Ansible should attempt to validate SSL certificates on the device
  • ansible_acx_no_proxy: May be set to either True or False depending on whether Ansible should bypass environment proxies when connecting to the switch

Example inventories for REST API (each with one host)

INI

aoscx_1 ansible_host=10.0.0.1 ansible_user=admin ansible_password=password ansible_connection=httpapi ansible_network_os=aoscx ansible_httpapi_validate_certs=False ansible_httpapi_use_ssl=True ansible_acx_no_proxy=True

YAML

all:
  hosts:
    aoscx_1:
      ansible_host: 10.0.0.1
      ansible_user: admin
      ansible_password: password
      ansible_connection: httpapi  # REST API connection method
      ansible_network_os: aoscx
      ansible_httpapi_validate_certs: False
      ansible_httpapi_use_ssl: True
      ansible_acx_no_proxy: True

Example inventories for SSH/CLI (each with one host)

INI

aoscx_1 ansible_host=10.0.0.1 ansible_user=admin ansible_password=password ansible_connection=network_cli ansible_network_os=aoscx

YAML

all:
  hosts:
    aoscx_1:
      ansible_host: 10.0.0.1
      ansible_user: admin
      ansible_password: password
      ansible_connection: network_cli  # SSH connection method
      ansible_network_os: aoscx

Example Playbook

Note the inclusion of the role with roles: and - role: ...:

---
-  hosts: all
   roles:
    - role: arubanetworks.aoscx_role
   tasks:
     - name: Create L3 Interface 1/1/3
       aoscx_l3_interface:
        interface: 1/1/3
        description: Uplink_Interface
        ipv4: ['10.20.1.3/24']
        ipv6: ['2001:db8::1234/64']

Using Both REST API and SSH/CLI Modules on a Host

To use both REST API and SSH/CLI modules on the same host, you must create separate plays such that each play uses either only REST API modules or only SSH/CLI modules. A play cannot mix and match REST API and SSH/CLI module calls.

In each play, ansible_connection must possess the appropriate value according to the modules used. If the play uses REST API modules, that value should be httpapi. If the play uses SSH/CLI modules, that value should be network_cli.

A recommended approach to successfully using both types of modules for a host is as follows:

  1. Set the host variables such that Ansible will connect to the host using REST API, like seen above.
  2. In the playbook, in each play wherein the SSH/CLI modules are used, set the ansible_connection to network_cli.

The inventory should look something like this:

all:
  hosts:
    aoscx_1:
      ansible_host: 10.0.0.1
      ansible_user: admin
      ansible_password: password
      ansible_network_os: aoscx
      ansible_connection: httpapi  # REST API connection method
      ansible_httpapi_validate_certs: False
      ansible_httpapi_use_ssl: True
      ansible_acx_no_proxy: True

and the playbook like this (note how the second play, which uses the SSH/CLI module aoscx_command, sets the ansible_connection value accordingly):

- hosts: all
  roles: 
    - role: arubanetworks.aoscx_role
  tasks:
    - name: Adding or Updating Banner
      aoscx_banner:
        banner_type: banner
        banner: "Hi!"

- hosts: all
  roles: 
    - role: arubanetworks.aoscx_role
  vars:
    ansible_connection: network_cli
  tasks:
    - name: Execute show run on the switch
      aoscx_command:
        commands: ['show run']

Updated 3 months ago



Using the AOS-CX Ansible Role


Installing and using the AOS-CX role and setting up the AOS-CX switch

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.