aruba/aruba-central-ansible-role

Ansible Role for Aruba Central

aruba-central-ansible-role

This Ansible Network role provides a set of platform dependent configuration management modules and plugins specifically designed for Aruba Central, which is a cloud-based Network Management System.

Requirements

• Python 3.5+

• Ansible 2.9 or later

  • Ansible 2.10+ requires ansible.netcommon collection to be installed

• Minimum supported Aruba Central firmware is 2.5.2

• Install all Ansible requirements, with the following command:

  ansible-galaxy install -r requirements.yml
  

• Install all Python requirements with the following command:

  pip install -r requirements.txt
  

Installation

Through Galaxy:

ansible-galaxy install arubanetworks.aruba_central_role

Through Github, use the following command. Use option -f to overwrite current role version:

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

Notes

• The modules in this role use Central's REST API. For information on REST API and how to obtain an access for using REST API, visit the Aruba Developer Hub: Getting Started with REST API
• An API token must be created for a user on Aruba Central's API Gateway and a valid, non-expired access_token must be used. For more information on how to get started with the API Gateway you can also watch this YouTube Video.
• A valid access token can be used in an Inventory file as mentioned in the Inventory section.
• Ensure that the access token was created with "Network Operations" selected in the Application drop-down list, while adding a new token on the API Gateway.
• Once a new token is generated, it will have an access_token and a refresh_token.
• An access token is valid for a period of 7200 seconds or two hours. After two hours, it will expire and a new token needs to be created. The token expiry time is currently not configurable.
• The refresh_token along with the client_id and client_secret are used to renew the access token. This functionality is implemented in this role by using an Inventory Plugin. You can either use an Inventory file or use an Inventory Plugin Config file for using the plugin.
• More details on how to use this plugin config file with tokens and other credentials for auto-renew of tokens is mentioned below in the Inventory Plugin Config File section.

Inventory/Host File

There are two ways in which you can use an inventory or host file with the Aruba Central Ansible Role:

1. Inventory - Host file which tells Ansible the required httpapi plugin to use with some other details and the access token.
2. Inventory Plugin Config File or Inventory Source
   • An inventory source file which is used by the inventory plugin.
   • A typical inventory plugin implementation has a plugin script (usually written in Python), and an inventory source (in this case it is a YAML file).
   • Based on Ansible Documentation, Inventory sources are the input strings that inventory plugins work with. An inventory source can be a path to a file or to a script, or it can be raw data that the plugin can interpret to dynamically generate inventory variables.
   • Only .yml files with Inventory Plugin Config File variables are accepted as an inventory source by the inventory plugin for this role.

• You can use either of the above files depending on your need.
  • If do not require auto-renew of tokens, use the simple Inventory file
  • Or, if you wish to have the auto-renew of tokens, use an Inventory Plugin Config File for the Inventory Plugin.

Inventory

Inventory Variables

The variables that should be defined in your inventory for your Aruba Central account are:

• ansible_host: Cluster-specific Base-URL for the API Gateway on Aruba Central in FQDN format, which can be found in the API Documentation URL on API Gateway
• ansible_connection: Must always be set to httpapi
• ansible_network_os: Must always be set to aruba_central
• ansible_httpapi_use_ssl: Must always be set to True
• ansible_httpapi_central_access_token: Aruba Central's API access token

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 is an inventory source file which is utilized by the inventory plugin to dynamically generate an inventory with all the options (as shown above in the simple Inventory file) required by the HttpAPI Connection Plugin.
• User needs to create a config file which has the plugin name and other central credentials.

Caveats

• Conventionally, an Inventory Plugin can not be shipped within a role since Ansible executes the Inventory Plugin before execution of the Playbook or Role. More information can be found on Ansible Docs.
  • Therefore, until we publish the Aruba Central Ansible Collection, you need to perform the following workaround for using the custom inventory plugin for this Ansible role for Central - which will take care of the auto-renew of tokens.

Method 1:

• Copy the central_inventory.py inventory plugin file from GitHub and store it within an inventory_plugins directory in your playbooks directory.
• Your playbooks directory should have the following structure:

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

• Where **inv_src.yml** or any other **.yml** file with a different name can act as the Inventory Plugin Config file. Sample Inventory Plugin Config File and the variables it uses are given below.
• Inventory Plugin Config File should not be used with Ansible Vault since the inventory plugin needs to write the renewed refresh and access tokens back to the plugin config file.
• Initially the user has to ensure that a valid Access and Refresh Token has been entered in the Inventory Plugin Config file for the first time. If both tokens are invalid, the inventory plugin will modify the file with <Enter a Valid Access/Refresh Token> message in the Inventory Plugin Config file and the execution will fail with "Unauthorized" failure.
• Central's refresh_token is valid for a period of 14 days. If not used until 14 days, the token will be revoked and a new token has to be created. Refresh token validity is non-configurable at the moment.

Method 2:

• Once the role is installed, go to the roles directory. Use the following commands to get the path where role is installed and move inventory_plugins directory with the plugin file.

$ ansible-galaxy role list 

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

• Select the path and go to the roles directory
• The role name might differ based on how you chose to install it
• Once you have the path 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

The variables that should be defined in your inventory plugin config file for your Aruba Central account are:

• access_token: Aruba Central's API Access Token.
• api_gateway: Cluster-specific Base-URL for the API Gateway on Aruba Central in FQDN format, which can be found in the API Documentation URL on API Gateway
• client_id: Aruba Central's API Client ID
• client_secret: Aruba Central's API Client Secret
• host: Must always be set to central
• plugin: Must always be set to central_inventory
• refresh_token: Aruba Central's API Refresh token

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 role installed through Galaxy set 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 role installed through Github set 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

• Where inventory.yml could either be a simple inventory file or it could be an inventory plugin config file (inventory source).
• Make sure to have the central_inventory.py in the inventory_plugins/ directory before executing the playbook using the inventory plugin config file.

Contribution

At Aruba Networks we're dedicated to ensuring the quality of our products, so if you find any issues at all please open an issue on our Github and we'll be sure to respond promptly!

For more contribution opportunities follow our guidelines outlined in our CONTRIBUTING.md

License

MIT

Author Information

• Jay Pathak (@jayp193)
• Derek Wang (@derekwangHPEAruba)

aruba-central-ansible-role's Issues

Play does not fail with status 400 response

When using the following in a playbook, incorrectly using strings for template group values does not result in a failed play. The groups are (correctly) not created but the 400 status doesn't seem to bubble up.

Playbook

---
- hosts: all
  roles:
  - arubanetworks.aruba_central_role
  tasks:
  - name: bug test.
    central_groups:
      action: create
      group_name: "bugtest"
      group_attributes:
        group_password: "bugtest"
        template_group:
          wired: "true"
          wireless: "true"
    register: create_me
  - debug:
      var: create_me      

Output

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

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

TASK [bug test.] *************************************************************************************************************************
ok: [arubacentral]

TASK [debug] *****************************************************************************************************************************
ok: [arubacentral] => {
    "create_me": {
        "changed": false,
        "failed": false,
        "msg": {
            "detail": "u'true' is not of type 'boolean'",
            "status": 400,
            "title": "Bad Request",
            "type": "about:blank"
        },
        "response_code": 400
    }
}

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

AWX - HTTP Error 401: Unauthorized

Hi,
Referring to this thread: https://community.arubanetworks.com/discussion/authentication-issue-accessing-aruba-central-from-awx

Using the same methods, even doing a curl command using the same variables - success.
However as soon as it's done through AWX, HTTP Error 401: Unauthorized.
Simple Inventory, simple playbook, just like the readme instructs.
Is there some crucial step missing or what could be the issue?

Sample Play Issues

< TASK [Get all the UI and Template Groups on Central] >
 ------------------------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

task path: /home/aruba-test/Documents/aruba-test/sample.yml:7
fatal: [aruba]: FAILED! => {"changed": false, "msg": "value of action must be one of: get_groups, get_group_mode, clone, update, create, delete, got: get"}

It's used in the sample plays:

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

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

The "action" does not seem to accurately reflect what the module is capable of. The spacing also appears incorrect - will try to addres in PR.

Firmware Compliance for Groups?

Love the role! I was wondering if you are all planning on adding setting firmware compliance for groups with support for scheduling?

Support `/configuration/v3/groups`

Aruba Central has an API endpoint /configuration/v3/groups. However, the endpoint is not implemented yet.

• Ref. Aruba Central: API Reference: /configuration/v3/groups

TypeError in Python3

Description:
TypeError when using "+" operand for type(dict_items) + type(dict_items)

aruba-central-ansible-role/library/central_sites.py

Line 413 in 6203de0

data = dict(site_dict.items() + addr_dict.items())

aruba-central-ansible-role/library/central_sites.py

Line 415 in 6203de0

data = dict(site_dict.items() + geo_dict.items())