Working with REST API on cutting-edge systems can be challenging at times. Rapid evolution and new features often lead to changes in the structure of REST API calls. These can be just cosmetic but still require an effort to adjust existing scripts.
This problem can be easily handled by the SDKs dedicated to systems such as Cisco Meraki or Cisco DNA Center. For now, unfortunately we don’t have a dedicated SDK for Cisco SD-WAN. However, the winds of change are blowing and there is a library that can simplify our lives now, and in the future become a full-blown SDK.
At CodiLime, we’re actively contributing to the development of Cisco’s vManage client library, which is responsible for communication with vManage.
In this article, we will go through the essential operations in the Cisco SD-WAN environment so you can get a feeling for how vManage client works, and how you can benefit from using it.
What should you know about vManage client?
vManage client is a fresh Python library developed by Cisco. Its purpose is to make interaction with vManage simple and intuitive. It supports various operations, from basic data retrieval to creating complicated feature templates. CodiLime is actively contributing to the development process.
If you want to modernize, automate and transform your software, hardware, and equipment, check our environment services.
Environment
For the purpose of this article, we will use a Cisco SD-WAN 20.10 Always On 
. It’s a free lab environment hosted by Cisco, that everybody can access to test various functionalities. It’s a great way to get in touch with SD-WAN.
However, this solution has limitations. The only allowed operations are read-only, we don’t have permission to perform any configuration changes. That’s why, in this article, we will focus on the operations that are retrieving information from the SD-WAN.
The direct URL to Cisco vManage is here .
Library installation
The vManage client librarycan be installed using the pip module by using the pip install vmngclient command.
Creating a session
To interact with vManage, we need to create a session. This is a straightforward process. First of all, we need to import the create_vManageSession method from the vmngclient.session. After that, we’re ready to create one passing the URL and credentials as arguments.
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
from vmngclient.session import create_vManageSession
from vmngclient.utils.personality import Personality
url = "sandbox-sdwan-2.cisco.com"
username = "devnetuser"
password = "RG!_Yw919_83"
session = create_vManageSession(url=url, username=username, password=password)
Now, we can communicate with vManage by using a newly created session object.
Displaying information
The structure of objects in vManage client is hierarchical. As an example, let’s grab a list of devices added to the SD-WAN.
Additional note: if you are looking for further information about SD-WAN, we recommend our previous article where we highlighted SD-WAN benefits.
devices = session.api.devices.get()
vManage client has its own built-in classes, which are frequently used to represent SD-WAN objects. In this example, the devices variable is an iterable of the type DataSequence, which contains instances of Device class objects.
From now on, we can interact directly with particular devices. Let’s print some basic information about each of them, check its system status, and gather BFD sessions.
for device in devices:
print(f"Gathering information about {device.hostname}")
system_status = session.api.device_state.get_system_status(device.id)
print(f"Reachability - {system_status.reachability}, status - {system_status.status}")
bfd_sessions = session.api.device_state.get_bfd_sessions(device.id)
print(f"Number of BFD sessions - {len(bfd_sessions)}\n")
Basic device information is accessible through class attributes. In the code above, we’re grabbing the hostname and ID that way. There are also other attributes, which are reachable, such as:
- Local system IP,
- Device model,
- UUID,
- Serial.
To gather information such as system status or BFD sessions, we have to interact with the session object once again. For both activities, there are prepared methods, which take the device ID as an argument. Since we’re iterating through all the devices, we’re calling get_system_status and get_bfd_sessions for each.
The output from the loop is presented below.
Gathering information about vmanage
Reachability - reachable, status - normal
Number of BFD sessions - 0
Gathering information about vsmart
Reachability - reachable, status - normal
Number of BFD sessions - 0
Gathering information about site1-cedge01
Reachability - reachable, status - normal
Number of BFD sessions - 12
Gathering information about dc-cedge01
Reachability - reachable, status - normal
Number of BFD sessions - 12
Gathering information about vbond
Reachability - reachable, status - normal
Number of BFD sessions - 0
Gathering information about site3-vedge01
Reachability - reachable, status - normal
Number of BFD sessions - 12
Gathering information about site2-cedge01
Reachability - reachable, status - normal
Number of BFD sessions - 12
We have gathered some useful information, but what about grabbing a specific type of device rather than listing the whole inventory?
Let’s check how to approach that problem.
Filtering
We can achieve that by utilizing a Personality enum from the vManage client utils. In this example, we will count and then list all reachable vBonds.
reachable_vbonds = session.api.devices.get_reachable_devices(Personality.VBOND)
print(f"\n\nReachable vBonds - {len(reachable_vbonds)}")
for vbond in reachable_vbonds:
print(f"Hostname - {vbond.hostname}, CPU load - {vbond.cpu_load}")
The list of reachable vBonds was created by the get_reachable_devices method. Then we checked the length of the list to get the total number of vBonds there. But it can be also grabbed directly from the vManage client by executing the count_devices method, which also accepts device personality type.
The output is the following.
Reachable vBonds - 1
Hostname - vbond, CPU load - 3.48
Now we know how to use built-in vManage client methods. It also supports manual call execution.
Manual call execution
Those methods can be helpful if you don’t find a built-in method to retrieve the data that you want. Cisco SD-WAN is still evolving rapidly, and so is its API. It’s possible that you will find an API call that is not yet covered by vManage client. In such a case, you can execute any request using first layer methods. For the GET requests, we have the get method.
print(f"\n\n\nsession.get example:")
get = session.get("/dataservice/device")
print(f"Response object type - {type(get)}")
print(f"Response code - {get.status_code}")
print(f"Content:\n{json.loads(get.text)}")
The first thing that catches the eye is the argument. In contrast to the requests library, we don’t have to put a full URL here. It’s because the vManage client session utilizes data taken during creation. We have to provide only the specific end-point; in our case it’s /dataservice/device.
After the execution, we’re getting a vManageResponse object type. The response is available via the text attribute. It’s a string object. To cast it to standard Python data types, we have to use loads from the JSON library. Besides the response data, we also have parameters such as the response code.
Let’s take a look at the output.
session.get example:
Response object type - <class 'vmngclient.response.vManageResponse'>
Response code - 200
Content:
{'header': {'generatedOn': 1686664278826, 'viewKeys': {'uniqueKey': \['system-ip'], 'preferenceKey': 'grid-Device'},
[...]
{'deviceId': '10.10.1.17', 'system-ip': '10.10.1.17', 'host-name': 'site3-vedge01', 'reachability': 'reachable', 'status': 'normal', 'personality': 'vedge', 'device-type': 'vedge', 'timezone': 'UTC', 'device-groups': \['No groups'], 'lastupdated': 1686648579490, 'bfdSessionsUp': 12, 'domain-id': '1', 'board-serial': '1701BB87', 'certificate-validity': 'Valid', 'max-controllers': '0', 'uuid': 'dac3e7f5-b48f-d29b-0685-d3bb4b2ea991', 'bfdSessions': '12', 'controlConnections': '3', 'device-model': 'vedge-cloud', 'version': '20.10.1', 'connectedVManages': \['10.10.1.1'], 'site-id': '1003', 'ompPeers': '1', 'latitude': '53.408', 'longitude': '-2.228', 'isDeviceGeoData': True, 'platform': 'x86_64', 'uptime-date': 1682598840000, 'statusOrder': 4, 'device-os': 'next', 'validity': 'valid', 'state': 'green', 'state_description': 'All daemons up', 'model_sku': 'None', 'local-system-ip': '10.10.1.17', 'total_cpu_count': '2', 'linux_cpu_count': '1', 'testbed_mode': False, 'layoutLevel': 4}]}
The complete code is available down below.
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
from vmngclient.session import create_vManageSession
from vmngclient.utils.personality import Personality
url = "sandbox-sdwan-2.cisco.com"
username = "devnetuser"
password = "RG!_Yw919_83"
session = create_vManageSession(url=url, username=username, password=password)
devices = session.api.devices.get()
for device in devices:
print(f"Gathering information about {device.hostname}")
system_status = session.api.device_state.get_system_status(device.id)
print(f"Reachability - {system_status.reachability}, status - {system_status.status}")
bfd_sessions = session.api.device_state.get_bfd_sessions(device.id)
print(f"Number of bfd sessions - {len(bfd_sessions)}\n")
reachable_vbonds = session.api.devices.get_reachable_devices(Personality.VBOND)
print(f"\n\nThere are {len(reachable_vbonds)} reachable vBonds")
for vbond in reachable_vbonds:
print(f"Hostname - {vbond.hostname}, CPU load - {vbond.cpu_load}")
print(f"\n\n\nsession.get example:")
get = session.get("/dataservice/device")
print(f"Response object type - {type(get)}")
print(f"Response code - {get.status_code}")
print(f"Content:\n{json.loads(get.text)}")
Summary
In contrast to the Cisco Meraki or DNA Center SDKs, SD-WAN lacked a library that would make interaction with the controllers easier. vManage Client is the response to that. Currently, it’s a good foundation for automation challenges such as changes in the API structure. While it’s still being developed as a library, it’s heading toward becoming a full-blown SDK for Cisco SD-WAN.
