cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

APIC-EM 1.3 Update – Part 2 - EasyQoS

1532
Views
9
Helpful
5
Comments
Cisco Employee

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. 1) Scope: defines the devices that will have a policy applied to them.  A device can only be assigned to one policy scope.
  2. 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.

qos_policy.png

Click on the "branchQoS" scope, shows the policy has been successfully defined on a single device.

qos policy applied.png

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.

added-oracle.png

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.

new-policy.png

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,

@adamradford123

5 Comments
Beginner

Well written blogs which help me to understand APIC-EM and various modules like EasyQOS and PnP. Are you planning to write something for iwan as well in future?

Cisco Employee

Thanks Razi,

yes, I will do an IWAN blog too  I am waiting for the next release.

Here is the index of all of them so far.

Adam Radford's Blog

Adam

Beginner

Hey Adam. I am working on a solution that uses EasyQoS in the APIC EM version 1.5.  I am able to create and delete Flows for my application as new users enter or leave the network. During the happy path execution the QoS settings are propagated to the networked device successfully. However I am seeing an event where the Flow gets into an unstable status. When I check the state of the FLow using the API /policy/get/{id} I get the following result.

{

  "response": [

    {

      "id": "f4df0f7a-aa1e-40c2-8c9a-2f18a64d16b3",

      "sourceIP": "192.168.19.109",

      "protocol": "udp",

      "applicationName": "cisco-audio",

      "matchDSCP": "46",

      "flowType": "VOICE",

      "networkDeviceId": "98f5f3d4-0ab4-42cf-94a7-d96422ea3188",

      "networkDeviceName": "EvoSW2",

      "interfaceId": "2444b4ef-5aec-466d-93f9-c8d07d22718d",

      "interfaceName": "GigabitEthernet1/0/3",

      "status": "CONFIGURING_DELETE",

      "failureReason": "192.168.19.107:NP_500:Unable to push configuration to device ip 192.168.19.107:FAILURE : [QoS configuration failed: This device aclEntry.getIpAceCD() is null while shouldn't be ,\nthe aclEntry is: AclEntry@25c59982[aceIdentifier=20,action=PERMIT,accControl"

    }

  ],

  "version": "1.0"

}

Once the flow enters this state I have not been able to successfully move it back into a usable state. It in fact locks the ability of my automated processes to manipulate in flows for the the sourceIP.

What is the best way to deal with this scenario?

The effect is blocking us from moving the integration into an Alpha test phase so any help or suggestions would be greatly appreciated.

Cisco Employee

Hi Bob,

I have seen this in older software releases, and though it had been fixed.

Can you confirm the target switch and version of code it is running please?

The other thing to check is the network-programmer logs.

I can let you know how to access those, If you do not already know.

Adam

Beginner

We are currently using the newly release version APIC-EM Version 1.5.0.1368.

Yes please tell me how to access any of the pertinent logs that could help in this issues.

I wanted to take this opportunity to expand on the problem in detail so you have as much information concerning our immediate problem scope.

More specifically what I need to deal with now is how to move the flow back out of this state or into a state that allows us to use the /policy/flow/ DELETE method.

I have already written the error handling and recovery code to identify flows that switch to the CONFIG_DELETE_FAILIURE state.

However all I can currently do is Log the error and isolate the sourceIP from future dynamic QoS commands.

I do this because any future command moves it to a new error state (For example a CONFIG_DELETE_FAILURE flow with a /policy/flow/POST command for that sourceIP results in a CONFIG_ADD_FAILURE state for that flow. (and sometimes there will be multiple errors flows for the same IP in the table presented on the EasyQoS screen for EasyQoS->Advanced Settings->Dynamic QoS (BETA).

When I attempt to call /policy/flow/ DELETE method I get back TaskIdResult. Following that link I can see it finish with and endTime and a isError=false but the state of the flow is moved to a “CONFIGURING_DELETE” state.

Hopefully this email will post these details directly to your blog. If not I will check back today and add them into the open discussion.

Thanks for all the consideration and assistance.

Bob Beals

Senior Software Engineer

Nectar Services Corporation

3701 West Plano Parkway, Suite 160, Plano, Texas 75075

This widget could not be displayed.