arubanetworks.aruba_central_role

aruba-central-ansible-role

This Ansible Network role includes special tools for managing Aruba Central, which is a cloud-based system for network management.

Requirements

Python 3.5 or higher
Ansible 2.9 or newer
- For Ansible 2.10 or above, you need to install the ansible.netcommon collection.
The lowest supported Aruba Central firmware version is 2.5.2.

To set up all Ansible requirements, run:

ansible-galaxy install -r requirements.yml

To install all Python requirements, use:
```
pip install -r requirements.txt
```

Installation

To install through Galaxy:

ansible-galaxy install arubanetworks.aruba_central_role

To install via GitHub, use the following command. The -f option overwrites the current version:

ansible-galaxy install git+https://github.com/aruba/aruba-central-ansible-role.git

Notes

The modules in this role use the REST API from Aruba Central. For details on the REST API and how to gain access, check the Aruba Developer Hub: Getting Started with REST API.
You must create an API token for a user on Aruba Central's API Gateway and use a valid, non-expired access_token. For more details, you can watch this YouTube Video.
A valid access token can be specified in an Inventory file as explained in the Inventory section.
When creating a new token on the API Gateway, ensure "Network Operations" is selected in the Application dropdown.
Once you generate a new token, you'll get an access_token and a refresh_token.
An access_token is valid for 7200 seconds (two hours). After that, you'll need to create a new one. The expiry time cannot be changed.
The refresh_token, along with client_id and client_secret, is used to update the access token. This function is part of this role through an Inventory Plugin. You can use either an Inventory file or an Inventory Plugin Config file.
Details on using the plugin config file with tokens for automatic renewals can be found in the Inventory Plugin Config File section.

Inventory/Host File

You can manage your inventory or host file with the Aruba Central Ansible Role in two ways:

Inventory
- A host file that tells Ansible which httpapi plugin to use and provides other details, including the access token.
Inventory Plugin Config File or Inventory Source
- A file used by the inventory plugin.
- A typical inventory plugin setup has a script (often in Python) and an inventory source (like a YAML file).
- According to Ansible Documentation, Inventory sources are inputs that inventory plugins work with. They can be paths to files or scripts, or raw data for dynamic inventory generation.
- Only .yml files with Inventory Plugin Config File variables are accepted by this role's inventory plugin.

Choose the file type based on your needs:
- If automatic token renewal isn’t required, use the simple Inventory file.
- If you want automatic renewal, use an Inventory Plugin Config File.

Inventory Variables

Your inventory for the Aruba Central account should include the following variables:

ansible_host: The Base URL for the API Gateway in FQDN format, found in the API documentation.
ansible_connection: Must be set to httpapi.
ansible_network_os: Must be set to aruba_central.
ansible_httpapi_use_ssl: Must be set to True.
ansible_httpapi_central_access_token: The API access token for Aruba Central.

Sample Inventory:

YAML

all:
  hosts:
    central:
      ansible_host: apigw-prod2.central.arubanetworks.com
      ansible_connection: httpapi
      ansible_network_os: aruba_central
      ansible_httpapi_use_ssl: True
      ansible_httpapi_central_access_token: CnjDaXXxvnjrvJRwxxxxXXxxXXXXxxxx

INI

arubacentral ansible_host=apigw-prod2.central.arubanetworks.com  ansible_connection=httpapi ansible_network_os=aruba_central  ansible_httpapi_use_ssl=True  ansible_httpapi_central_access_token=CnjDaXXxvnjrvJRwxxxxXXxxXXXXxxxx

Inventory Plugin Config File

This file is used by the inventory plugin to create an inventory dynamically with all necessary options for the HttpAPI Connection Plugin.
You need to create a config file that includes the plugin name and other credentials.

Caveats

Inventory Plugins can't be included in a role since Ansible runs them before executing a Playbook or Role. More information is available in Ansible Docs.
Until we launch the Aruba Central Ansible Collection, you need to do a workaround to use the custom inventory plugin for token auto-renewal.

Method 1:

Copy the central_inventory.py inventory plugin from GitHub and store it in an inventory_plugins directory within your playbook directory. Your directory structure should look like this:

playbooks_dir
+-- playbook1.yml
+-- playbook2.yml
+-- inv_src.yml
+-- inventory_plugins/
|   +-- central_inventory.py

Where inv_src.yml or any other .yml file can serve as the Inventory Plugin Config file. Refer to the provided Sample Inventory Plugin Config File for details.
Don’t use the Inventory Plugin Config File with Ansible Vault, as it needs to write updated tokens back into the config file.
Initially, ensure a valid Access and Refresh Token is entered in the Inventory Plugin Config file. If both tokens are invalid, the file will show <Enter a Valid Access/Refresh Token> and execution will fail with an "Unauthorized" error.
Refresh tokens are valid for 14 days; if not used within that time, they will expire and a new token must be created. Their validity is currently not configurable.

Method 2:

After installing the role, navigate to the roles directory. Use these commands to find the installation path and move the inventory_plugins directory with the plugin:

$ ansible-galaxy role list 

------------------output-----------------
# /home/admin/.ansible/roles
- arubanetworks.aruba_central_role, 0.2.1

Go to the role's directory based on how it was installed.
Move the inventory plugin directory to your playbooks directory:

$ cd /home/admin/.ansible/roles
$ cd arubanetworks.aruba_central_role
or
$ cd aruba-central-ansible-role

$ mv inventory_plugins/ <path_to_playbooks_directory>

Inventory Plugin Config Variables

Your inventory plugin config file should include these variables for your Aruba Central account:

access_token: The API Access Token for Aruba Central.
api_gateway: The Base URL for the API Gateway in FQDN format, found in the API documentation.
client_id: The API Client ID for Aruba Central.
client_secret: The API Client Secret for Aruba Central.
host: Must be set to central.
plugin: Must be set to central_inventory.
refresh_token: The API Refresh Token for Aruba Central.

Sample Inventory Plugin Config File:

YAML

access_token: CnjDaXXxvnjrvJRwxxxxXXxxXXXXxxxx
api_gateway: apigw-prod2.central.arubanetworks.com
client_id: FOqWxx124ASdfS36HqKIeXXzZ
client_secret: O2RfdKgiS13GhswdrWAIEueMPOxxZxX
host: central
plugin: central_inventory
refresh_token: X12daE6BFhk8QqqzzeifHTYxxZZ12XxX

Example Playbooks

Including the Role

If you installed the role through Galaxy, set the role to arubanetworks.aruba_central_role:

---
-  hosts: all
   roles:
     - role: arubanetworks.aruba_central_role
   tasks:
   - name: Get all the UI and Template Groups on Central
     central_groups:
       action: get_groups
       limit: 20
       offset: 0

If installed through GitHub, set the role to aruba-central-ansible-role:

---
-  hosts: all
   roles:
     - role: aruba-central-ansible-role
   tasks:
   - name: Get all the UI and Template Groups on Central
     central_groups:
       action: get_groups
       limit: 20
       offset: 0

Playbook Execution

ansible-playbook playbook.yml -i inventory.yml

Here, inventory.yml could be a simple inventory file or an inventory plugin config file.
Ensure the central_inventory.py file is in the inventory_plugins/ directory before executing the playbook with the config file.