Background
This blog series covers some of the new API released as part of the APIC-EM 1.3 release of code.
This particular blog covers a the EasyQoS application. EasyQoS is a policy based approach to deploying Quality of Server (QoS) across Cisco switches, routers and Wireless LAN controllers.
This particular blog show how to update an existing QoS policy, create a new application and add a new policy containing the new application.
A bit about EasyQoS application
There are two key concepts with EasyQoS.
- 1) Scope: defines the devices that will have a policy applied to them. A device can only be assigned to one policy scope.
- 2) Policy: a mapping between applications and "relevance". The relevance has one of three values:
- "Default": the application will be treated as default (no QoS marking, default queuing)
- "Relevant": the application will have appropriate QoS markings and queuing defined as per the Cisco Validated Design (CVD)
- "Irrelevant": the application will marked as not important and restricted to a small amount of network bandwidth (scavenger, for those familiar with QoS)
Defining the initial policy via User Interface
In this example, a simple policy ("adam-branch") has been defined. It is applied to the scope "branchQoS". The "sap" application has been defined as business relevant. Note there are no applications defined as "Default" or "Business Irrelevant" in this example.
Click on the "branchQoS" scope, shows the policy has been successfully defined on a single device.
Using the API to modify a policy
Taking a look at the current policies defined on the scope "branchQoS", a single policy has been defined. The name of the policy is "adam-branch-BR". The reason for the "-BR" suffix is that these are applications that are Business-Relevant. In this example the list contains a single application ("sap"), but could contain multiple applications.
In later examples "-BI" (Business Irrelevant) and "-D" (default) policies will be shown.
https://adam-apic/api/v1/policy?policyScope=branchQoS GET
{
"response": [
{
"instanceUuid": "3c20e26b-7d94-4d23-a7fd-8ae68a68207d",
"policyName": "adam-branch-BR",
"policyOwner": "admin",
"policyPriority": 4095,
"state": "Active",
"taskId": "5ecdad7f-50ba-499f-8ed6-5a182f7347f7",
"id": "3c20e26b-7d94-4d23-a7fd-8ae68a68207d",
"resource": {
"applications": [
{
"appName": "sap",
"id": "f05e06db-f148-427f-a98d-74f05ef8a2b4",
"stale": false
}
]
},
"actions": [
"SET_PROPERTY"
],
"actionProperty": {
"relevanceLevel": "Business-Relevant",
"pathControlFlag": false,
"pathPreferenceFlag": false
},
"policyScope": "branchQoS"
}
],
In this example, the "oracle-bi" application is also business relevant, so the policy needs to be updated. First need to get "id" of the pre-defined oracle-bi application using the following request. The application has an id of "8d04df43-56c2-4572-802d-b743dc50b836" and is using TCP ports "9703,9704"
https://adam-apic/api/v1/application?name=oracle-bi GET
{
"response": [
{
"instanceUuid": "8d04df43-56c2-4572-802d-b743dc50b836",
"applicationGroup": "other",
"category": "database",
"categoryId": "1a52425a-d5d4-4cdd-97da-755faf76247a",
"encrypted": "false",
"p2pTechnology": "false",
"tunnel": "false",
"enabled": "true",
"nbarId": "1359",
"engineId": "3",
"globalId": "L4:9703",
"selectorId": "9703",
"helpString": "Oracle Business Intelligence",
"longDescription": "Used by Oracle in their Business Intelligence products.",
"references": "http://www.oracle.com/us/solutions/business-analytics/business-intelligence/index.html",
"isRepresentativeApp": false,
"popularity": 1,
"indicativeTcpPorts": "9703,9704",
"pfrThresholdJitter": 1,
"pfrThresholdJitterPriority": 3,
"pfrThresholdLossRate": 5,
"pfrThresholdLossRatePriority": 2,
"pfrThresholdOneWayDelay": 100,
"pfrThresholdOneWayDelayPriority": 1,
"trafficClass": "BULK_DATA",
"rank": 65535,
"ignoreConflict": false,
"id": "8d04df43-56c2-4572-802d-b743dc50b836",
"subCategory": "enterprise-transactional-apps",
"name": "oracle-bi",
"appProtocol": "tcp",
"tcpPorts": "9703,9704"
}
The next step is to modify the existing policy to add the "oracle-bi" application. NOTE: This will be a PUT (modify) rather than POST (create a new policy). I will show you how to create an application from scratch in the next example.
Remember the id of the oracle-bi application is "8d04df43-56c2-4572-802d-b743dc50b836".
https://adam-apic/apic/api/v1/policy PUT
[{
"policyName": "adam-branch-BR",
"policyOwner": "admin",
"policyPriority": 4095,
"actions": ["SET_PROPERTY"],
"policyScope": "branchQoS",
"actionProperty": {
"relevanceLevel": "Business-Relevant"
},
"resource": {
"applications": [{
"id": "8d04df43-56c2-4572-802d-b743dc50b836"
}, {
"id": "f05e06db-f148-427f-a98d-74f05ef8a2b4"
}]
},
"id": "3c20e26b-7d94-4d23-a7fd-8ae68a68207d"
}]
The response will be a taskId (8baaf565-4a29-4230-907e-973d08b3f347) that needs to be polled.
{
"response": {
"taskId": "8baaf565-4a29-4230-907e-973d08b3f347",
"url": "/api/v1/task/8baaf565-4a29-4230-907e-973d08b3f347"
},
"version": "1.0"
}
Polling the status of the task (8baaf565-4a29-4230-907e-973d08b3f347) shows the task completed successfully.
https://adam-apic/api/v1/task/8baaf565-4a29-4230-907e-973d08b3f347 GET
{
"response": {
"version": 1480233941149,
"startTime": 1480233941149,
"endTime": 1480233942264,
"isError": false,
"serviceType": "Policy Service",
"operationIdList": [
"4d5a7fb5-eb3b-4367-a0ba-1bfa38074f61"
],
"rootId": "8baaf565-4a29-4230-907e-973d08b3f347",
"id": "8baaf565-4a29-4230-907e-973d08b3f347"
},
"version": "1.0"
The policy change will be reflected in the user interface.
Using the API to create a custom application
Although there are 1300 applications defined in EasyQoS application, there is also an API to create new application definitions.
In this example, I am creating an application "adam-new" which is a TCP application with an IP address of "10.200.20.0" and TCP Port of 2320. The QoS Class for this application is "BULK_DATA". The other attributes are for IWAN path selection.
https://adam-apic/api/v1/application POST
[{
"helpString": "adam-new",
"name": "adam-new",
"type": "_server-ip",
"appProtocol": "tcp",
"trafficClass": "BULK_DATA",
"category": "other",
"categoryId": "995f625b-fe2e-40da-8ce8-c2b0ee3d5153",
"subCategory": "other",
"pfrThresholdLossRate": 1,
"pfrThresholdOneWayDelay": 150,
"tcpPorts": 2320,
"transportIps": "10.200.20.0",
"pfrThresholdJitter": 20,
"pfrThresholdJitterPriority": 3,
"pfrThresholdLossRatePriority": 1,
"pfrThresholdOneWayDelayPriority": 2,
"engineId": 6,
"rank": 1
}]
As usual, there will be a task created, which needs to be polled. The response will show the status of the task and the id of the newly created application will returned in the "progress" attribute 2297ba33-42da-494c-9875-4d7551060b18.
https://adam-iwan/api/v1/task/1ff99683-1ba5-4cf6-a33f-a8ceb2ee73ba GET
{
"response": {
"version": 1480235124975,
"startTime": 1480235124975,
"endTime": 1480235127414,
"progress": "2297ba33-42da-494c-9875-4d7551060b18",
"isError": false,
"serviceType": "Policy Service",
"operationIdList": [
"fb277067-6c3a-40eb-a632-58bc5e3df40e"
],
"rootId": "1ff99683-1ba5-4cf6-a33f-a8ceb2ee73ba",
"id": "1ff99683-1ba5-4cf6-a33f-a8ceb2ee73ba"
},
"version": "1.0"
}
Using the API to create a new policy
Using the id of the newly created application "adam-new" a "Business Irrelevant" policy will be created for the same scope. The name of the policy will be the same as before, except it will have a "-BI" and the "relevanceLevel" also needs to reflect the policy is Business-Irelevant applications. The application id is the same one created in the earlier step (adam-new).
https://adam-apic/apic/api/v1/policy POST
[{
"policyName": "adam-branch-BI",
"policyOwner": "admin",
"policyPriority": 4095,
"actions": ["SET_PROPERTY"],
"policyScope": "branchQoS",
"actionProperty": {
"relevanceLevel": "Business-Irrelevant"
},
"resource": {
"applications": [{
"id": "2297ba33-42da-494c-9875-4d7551060b18"
}]
}
}]
Again, checking the status of the task shows it was successful. The id of the new policy is also returned (2cdf14a8-1496-4f04-864a-548bc93d0740)
https://adam-iwan/api/v1/task/fdb8c6ea-8716-4f44-8d2a-925c61f47c41 GET
{
"response": {
"version": 1480236810504,
"startTime": 1480236810504,
"endTime": 1480236811605,
"progress": "2cdf14a8-1496-4f04-864a-548bc93d0740",
"isError": false,
"serviceType": "Policy Service",
"operationIdList": [
"4aebc151-df89-4ce4-afaf-033cde762b1d"
],
"rootId": "fdb8c6ea-8716-4f44-8d2a-925c61f47c41",
"id": "fdb8c6ea-8716-4f44-8d2a-925c61f47c41"
},
The User Interface shows the policy has been updated successfully.
This can be verified through an API call. You will see both a "Business Irrelevant" (one application – "adam-new") policy and a "Business Relevant" (two applications "sap" and "oracle-bi") policy.
https://adam-iwan/api/v1/policy?policyScope=branchQoS GET
{
"instanceUuid": "2cdf14a8-1496-4f04-864a-548bc93d0740",
"policyName": "adam-branch-BI",
"policyOwner": "admin",
"policyPriority": 4095,
"state": "Active",
"taskId": "fdb8c6ea-8716-4f44-8d2a-925c61f47c41",
"id": "2cdf14a8-1496-4f04-864a-548bc93d0740",
"resource": {
"applications": [
{
"appName": "adam-new",
"id": "2297ba33-42da-494c-9875-4d7551060b18",
"stale": false
}
]
},
"actions": [
"SET_PROPERTY"
],
"actionProperty": {
"relevanceLevel": "Business-Irrelevant",
"pathControlFlag": false,
"pathPreferenceFlag": false
},
"policyScope": "branchQoS"
},
{
"instanceUuid": "3c20e26b-7d94-4d23-a7fd-8ae68a68207d",
"policyName": "adam-branch-BR",
"policyOwner": "admin",
"policyPriority": 4095,
"state": "Active",
"taskId": "82fc8076-3f33-4c90-9577-aac97ab3c8fa",
"id": "3c20e26b-7d94-4d23-a7fd-8ae68a68207d",
"resource": {
"applications": [
{
"appName": "oracle-bi",
"id": "8d04df43-56c2-4572-802d-b743dc50b836",
"stale": false
},
{
"appName": "sap",
"id": "f05e06db-f148-427f-a98d-74f05ef8a2b4",
"stale": false
}
]
},
"actions": [
"SET_PROPERTY"
],
"actionProperty": {
"relevanceLevel": "Business-Relevant",
"pathControlFlag": false,
"pathPreferenceFlag": false
},
"policyScope": "branchQoS"
}
],}
What Next?
This blog covered some basic API for the EasyQoS application on APIC-EM.
In the meantime, if you would like to learn more about this, you could come hang out with us in The Cisco Devnet DNA Community. We’ll have a continuous stream of blogs like this and you can ask questions and we’ll get you answers. In addition, we have a Github repository where you can get examples related to EasyQoS.
Thanks for reading,
5 Comments