Using Python REST API SDK

Aruba Central is an unified cloud-based network management and configuration platform for campus, branch, remote and data center networks. There are various needs for automation and programmability like automating repetitive tasks, configuring multiple devices, monitoring and more. This python package is to programmatically interact with Aruba Central via REST APIs.

How to Install?

Install using Python package manager

pip3 install pycentral

To install with extras, which displays log messages in color, install package with the following command

pip3 install pycentral[colorLog]

Package structure

The dir structure of the pycentral package is as follows.

│   README.md
│   Contributions.md
│   ...
│
└───pycentral
│   │   base.py
│   │   configuration.py
│   │   ...
│   │
│   └───workflows
│       │   config_apsettings_from_csv.py
│       │   ...
│
└───docs
    │   ...

pycentral

The pycentral subfolder contains the Aruba Central Python modules. Each module contains multiple Python classes. Each Class is a representation of some of the Aruba Central's API categories as mentioned in the API Reference section. Each class has its own function definitions that are used to make a single REST API call.

In addition to using the modules provided by the package, there is also a module base.py containing function ArubaCentralBase.command(). This function can make any REST API call using the API endpoint URL, HTTP Method, HTTP query params and HTTP payload as required by an API endpoint. The REST API calls are made using the Python requests library by ArubaCentralBase.command(), as supported by Aruba Central API Gateway endpoints.

workflows

workflows folder contains scripts that combine multiple REST API calls based on function definitions provided by pycentral modules to achieve a network automation use-case involving multiple steps or repetitive actions that has to be done in scale. Each workflow script contains comments that describe the step-by-step operations performed by the script.

📘

Module Documentation

To get list of implemented modules and its documentation visit python module documentation.

Gathering requirements

Gathering variables required for the package base class ArubaCentralBase.

• base_url
  Go to Account Home -> API Gateway -> APIs. All Published APIs Table will show URL under DOCUMENTATION column. Truncate this to end with '.com'. For example, https://apigw-prod2.central.arubanetworks.com/swagger/central/ must be truncated to https://apigw-prod2.central.arubanetworks.com
• client_id and client_secret
  Obtain client_id and client_secret variables by creating an API Gateway client in Aruba Central. Refer the Aruba API Gateway section for more details.

At this point, create an API access token from the API Gateway WebUI as described in the Aruba API Gateway section or go further to collect other variables for the Python base class to create/manage access_token via OAUTH APIs.

• customer_id
  Obtain the customer_id by clicking on the figure icon on top right corner of Aruba Central WebUI.

• username and password
  Aruba Central user's username and password. The access token generated by the OAUTH APIs will have the same role/privileges as the provided Aruba Central user credentials.

Execution

ArubaCentralBase class requirements

ArubaCentralBase class requires one mandatory argument central_info. Other optional arguments are token_store and ssl_verify.

1. central_info
One of the following options can be used.

a. Either Provide variables obtained from Gather Requirements section directly to Aruba Central Base class in Python dict structure.

central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}

central_info = {
   "username": "<aruba-central-account-username>",
   "password": "<aruba-central-account-password>",
   "client_id": "<api-gateway-client-id>",
   "client_secret": "<api-gateway-client-secret>",
   "customer_id": "<aruba-central-customer-id>",
   "base_url": "<api-gateway-domain-url>"
}

b. OR Provide the required variables using JSON/YAML file. Use pycentral.workflows_utils.get_conn_from_file() function which accepts name of the file and returns the ArubaCentralBase instance object. YAML examples are provided below.

central_info:
  base_url: "<api-gateway-domain-url>"
  token:
    access_token: "<api-gateway-access-token>"
ssl_verify: true

central_info:
  username: "<aruba-central-account-username>"
  password: "<aruba-central-account-password>"
  client_id: "<api-gateway-client-id>"
  client_secret: "<api-gateway-client-secret>"
  customer_id: "<aruba-central-customer-id>"
  base_url: "<api-gateway-domain-url>"
token_store:
  type: "local"
  path: "temp"
ssl_verify: true

2. token_store
As provided in the above YAML file, token_store default settings are type "local" and path "temp". When OAUTH APIs approach is used, a new access token will generated and cached in the mentioned path of local python host machine. This assists in access_token re-use and help in refreshing expired tokens by the package instead of creating a new access_token.

3. ssl_verify
This argument is of boolean type and default setting is "true". When set to "true", the python client will validate Aruba Central's SSL certs while making HTTPS requests.

❗️

Security Note

• File accepted by pycentral.workflows_utils.get_conn_from_file() are not encrypted. Implement your preferred security encryption method for added security.

• In addition, by taking OAUTH APIs approach the pycentral package will cache generated access_token in local machine in unencrypted JSON file. Override ArubaCentralBase.storeToken() and ArubaCentralBase.loadToken() by leveraging the ArubaCentralBase.token_store variable to implement your own secure token storage mechanism.

Sample scripts

1. Making API call using pycentral base
   Using the base class ArubaCentralBase, any Aruba Central supported REST API calls can be made. A list of groups from Aruba Central can be obtained from the script below. Obtain the HTTP Path, HTTP Method and HTTP query params from Aruba Central Swagger documentation or API references section.

Execute the script ,after filling central_info variable, with command python3 pycentral_base_sample.py.

from pycentral.base import ArubaCentralBase
from pprint import pprint

# Create an instance of ArubaCentralBase using API access token 
# or API Gateway credentials.
central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info,
                           ssl_verify=ssl_verify)

# Sample API call using 'ArubaCentralBase.command()'
# GET groups from Aruba Central
apiPath = "/configuration/v2/groups"
apiMethod = "GET"
apiParams = {
    "limit": 20,
    "offset": 0
}
base_resp = central.command(apiMethod=apiMethod, 
                            apiPath=apiPath,
                            apiParams=apiParams)
pprint(base_resp)

🚧

Security Note

Please Note that you would not want to hardcode access_token directly in a production script.

2. Making API call using pycentral modules
   Some API endpoints supported by Aruba Central are implemented as modules in the Python package. pycentral.configuration module and Groups class is used below to obtain list of groups from Aruba Central.

Execute the script, after filling central_info variable, with command python3 pycentral_module_sample.py.

# Import Aruba Central Base
from pycentral.base import ArubaCentralBase
from pprint import pprint

# Create an instance of ArubaCentralBase using API access token 
# or API Gateway credentials.
central_info = {
    "base_url": "<api-gateway-domain-url>",
    "token": {
        "access_token": "<api-gateway-access-token>"
    }
}
ssl_verify = True
central = ArubaCentralBase(central_info=central_info, 
                           token_store=None, 
                           ssl_verify=ssl_verify)

# Sample API call using Configuration sub-module `pycentral.configuration`
from pycentral.configuration import Groups

# Get groups max limit 20, apply offset and fetch other groups in loop
g = Groups()

module_resp = g.get_groups(central)
pprint(module_resp)

3. Using pycentral workflows
   Workflows are used to achieve an automation use-case which generally involves multiple API calls or dealing with scale and repetitive tasks with ease. Refer the workflows directory to know the supported workflows.
   The following workflow updates settings for multiple Aruba Access Points (AP) defined in the .csv file. In this case, we rename the APs and do not disturb other settings.

Execute the script, after building csv_filename and central_filename, with command python3 pycentral_workflow_sample.py.

Sample CSV file:

serial_number,hostname,ip_address,zonename,achannel,atxpower,gchannel,gtxpower,dot11a_radio_disable,dot11g_radio_disable,usb_port_disable
AAAAAAAAAA,AP1,,,,,,,,,
BBBBBBBBBB,AP2,,,,,,,,,

# Create the following files by refering to the samples.
csv_filename = "csv_file.csv"
central_filename = "input_token_only.yaml"

# Get instance of ArubaCentralBase from the central_filename
from pycentral.workflows.workflows_utils import get_conn_from_file
central = get_conn_from_file(filename=central_filename)

# Rename AP using the workflow `workflows.config_apsettings_from_csv.py`
from pycentral.workflows.config_apsettings_from_csv import ApSettingsCsv
ApSettingsCsv(conn=central, csv_filename=csv_filename)

👍

Sample scripts

For sample scripts, go to the sample_scripts dir in pycentral's GitHub repository.