Using Python REST API SDK
PyPi Package
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 toAccount 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 tohttps://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()
andArubaCentralBase.loadToken()
by leveraging theArubaCentralBase.token_store
variable to implement your own secure token storage mechanism.
Sample scripts
- Making API call using pycentral base
Using the base classArubaCentralBase
, 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.
- Making API call using pycentral modules
Some API endpoints supported by Aruba Central are implemented as modules in the Python package.pycentral.configuration
module andGroups
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)
- 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.
Updated 7 days ago