0

Automating Network Provisioning with Cisco APIC — Exploring the REST API


How to automate the configuration of network devices? Cisco APIC-EM (= Application Policy Infrastructure Controller) is a controller that can help us with that task. In this blog post, we will explore its modern REST API for accomplishing basic tasks like creating, reading, updating and deleting (CRUD) objects like

  • APIC users (e.g. administrators)
  • network discovery tasks
  • network devices and their configurations.

We will use the Chrome Postman plugin for exploring the API.

Tldr;

Click here to have a look at the summary section.

What is Cisco APIC?

See here a nice 4 minute Cisco youtube commercial about APIC. And here you find a Cisco live! 40 minute session, which gives a short overview. I will summarize:

  • APIC is a controller with Web Interface and REST API, which can be used to Create, Read, Update and Delete (CRUD) following kind of objects (and more)
    • Network Devices
      • Locations
      • Interfaces
        • Links
        • Hosts
    • Policies
    • Tasks
  • Anything you can do in the Web interface can also be done via the REST API (similar to Ruby on Rails, RoR)
  • The video is showing how a REST test tool like Chrome Postman or simple Python scripts can be used to interface with the REST API. Some examples are:
    • displaying a list of all network devices
    • displaying a the network path from arbitrary address A to arbitrary address B
    • finding an ACL on a network path that is blocking a certain application
  • The REST API is self-documenting using Swagger
    hc_001
    Note: “self-documenting” means

    • that it can be explored through the same interface (but different path) like the API itself
    • the documentation is generated from source code. Note, that the developer needs to add the content of the swagger documentation to the source code, similar to javadocs. Swagger takes care of converting the source code into swagger interactive web pages.

Why should you install Cisco APIC?

Quick answer: you should not. The installation on VMware 5.1 or 5.5 would require 6 vCPUs and 64 GB of RAM, 500 GB disk and 200 MB disk I/O speed. A monster of an application. Wow.

To be more specific: you can install Cisco APIC, but you do not need to install Cisco APIC, if you just want to explore the Cisco APIC interfaces: there is a more clever, cloud-based possibility: DevNet sandboxes offered by Cisco.

If you still want to install it, the SW can be found via this DevNet page (use IE or Firefox; since Chrome is not supported; click on “3”). The SW is also available on Cisco’s SW repository. However, authorization is required there, while in DevNet, the access is less restrictive.

A clever Alternative: DevNet Sandboxes:

Instead of installing this monster application, we can also connect to one of the DevNet Learning Labs found in the DevNet Sandbox catalog.

2016.03.08-23_56_12-hc_001

Note that you need to register with Cisco, if you have not done already, either as a Customer or a Partner. In both cases, they want you to enter a contract number. I am a CCIE, so I already had an account.

See below more information on the pre-installed labs.

 

2016.03.09-00_42_31-hc_001

Most of the labs are APIC labs. When clicking on the “Develop in the Sandbox” button on the upper right of the page, I reach at the lab catalog.

2016.03.09-00_49_05-hc_001

Let us keep simple, and try to enter the APIC-EM DB Only Always-On lab: this seems to be a kind of guided lab. Cool. 😉

2016.03.09-00_50_40-hc_001

scrolled down on the left pane:

2016.03.09-15_31_28-hc_001_credentials_removed

we find a link to the APIC-EM portal: https://sandboxapic.cisco.com:9443. There, I could log in with the specified default credentials (removed).

2016.03.09-00_57_14-hc_001

With that, I have reached the APIC-EM portal:

2016.03.09-15_28_14-hc_001

Manipulating Users

Note: In this example, we will show how to create, read and delete users using Postman, a chrome app for sending RESTful HTTP commands (most important: POST, GET, PUT, DELETE for Create, Read, Update and Delete of an object).

Let us go back to the guided tour on the “APIC-EM DB Only Always-On lab” we had reached from the lab catalog: on the left pane, we can find a link to the sandbox:

2016.03.09-15_31_28-hc_001_credentials_removed

Furthermore, we can find a link to a hello world guided tour in order to explore the northbound REST interface.

There, they are requesting that the user should install Postman. This is the tool I use often to test my ProvisioningEngine and its target systems. Within Postman, I have created a new collection called “Cisco APIC – hello world sandbox”:

2016.03.14-01_22_40-hc_001

Before sending my first REST commands to the Cisco APIC, I would like to explore the self-documented interface. From what I have seen in the video, I just need to enter the link https://sandboxapic.cisco.com:9443/swagger in a browser. Yes; here we are:

2016.03.09-15_54_23-hc_001

In the hello world example, we will start with the creation of a ticket. Let us explore the ticket documentation:

2016.03.09-16_00_49-hc_001

Init: Creation of an authentication Token

Now, on Postman, let us perform our first real command: creation of a ticket. In Postman, I enter:

2016.03.09-16_17_17-hc_001

and the body:

2016.03.09-16_11_19-hc_001_password_removed

After pressing the “Send” button we get:

2016.03.09-16_15_40-hc_001

Good. So, what do we do with that?

Read Users: GET /user

The serviceTicket above then is used as an X-Auth-token for all subsequent requests. Let us use it to show all users:

2016.03.09-16_30_03-hc_001

Do not forget to switch from POST to GET, before you press the Send button.

Oups, we get: “Not Found”

That was, because I had a double-slash instead of a slash in the URL. After correcting the URL and pressing the Send button again, we get a meaningful answer:

{
  "response": [
    {
      "username": "greg",
      "authorization": [
        {
          "scope": "ALL",
          "role": "ROLE_ADMIN"
        }
      ]
    },
    ...
    {
      "username": "admin",
      "authorization": [
        {
          "scope": "ALL",
          "role": "ROLE_ADMIN"
        }
      ]
    },
    ...
  ,
  "version": "1.0"
}

Note: The API developers have chosen to use singular nouns like GET /user. This is a little bit awkward, since a GET /user is returning a collection of users, not a single user. GET /users sounds more natural, especially, if you are used to Ruby on Rails. However, at the end, it is a matter of convention. Unfortunately, there is no agreement on the convention either way and we find popular API examples for both conventions. Fortunately, they have chosen not to mix plural and singular nouns in the URL. Good.

Create a User: POST /user

With a little bit of trial and error, I also have been successful in creating a new user entry:

2016.03.09-17_04_53-hc_001

And yes: the user can be seen with a GET /user request as above:

2016.03.09-17_11_14-hc_001

The password seems to be saved more securely elsewhere.

Now, I can log into APIC portal as user “olli”:

2016.03.10-16_20_32-hc_001

Read single User: GET /user/{name}

Now let us read a single user. This is not straightforward, since the API developers have chosen not to auto-generate and display user IDs. Maybe the username is the ID? Then it needs to be unique. Let us test this first: trying to create a user with the same name:

2016.03.09-17_16_16-hc_001

yepp: the username is the unique ID. Following REST semantics, we should be able to read a single user with GET /user/olli:

2016.03.09-17_18_30-hc_001

Works fine.

Update User: PUT /user

The tricky part is to update the user. From swagger we see that the more obvious syntax

PUT /user/{id}

is not supported. We are required to issue the command

PUT /user

without ID, and the ID is specified in the body. This is not following REST API best practices and will be discussed after the Summary.

2016.03.09-17_55_44-hc_001

Even if I use the right syntax PUT /user, I am not allowed to change the password of user “olli” when using an authentication token (ticket) that has been created by the admin:

2016.03.10-16_35_47-hc_001

Password change via the REST API is supported only, if you log in as the user in question. Therefore I need to get a new ticket (token) for user olli instead:

2016.03.10-16_37_10-hc_001

And now we can use the serviceTicket as an authentication token in the update user command:

2016.03.10-16_38_38-hc_001

Note: you need to remove the /olli part from the URL above!

Now the update works:

2016.03.10-16_41_04-hc_001

Yesss! That was not easy. I have removed my first unsuccessful attempts, where I had tried with the URL /user/olli in order to simplify the post and in order to not confuse you.

Now I can log in to the APIC-EM portal using the updated password:

2016.03.10-16_43_11-hc_001

Delete user: DELETE /user/{name}

With the ticket (token) of the admin (again), it is easy to delete the entry via DELETE /user/olli:

2016.03.09-17_21_12-hc_001

Note: we have got a 200 OK upon a DELETE request, which indicates that it has been deleted immediately and that the response body is not empty. For asynchronous processing, 202 would have been the right answer HTTP code and for a successful deletion without response body, code 204 is used. See Section 9 of RFC2616.

As expected, after the deletion us user “olli”, a GET /user/olli then leads to “404 Not Found” error:

2016.03.09-17_39_25-hc_001

Discovering the Network

We did not start playing around with Cisco APIC in order to manipulate users, did we? Let us get into the real stuff: discovering and manipulating networks.

2016.03.09-18_11_42-hc_001

Read network discoveries: GET /discovery/{startIndex}/{recordsToReturn}

When I understand it right, I can manipulate network discovery tasks on /discovery. Two network discovery tasks have already been conducted:

2016.03.09-18_13_23-hc_001

What is missing in the interface, is a GET /discovery to return a list of all discoveries. The only request, which seems to come close is

GET /discovery/{startIndex}/{recordsToReturn}

2016.03.09-18_17_53-hc_001

Yes, GET /discovery/1/2 was, what I was looking for. Also GET /discovery/1/500 works fine, and comes close to GET  /discovery I was looking for. Note that 500 seems to be the largest possible value: GET /discovery/1/501 fails with following error message:

2016.03.10-14_23_42-hc_001

Unlike user objects, discovery objects have explicit IDs. Those are the IDs you need to use, if you want to manipulate a single discovery.

Read single network discoveriy: GET /discovery/{id}

Let us read a single discovery with ID=1: GET /discovery/1

2016.03.10-14_45_11-hc_001

I guess, you need to run a discovery first, which will populate the database with all network-devices, links, hosts, policies, etc. After that, the network-devices can be manipulated.

TODO: clear the network database, run a discovery and observe, what happens.

But for now, let us review the existing data in the network topology database.

Collecting Network Device Info

Read network device info: GET /network-device

Let us look for network-devices: with GET /network-device, we get a list of devices:

2016.03.10-15_50_25-hc_001

Read running-config of network devices: GET /network-device/config

That is interesting as well: we can retrieve the configuration of all known network-devices with a GET /network-device/config:

2016.03.10-15_55_27-hc_001

The id of the network device can be found if we scroll down:2016.03.10-15_56_30-hc_001

However, the config cannot be changed: there is no POST or PUT command defined for /network-device/config:

2016.03.10-15_58_37-hc_001

Summary

Cisco Application Policy Infrastructure Controller is a software based centralized provisioning system for networks running on Linux Ubuntu that provides administrators with the possibility to manage network policies (Security ACLs, QoS) from a central point using a modern RESTful interface. The software can run on either on physical hardware or on a VMware VM (ESXi V5.1 or 5.5). The resource needs are too challenging to be run on a developer’s notebook: 6 cores and 64 GB RAM (see release notes). However, Cisco offers Cloud based development sandboxes on DevNet. See here a catalog of APIC labs.

Using such a sandbox, we have demonstrated the usage of the north-bound REST API of Cisco APIC (= Application Policy Infrastructure Controller), a controller for automatic provisioning of Cisco based networks. For that, we have used a DevNet sandbox (registration required), a Cisco-hosted lab for developers. We have used the simplest species of those labs that is based on a pre-populated database with no real target network behind (southbound). We have demonstrated on how to

  • browse the API documentation
  • get an authentication token
  • show or manipulate
    • APIC users
    • network discovery tasks
    • network devices
    • and network device running-configs (read only)

The Cisco APIC offers many more features, which were not yet explored here. Among others, policies can be manipulated.

If you need to download the SW, it can be found via this DevNet page (use IE or Firefox; since Chrome is not supported; click on “3”).

Appendix: Does the Cisco APIC REST API follow REST best practice?

During the hands-on lab, we have observed that the Cisco APIC REST API does not follow REST best practices (another article on REST best practice can be found here):

  • the API is using singular nouns like GET /user for getting a collection of users
  • the API is not very consequent with the assignment of unique IDs:
    • for users, the name is used as ID
    • for network devices, UUIDs are used as IDs
    • for discoveries, incremented numbers 1,2, … are used as IDs
  • the syntax of the API for reading a collection depends on the object type:
    • for users: GET /user will display all defined users.
    • for discoveries: GET /discovery is not defined. Instead, only a paginated version of the command is supported: GET/discovery/{offset}/{number} will return up to 500 entries, starting with entry #{offset}.
      • I rate it as inconvenient that GET /discovery is not defined. I deem the developers will have had their reasons; maybe this is a measure to avoid too long answers or to limit the performance required by the requests?
      • pagination is a nice feature, especially, if used for GUI display. However, I personally like a more verbose syntax better: e.g. GET/discovery/pagination/offset/{offset}/limit/{limit} or GET/discovery?pagination=yes&offset={offset}&limit={limit}.
      • If an API offers pagination, it should do so with all objects. However, GET /discovery/1/500 is defined, but GET /user/1/500 leads to an error. On the other hand, GET /user is defined, but GET /discovery leads to an error.
  • The syntax for updating an entry is counter-intuitive and does not follow REST API best practices (IMO):
    • a single user can be read with GET /user/{id}, where the user name is used as ID. Following REST best practice, the same resource can be updated with a PUT /user/{id}. However, the developers have chosen that the syntax is PUT /user without ID, while the user ID is specified in the body. This makes sense only for batch bulk update of all users. However, the body contains a single entry only instead of a a list of entries.

Those are little inconveniences, we can live with, though.

 

7

CCIE Written HowTo — where to get the Questions from (also for MCSE and others)


Every two years, I need to re-certify for the Cisco Certified Internetworking Expert certification (CCIE). This time I intend to post my findings on this blog. I intend to describe where to get Example Questions from and how to read them (works for all Exams, not only Cisco exams)

Previously, I had planned to write following other parts:

  • Part 2: (canceled): hints about how to answer the R&S 400-101 questions — better see online version of 600 CCIE R&S questions from Feb 2016; it already has a good set of questions and answers.
  • Part 3: (planned): how to get Cisco Routing&Switching hands on experience using a GNS3 Cisco Routing&Network simulator or maybe better by using the Cisco dCloud, since GNS3/dynamips does not support the most recent IOS versions and the installation is not necessary with dCloud, saving us precious time.

Now let us accomplish part 1:

Document Versions

  1. (2015-12-09) initial release
  2. (2015-12-23) added some hints on my experience with A+ VCE and added a hint from an old colleague that the CCDP test 352-001 is easier to achieve than the R&S 400-101 test. I also added an online free resource for the R&S 400-101 test I have found.
  3. (2016-04-27) updated the link to the online version of the CCIE R&S questions from Feb 2016 (was a link of 500 questions from Dec. 2015 before); added Cisco dCloud link. In the last chapter, I also added a hint how to seach for a specific question and its explanation on the same site.

Tl;dr – Summary

We can retrieve example questions for certification from ExamCollection and read them using VCE Simulator from Avanset or BlueStacks Android Simulator on a PC. Alternatively, you can use VCE Simulator Mobile or A+ VCE on iPad or Android tablets. A+ VCE offers a demo mode that allows to see all questions with a trickThis link seems to offer a free conversion of the VCE files to PDF, but I have not succeeded to do so. There is also online repository of 600 CCIE R&S questions (Feb 2016). However, the free VCE files as well as the online repository seem to cover only ~60-70% of the questions you will see in a real test.

Where to get Example Questions from?

Free and premium VCE files with example question can be retrieved from ExamCollection after registration (for free). You will find all kinds of tests, e.g. Microsoft and Cisco using the search field. Also the new 400-101 Routing&Switching Test, or the 350-080 Data Center tests (to be replaced by 400-151 after June 22, 2016).

Last year I only have used the free VCE files, and almost 100% of the test questions had matched (score 944/1000). I intend to live with the free versions of VCE files this time again.

Alternatively, you might want to check out one of the many resources you find on the Internet nowadays. E.g., I have found an online repository of 600 CCIE R&S questions (Feb 2016), which comes with good explanations.

Note: this time I have found out that the free VCE files and the online version of the 400-101 test cover only 60-70% of the exam questions. I have not tested the commercial variants, e.g. on this link, but I guess, they will be more complete. For the 400-101 exam, the commercial variant currently has 937 questions instead of only 500 to 600 tests in case of the free VCE files and online repository, respectively.

A Hint to CCIE Recertifiers

Note: if you happen to re-certify an existing CCIE, an old colleague of mine had given me the hint that the CCDE test 352-001 test is easier to achieve than the CCIE R&S 400-101 test. The CCDE 352-001 exam has less questions (~400 questions in the buy-versions of ExamCollection) than the CCIE 400-101 Routing&Switching Test (~950 questions) and the latter test seems to be very challenging. Also the 350-080 Data Center exam seems to be very challenging: a colleague has taken the exam twice without success before switching over to 352-001.

Note: all exams are refreshed on and after July 25th, 2016. See e.g. this official statement about 400-101 or 302-001 from Cisco.

How to read the Questions?

The VCE files seem to be encrypted and require a VCE reader. The VCE reader I had bought 2 years ago does not accept the new VCE files. I now have several possibilities:

If you say, “buying is better than subscribing”, do not forget that you might not be able to open new VCE files next time you need to take the test. That happened to me: two years ago, I had bought the editor version of VCE Simulator from Avanset and I thought that I can use it for the next ten years. Now, two years later, the software refuses to open new VCE files. What a pity. Subscription licenses might not be so bad at the end.

Experiences with A+ VCE

This time, I have opted for the A+ VCE for iPad. Currently, this software has some problems (seen in iOS 8):

  • problem with pause function: if you pause the test and switch to Safari for Internet research, more often than not, the tests stops without notice when you try to come back and resume the test. A workaround is to save the session, each time before you leave the  to the other app.
  • crash problems with the timer: if the timer counts down while you are not working with the app, I had the problem that the app was crashing every every time I had tried to start it. After the re-installation, I was shocked that the software had forgotten, that I had payed for the buy version already. However, on the main page, there was an option to restore the add-ons.
  • problem with marked questions mode: if you learn all marked questions and save the session because you want to continue learning later on, the app gets confused about which question you were: e.g. if you have a VCE file with a total of 500 question with 250 questions marked, and you save the session at question 97 of 250 marked questions, the saved session will forget that you were in the “marked” questions mode and will show you question 97 of the 500 question (which may be a totally different question than the one you had expected.
  • Once, I had problems importing the VCE files from behind a HTTP proxy (“Invalid File”). However, the support team is very responsive and the problem was solved by directly connecting to the Internet.

All those issues were seen with iPad2 and iOS8 and might be gone with higher versions (however, I doubt it).

Demo for free

If you want to explore the VCE files before investing any money: A+ VCE comes with a free demo mode and you can view up to

  • 12 questions on BlueStacks
  • 61 questions on Android

You can also view all questions if you follow the instructions on this youtube post: the trick is: when you re-take the exam, before starting the test, use the slider on the botton to navigate to another first question. I have tested it and it works fine.

Also the VCE Exam Simulator allows you you import any VCE file and see the first 5 questions for free. This seems to work fine and a colleague of mine is using it with no reported problems so far (demo tested on iPad 2 and productive training on iPad 3).

PDF for free

This link and that link offer many VCE files also as PDF, e.g. navigate to the Cisco 400-101 files. Others can be found here.

Note: the first link pretends to offer a free conversion service of VCE files to PDF, but it does not work for me: to convert a VCE you need to post comment, but  there is no button or field on the page that allows you to leave any comment.

How to find the answer and explanation to a specific question?

If you find a question in the VCE or PDF (e.g. “Which three components comprise the structure of a pseudowire FEC element”) and you want to find a quick answer, you can try to search like follows using Google:

2016.04.27-11_30_02-hc_001

E.g. try: site:www.ccieexam.org Which three components comprise the structure of a pseudowire FEC element

The Feb 2016 questions and the Dec. 2015 questions of this specific site have proven to offer good explanations for most of the questions. Only, if the explanation is not sufficient or the answer is wrong, as happens sometimes, you need to dig deeper by omitting the site directive and work with a few keywords only.