AOS-CX Ansible Collection

👍
There are two approaches to using the AOS-CX modules: role and collection. A guide for the latter is detailed here. For the alternative method, see the instructions for using the AOS-CX Ansible Roles under Additional Resources

What is an Ansible collection?

In Ansible, a collection is used to bundle up and distribute Ansible content, including items such as playbooks, roles, modules, and plugins.

📘
Installing the Collection
If you're looking for instructions to install the HPE Aruba Networking AOS-CX Ansible Collection, check out the section Installing the HPE Aruba Networking AOS-CX Collection.

AOS-CX Module Support and Compatibility

All of HPE Aruba Networking's Ansible modules can be run with both Ansible Engine and the Ansible GUIs (Ansible Automation Platform and AWX). The sole requirement is Ansible version 2.9.0 or later and the pyaoscx v2 Python package.

Module	8400	8360	8325	8320	6400-6000	4100i	10000	9300
aoscx_acl	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_acl_interface	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_acl_vlan	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_backup_config	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_banner	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_boot_firmware	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_checkpoint	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_command	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_config	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_dns	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_facts	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_interface	✅	✅	✅	✅	✅	✅	✅
aoscx_l2_interface	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_l3_interface	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_mac	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospf_area	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospf_interface	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospf_router	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospf_vlink	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospfv3_area	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospfv3_router	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_ospfv3_vlink	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_poe	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_qos	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_qos_cos	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_qos_dscp	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_queue	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_queue_profile	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_queue_profile_entry	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_static_mac	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_static_route	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_system	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_upload_config	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_upload_firmware	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_vlan	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_vlan_interface	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_vrf	✅	✅	✅	✅	✅	✅	✅	✅
aoscx_vsx	✅	✅	✅	✅	✅	✅	✅	✅

Platform	Firmware
8400	XL.10.04.001 and later
8360	LL.10.06.001 and later
8325	GL.10.04.001 and later
8320	TL.10.04.001 and later
6400-6300	FL.10.04.001 and later
6200	FL.10.04.001 and later
6100	PL.10.06.001 and later

SSH/CLI Modules

All of our modules in the AOS-CX collection are written to use REST API for connection and configuration, however we do have an option to use SSH as a connection method to execute CLI commands directly onto the switch. 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 collection.

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 node's known_hosts file must contain the target device's public key. Alternatively, host key checking by the control node 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

[defaults]
host_key_checking=False

Limitations and Notes

When using the SSH modules to execute "show" commands, it's important to keep in mind that the output of the executed CLI commands are inherently hidden during Ansible's execution. Therefore it's best practice to save the output of any "show" command to a variable using Ansible's register capabilities and outputting the result. Alternatively, you can run the ansible-playbook command in verbose by adding -v to the command to output during runtime. See the below output for each method:

ansible-control-machine$ansible-playbook show_vlan_debug.yml -i hosts.yml

PLAY [all] *********************************************************************

TASK [Gathering Facts] *********************************************************
ok: [aoscx_1]

TASK [Execute show vlan on the switch and register] ****************************
ok: [aoscx_1]

TASK [Output registered variable] **********************************************
ok: [aoscx_1] => {
    "show_vlan_output": {
        "changed": false,
        "failed": false,
        "stdout": [
            "------------------------------------------------------------------------------------------------------------------\nVLAN  Name                              Status  Reason                  Type        Interfaces                    \n------------------------------------------------------------------------------------------------------------------\n1     DEFAULT_VLAN_1                    up      ok                      default     1/1/2-1/1/28\n11    VLAN11                            down    no_member_port          static      \n12    VLAN12                            down    no_member_port          static      \n13    VLAN13                            down    no_member_port          static      \n255   VLAN255                           down    no_member_forwarding    static      1/1/1,lag220\n4000  VLAN4000                          down    no_member_port          static"
        ],
        "stdout_lines": [
            [
                "------------------------------------------------------------------------------------------------------------------",
                "VLAN  Name                              Status  Reason                  Type        Interfaces                    ",
                "------------------------------------------------------------------------------------------------------------------",
                "1     DEFAULT_VLAN_1                    up      ok                      default     1/1/2-1/1/28",
                "11    VLAN11                            down    no_member_port          static      ",
                "12    VLAN12                            down    no_member_port          static      ",
                "13    VLAN13                            down    no_member_port          static      ",
                "255   VLAN255                           down    no_member_forwarding    static      1/1/1,lag220",
                "4000  VLAN4000                          down    no_member_port          static"
            ]
        ]
    }
}

PLAY RECAP *********************************************************************
aoscx_1                    : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

ansible-control-machine$cat show_vlan_debug.yml
- hosts: all
  collections:
    - arubanetworks.aoscx
  vars:
    ansible_connection: network_cli
  tasks:
    - name: Execute show vlan on the switch and register
      aoscx_command:
        commands: ['show vlan']
      register: show_vlan_output

    - name: Output registered variable
      debug:
        var: show_vlan_output

ansible-control-machine$ansible-playbook show_vlan.yml -i hosts.yml -v
Using /etc/ansible/ansible.cfg as config file

PLAY [all] *********************************************************************

TASK [Gathering Facts] *********************************************************
ok: [aoscx_1]

TASK [Execute show vlan on the switch] *****************************************
ok: [aoscx_1] => {"changed": false, "stdout": ["------------------------------------------------------------------------------------------------------------------\nVLAN  Name                              Status  Reason                  Type        Interfaces                    \n------------------------------------------------------------------------------------------------------------------\n1     DEFAULT_VLAN_1                    up      ok                      default     1/1/2-1/1/28\n11    VLAN11                            down    no_member_port          static      \n12    VLAN12                            down    no_member_port          static      \n13    VLAN13                            down    no_member_port          static      \n255   VLAN255                           down    no_member_forwarding    static      1/1/1,lag220\n4000  VLAN4000                          down    no_member_port          static"], "stdout_lines": [["------------------------------------------------------------------------------------------------------------------", "VLAN  Name                              Status  Reason                  Type        Interfaces                    ", "------------------------------------------------------------------------------------------------------------------", "1     DEFAULT_VLAN_1                    up      ok                      default     1/1/2-1/1/28", "11    VLAN11                            down    no_member_port          static      ", "12    VLAN12                            down    no_member_port          static      ", "13    VLAN13                            down    no_member_port          static      ", "255   VLAN255                           down    no_member_forwarding    static      1/1/1,lag220", "4000  VLAN4000                          down    no_member_port          static"]]}

PLAY RECAP *********************************************************************
aoscx_1                    : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

ansible-control-machine$cat show_vlan.yml
- hosts: all
  collections:
    - arubanetworks.aoscx
  vars:
    ansible_connection: network_cli
  tasks:
    - name: Execute show vlan on the switch
      aoscx_command:
        commands: ['show vlan']

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 collection, 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 arubanetworks.aoscx.aoscx
ansible_connection: Set to arubanetworks.aoscx.aoscx to use REST API modules, network_cli to use SSH/CLI modules, and httpapi for legacy REST API method.
- See below for info on using both REST API modules and SSH/CLI modules on a host
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.
ansible_aoscx_validate_certs: Set to True or False depending if Ansible should bypass validating certificates to connect to AOS-CX. Only required when ansible_connection is set to arubanetworks.aoscx.aoscx
ansible_aoscx_use_proxy: Set to True or False depending if Ansible should bypass environment proxies to connect to AOS-CX. Only required when ansible_connection is set to arubanetworks.aoscx.aoscx.
ansible_httpapi_use_ssl: Must always be True as AOS-CX uses port 443 for REST. Only required when ansible_connection is set to httpapi.
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. Only required when ansible_connection is set to httpapi.

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_network_os=arubanetworks.aoscx.aoscx ansible_connection=arubanetworks.aoscx.aoscx ansible_aoscx_validate_certs=False ansible_aoscx_use_proxy=False ansible_acx_no_proxy=True

YAML

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_acx_no_proxy: True
      ansible_aoscx_validate_certs: False
      ansible_aoscx_use_proxy: False

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=arubanetworks.aoscx.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: arubanetworks.aoscx.aoscx

Example Playbook

Note the inclusion of the collection with collections: and - ...:

---
-  hosts: all
   collections:
     - arubanetworks.aoscx
   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 arubanetworks.aoscx.aoscx. 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:

Set the host variables such that Ansible will connect to the host using REST API, like seen above.
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: arubanetworks.aoscx.aoscx
      ansible_connection: arubanetworks.aoscx.aoscx  # REST API via pyaoscx connection method
      ansible_acx_no_proxy: True
      ansible_aoscx_validate_certs: False
      ansible_aoscx_use_proxy: False

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
  collections:
    - arubanetworks.aoscx
  tasks:
    - name: Create VLAN 300 with description and name
      aoscx_vlan:
        vlan_id: 300
        name: UPLINK_VLAN
        description: This is VLAN 300

- hosts: all
  collections:
    - arubanetworks.aoscx
  vars:
    ansible_connection: network_cli
  tasks:
    - name: Execute show vlan on the switch
      aoscx_command:
        commands: ['show vlan']

👍

What is an Ansible collection?

📘Installing the Collection

AOS-CX Module Support and Compatibility

SSH/CLI Modules

Limitations and Notes

Inventory Setup

Example inventories for REST API (each with one host)

INI

YAML

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

INI

YAML

Example Playbook

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

📘
Installing the Collection