One of the great things of all network virtualization solutions, is that they can be automated using some form of API that they publish. Cisco ACI is no different and offers a RESTful API which you can consume to do stuff on the network. Well, it’s a ‘sort-of’ RESTful API, as they only seem to use GET and POST functions, no DELETE, PUT, etc. Instead to delete an object, you do a POST with the status ‘deleted’. Anyway, details.
PowerTool
Cisco has a PowerShell implementation for multiple products, for example UCS and ACI. They call their module PowerTool and is generally pretty useful. However, it seems as PowerTools keeps lagging more and more behind the supported versions. Changes in APIs can make the PowerTool unusable for newer versions. Due to this fact, a few of my colleagues requested to collaborate on a custom Cisco ACI script that can be used to do the initial installation of an ACI network. This script has turned out pretty awesome and has cut the installation time from a few days to a few hours or so. While I can’t share the entire script, I thought I’d share the foundation, for anyone that wants to do the same and move away from the PowerTool dependancy.
The APIC
The Application Policy Infrastructure Controller (APIC) is the entry point of the ACI API. This is where you will be sending your HTTP requests/API calls to. First, you need to login to the APIC and get a cookie. After getting a cookie, use that cookie to authenticate your API call and actually do something. Calling the ACI API is pretty similar to calling any other API, so I was able to re-use an old PowerShell function which I use for pretty much every API script. The only exception being that it first has to login and retain the cookie, plus that the cookie can expire and the APIC will return a HTTP code 403 when it does. The function then makes sure it logs back in again.
API Inspector
The API call itself is directed to a specific URL and the HTTP body contains the settings of what you want to accomplish. The APIC has something pretty cool to help you find the right URL and HTTP body to use in your scripts; the API Inspector. The API Inspector is a window that you can open through the menu under your username, using the menu option “Show API Inspector”. You can use this window to sniff out API calls that the web interface is doing to translate your actions in the GUI to the API. The APIC web interface only uses API calls to do its work. Here’s an example of how it looks when you add an EPG:
I added a new EPG called NewEPG in the web interface and you’ll see that the URL was shaped to the EPG name and the tenant and application name. The body contains the bits that the APIC needs to add the EPG.
Adding EPGs in Bulk
After getting the proper URL and HTTP body from the API Inspector, you can use that to programmatically format API cals for bulk adding EPGs (or anything else, for that matter). In the example script below, you can find a simple function to interpret a CSV file, add an EPG and optionally add it to a vCenter instance as a portgroup. You’ll see the URL and HTTP body return in this example and variables filling up the name spaces.
This example script reads a CSV file and generates an API call for each line, adding an EPG for it. To run it, use the following syntax:
.\aci-create-epgs.ps1 -username admin -password mypassword -apic my.apic.hostname -CSVFile c:\aci-epgs.csv
The first 3 parameters are the details of your APIC. The CSV file is pretty straightforward, but needs to contain all information needed to add an EPG. Everything besides the EPG and its description, needs to exist for the API call to work.
EPG Name, EPG Description, Bridge Domain, Application Profile, Tenant Name, vCenter Name NewEPG1, my description, MyExistingBridgeDomain, MyExistingApplicationProfile, MyExistingTenant, OptionalvCenterName NewEPG1, my description, MyExistingBridgeDomain, MyExistingApplicationProfile, MyExistingTenant,
Conclusion
This is a very simple and quick way to get started with the ACI API and using the API Inspector it can be real easy to automate more of the ACI configuration. Have fun!
You can download the examples used above from my GitHub PowerShell repository.
Leave a Reply