aruba/pycentral

Aruba Central Python SDK

pycentral

Aruba Central Python Package Index 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

In order to run the workflow scripts, please complete the steps below:

1. install virtual env (refer https://docs.python.org/3/library/venv.html). Make sure python version 3 is installed in system.

   $ python3 -m venv centralenv
   

2. Activate the virtual env

   $ source centralenv/bin/activate
   in Windows:
   $ centralenv/Scripts/activate.bat
   

3. Install the pycentral package

   (centralenv)$ pip3 install pycentral
   

   To install package with extras colorLog which will display log in color

   (centralenv)$ pip3 install pycentral[colorLog]
   

Now you can start making your script based on modules in pycentral or use different workflows from the subpackage workflows.

Executing Scripts

1. Gathering variables required for the package base class ArubaCentralBase.

   • base_url OR cluster_name: You can find the base URL or cluster name of the Central account's API Gateway from the table here. The base URL or cluster name is based on the geographical Central cluster in which the account is registered.

   • access_token: You can create an API access token for Aruba Central from -

     • Aruba Central UI
     • OAuth APIs

   • Optional variables - You need to provide the below variables if you want to use PyCentral's ability to generate access tokens from Aruba Central with the help of OAuth APIs.

     • 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.

     • client_id and client_secret: Obtain client_id and client_secret variables by creating an API Gateway client in Aruba Central. Refer the following documentation for more details.

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

   

2. Providing input variables to the Python scripts. One of the following options can be used.

   • Provide variables directly to Aruba Central Base class in dictionary format.

     Access token approach:

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

     OAUTH APIs approach with capability to generate new 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>"
         }

     Alternatively, you can use cluster_name instead of base_url in the above mentioned dictionaries. You can find the list of clusters that are supported in the constants.py file. If you would like to add support for other Central clusters, you can do so by adding it in the constants.py. Refer the sample scripts in step3 and step4 for examples.

   • OR Provide the required variables using JSON/YAML file. Refer to the sample input files to understand how the files have to be structured -

     • sample_scripts/input_token_only.yaml

     • sample_scripts/input_credentials.yaml

     • sample_scripts/input_token_only_cluster_name.yaml

     • sample_scripts/input_credentials_cluster_name.yaml

       More sample input files can be found in the sample_scripts folder. Use pycentral.workflows_utils.get_conn_from_file() function which accepts name of the file and returns the ArubaCentralBase instance object.

3. Making API call using pycentral base: Using the base class ArubaCentralBase, any Aruba Central supported REST API calls can be made. Refer the following sample script sample_scripts/pycentral_base_sample.py

   Obtain the HTTP Request related information from Aruba Central Swagger documentation or API references page in Aruba Developer Hub.

4. Making API call using pycentral modules: Some API endpoints supported by Aruba Central are implemented as modules in the Python package. Refer the following sample script using modules sample_scripts/pycentral_module_sample.py

   To obtain a list of implemented modules and its documentation refer the pycentral module documentation

5. 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. Check out the central-python-workflows repository to check out workflows that utilize the Pycentral library.

Documentation:

• Python package documentation:
• pycentral module documentation
• Use-Cases and Workflows:
  • Aruba Developer Hub
  • central-python-workflows

Note:

The package takes one of the two approaches to gain access to Aruba Central APIs.

• OAUTH APIs: By taking OAUTH approach to generate new access_token, the python package will cache the tokens locally for re-use. Caching tokens locally, helps preventing creation of new access_token every time the script is run. In addition, when the access_token is expired the script will attempt to use the supplied credentials and attempt to refresh the expired token.

  Override the ArubaCentralBase.storeToken() and ArubaCentralBase.loadToken() function definitions to change this behavior of caching in local file(JSON) and manage tokens more securely.

• Access Token: This process is more secure. By providing only the access_token instead of credentials, the package will not cache the tokens. But loses the ability to handle expired token and to generate new access tokens.

How to contribute

Please see the accompanying CONTRIBUTIONS.md file for guidelines on how to contribute to this repository.

Troubleshooting Issues

If you encounter module import errors, make sure that the package has been installed correctly.

Additionally, please read the RELEASE-NOTES.md file for the current release information and known issues.

pycentral's Issues

pip 21.3 just posted 2 days ago breaks pycentral

...
    from pycentral.base import ArubaCentralBase
  File "/home/wade/.local/lib/python3.8/site-packages/pycentral/base.py", line 26, in <module>
    from pycentral.base_utils import tokenLocalStoreUtil
  File "/home/wade/.local/lib/python3.8/site-packages/pycentral/base_utils.py", line 28, in <module>
    from pip._internal.utils.misc import get_installed_distributions
ImportError: cannot import name 'get_installed_distributions' from 'pip._internal.utils.misc

get_internal_distributions() was removed in 21.3 (posted 10/11/2021) the previous version 21.2.4 is fine.

PR with fix #10

FYI: can be worked around prior to the fix being published on pypi by specifying the older version pip install pip==21.2.4

example AP rename code always terminates with an error

The example code always terminates with an error

AP_SETTINGS_CSV - ERROR - Failed to update ap settings for APs []

it looks like its just not checking for an empty array. Perhaps we could test for this condition.

unkown_aps = list(set(all_aps) - set(success_aps + failed_aps))
failed_aps = failed_aps + unkown_aps
print("")
LOGGER.error("Failed to update ap settings for APs %s" % failed_aps)

No unit test cases for the Pycentral code

Hi,

As I was surfing through the code, I found that there are no unit test cases for the currently present code for Pycentral library. It will be helpful to have unit test cases in the repo before leveraging the library.

MSP functionality

Hi!

Would like to contribute msp api functionality.

Br

M.

Problem with multiple ArubaCentralBase objects

I believe the use of a singleton C_DEFAULT_ARGS in pycentral.base_utils is causing an issue when using multiple API connections (e.g. when connecting multiple times with different credentials).

ArubaCentralBase.init makes a call to base_utils.parseInputArgs() to get a clean set of central_info parameters. Unfortunately, parseInputArgs() uses the same return dictionary for all calls. So, calling parseInputArgs() with different values affects all previous calls.

In parseInputArgs(), the line:

default_dict = C_DEFAULT_ARGS

can be replaced by:

default_dict = dict(C_DEFAULT_ARGS)

Thanks!

Timeout Handling

When performing API calls, I occasionally (but regularly and consistently) get client side timeout errors on the pycentral module which doesn't appear to be handling them well - usually a retry clears it right up, so it would probably be useful to to a better job of catching that particular exception or setting a retry count as well as a timeout value when creating the pycentral object, which can then be passed on to the requests module (it currently appears to be 60 seconds).

Some pycentral calls need Northbound API to be enabled by TAC

Several API calls (for example get_all_wlans() ) need Northbound API to be enabled on account. This is not enabled by default and need to be requested from TAC.

It would be nice to have this prerequisite mentioned in documentation.