APIC DC API Deep Dive

so hey everybody welcome thank you for so probably a lot of people that are at breakouts right now so small audience here today but that's fine makes it more personal so if you guys want to stop and ask questions at any point please you're welcome to I encourage it my name is Paul essiac I am a Solutions Architect with the Cisco advanced services AC I practice so I've been working with the NCMA business unit or formerly NCM II now I an SBU for the last two years working on a CI specifically around the api's so that's essentially everything that I've been working on working with partners for enabling them to make their products work with a CI integrating allowing them to leverage the API is more effectively on how to actually get that full and to end integration between what a CI can do and then what other vendors can do and how they can add value to what a CI is capable of providing so the topic today is a CI deep dive on the the api's so here's a brief introduction of I'm sorry agenda of what we're going to cover today we'll go through some introductory topics to sort of get your minds going you know switch over into this application centric way of thinking we'll go through the programmatic interfaces that a CI offers and then go into some of the real meat about how the API and SDK works there so how you can work with the rest interfaces how you can work with the SDK so on and so forth then you know you're gonna want to know how to get started if you come out of the session without knowing you know how to take your laptop and get all of the necessary documentation and python modules all that installed then I failed so please come up and you know maybe punch me or at least scold me because I want you to be able to do this after you've come out of this session we'll go through some best practices I've learned a lot about this product about these interfaces over the last couple years so I want to make sure that I impart some of that knowledge for me to you guys and we'll go through applicability like where other people are using this and then finally wrap things up so does that look good to everyone yes okay yes good enough so before we get into the introduction here how many people in the audience are familiar with ACI have some familiarity okay great a little bit okay so how many of you are developers by trade okay couple how many of you are Network focus guys okay so for the the developers by trade there's a lot of content in here that is very much code specific but seems a majority of the people in the audience are network based guys and I might sort of go a little bit into too much detail beyond what you're interested in so what I'm hoping to do is at least give you the references give you the information and then you have the slides to go back to to see you know hey you know he talked about how we can do these lookups by class or by DN or whatnot how do I actually implement that and so you'll have this to go back to and at least give you some of the theory for the developers in the crowd please feel free to stop and ask me more questions if I'm not going into enough detail so goals for this session I want to introduce you to what ACI what the APEC data center can do that's gonna be a brief overview but at least to sort of prime your minds to begin thinking about that educate you about the programmatic interfaces so you'll know what's there give you the steps to get started with that SDK and then again provide those best practices all the stuff the agenda what is not in scope for the session is giving a very comprehensive course on Python if you're not familiar with Python then you know it's one of those things that it could take a week or two potentially longer if you don't have any programming a background to become familiarized with so that's something that's not in scope there I'm also I plan on doing a comprehensive class on the AC I simply because it's a huge solution in and of itself so it's very very difficult to teach that in a one-hour session that we have here so as far as leveraging programming let's look a little bit about why it's applicable so why do you want to leverage these programmatic interfaces well for the first item that I think everybody would agree upon speed how many people think that they can go and configure a router quicker than some scripts that could do it anybody okay so I'm glad because I mean I'd I typed pretty quickly but I can't beat something that's that's written to actually do it I just don't have that ability to type so quickly efficiency and cost right a perfect tie-in to doing things in an automated fashion is that you're going to increase your efficiency if you I mean look at the Industrial Revolution as machines began to do some of these tasks it just wasn't possible for one guy the assembly line to go and build engines as as quickly machines are just gonna be better at doing it because they're custom-made for it and computers are very good at doing the same thing over and over again but people have to teach those computers how to do it and that's why this program ability is so important and then the quality of course right how well the the consistency of the information that comes out of the system is applied is going to be directly tied to how well your code is written and then how well it's able to consistently execute one person people are just not very good at doing the same thing over and over again you get tired you start to fat-finger things yes a lot of things get into muscle memory but we just can't can't do it we wear out after a while so who is interested right again I mentioned a lot of partners that I'm dealing with the list is probably you know three or four pages deep in terms of partners that were going with there's a lot of them that I'm interacting with on a daily basis and they're very interested in leveraging a CI and the programmatic aspects on how to actually go and automate these these products customers I'm also working with a ton of customers I am in the advanced services group so I see that customers are actively looking to leverage these technologies these new interfaces to go and automate their networks they're not looking at doing things in a very manual fashion anymore a lot of them are not looking to leverage even off-the-shelf products for this they want to go and build it in-house the same way that a lot of customers are going and building OpenStack portals in-house or maybe internal IT provisioning portals that they want to do the same thing around a CI and begin to automate that on their own system integrators Cisco within the Cisco IT organization there's a whole lot of automation and orchestration that's taking place so essentially everyone I I bet that you know we could probably pick a few people out of beyond the audience around here and they're probably saying yes I'm looking at automation yes I'm looking at programmability because it's a really hot topic nowadays so I'm glad you guys are here to learn about this because it's really gonna help you increase your value as engineers so the how right this is the most important part I think because you can have the motivation you can be the right person but until you know how to do it you're not gonna be able to get there so what are we gonna look at doing we want to automate common tasks those could be troubleshooting tasks those could be maybe monitoring tasks gathering information sort of processing it to display it in a better fashion than what is natively available out of the system so that's a big one deployment tasks I've got a lot of customers that are using the api's on ASIC to do huge deployments like taking on a on a cloud stack environment where you need to provision a thousand VLANs on every single interface across hundreds of leaves if you go and you try to do that manually I guarantee you're gonna be in there for weeks clicking through buttons to do it and so we've worked with them to to automate these processes it's done in a matter of minutes which is a really really great benefit of this so we know how to leverage the programmability now let's go into a little overview about what a CI provides you so the ACI solution is a really comprehensive and and why this scaled solution it's not looking to just address network problems it's not looking to just address layer two mobility or anything to that there's innovations that go all the way up and down the stack from the physical layer up to the application layer so at the physical layer we've introduced all sorts of new technologies including 40-gig by dye optics mid plane lists chassis so the fabric connects directly into the line cards we've got new merchants plus silicon so there's a whole bunch of innovations that just take place at the hardware level but we've gone a step above that right we've made new innovations on the network side so using is is with non IP based interconnectivity between the spines and the individual leaf nodes right all of the the discovery of the fabric is automated so you're no longer going and building out on a node by node basis the management is done across the board through your a pic controller so there's a great amount of innovation there at the network layer look at the virtualization layer right we've gone and we've very very tightly coupled with hypervisors that can connect to the fabric so when you create a network policy it gets pushed down into the hypervisors so that you're no longer going there and manually stitching VLANs to go from your leaf to your virtual switch instead it's automatically created for you and you can go and begin to place workloads in there now imagine what you could do if you pair that with the automation capabilities of a lot of these compute and virtualization platforms with a fully automated fabric that means that 100% of your IT provisioning process could be automated which is like the holy grail of all IT operations so it's a fantastic advantage there and then I touched upon the application tier we've got this new way of modeling applications use it using what are called application profiles and with this technology with this methodology we don't look at representing applications as just V LANs or subnets or maybe a set of access controls but rather we model the complete application with the different tiers of it look at the web tier the application tier the database tier the communications between them and then map them accordingly and push that down into the infrastructure so it's a very holistic solution that works on many different levels and so makes it very very powerful in terms of what you can do so in terms of the the semantics that we're dealing with ACI takes application level semantics and ensures that there is no loss of data going down from ACI into the configuration you have a complete picture going from the top down into the bottom it also allows as I mentioned earlier you've got the a peak which is like that central point of Management but not a single point of failure that gives you a singular view into the fabric that provides you a bunch of information about statistics information counters false configuration all of that is available through the ethic but it looks like a singular entity so you're no longer managing switch by switch looking at you know what is the the OSPF neighbor state on this device what is it here how do I sort of correlate to over you have a singular view of the fabric so it acts like a single monolithic entity now finally all of this is based about open standards and open api's so we haven't gone and created a solution that's extremely proprietary we want to make it available to others to go and integrate with so if you wish to add some new functionality to your your ACI fabric you're not limited to what Cisco can do you're not limited to what a third party can you can go and actually extend it yourself either via the northbound API or southbound API so you have a lot of possibilities a lot of new ways to extend it now all of this configuration is not based on what we're used to in the current days of router and switch configurations I'm sure how many people in this room have gone in and typed compte on a router or a switch okay everybody I hope right even for the developer guys you've probably done it at least once or twice well compte is gone I'm sorry to say it's it's no longer there the way that we now represent configuration is through this very object-oriented object model and what the object model is meant to do is take every aspect of what can be configured within a data center the the network layer but also including compute an application and represent that in an object-oriented fashion so now an OSPF router is no longer router OSPF 10 and then an area area idea ID under that you know some some authentication properties so on and so forth instead it's an object called an OSPF router which has properties on it that can be set and that OSPF router will have children beneath it that define the interfaces that are part of that and so when you go on you query for OSPF routers you can deal with those in a very programmatic fashion and I'll show you in a little bit how we can do that again it's a tree based hierarchy so if you're familiar with the SNMP mid tree you're familiar with the MIT you know how to sort of go down through the different layers and you know look at the the top layer CD into lower layers get more information on it it's got different branches to address various layers of functionality so as an example the policy universe configures all of the tenancy all of the contracts and how objects intercommunicate you've got the compute universe that's where you'll see all of the physical compute nodes and all other entities so there's a lot of different areas here that are described and they have different logical branches to contain that information each of these individual blue dots here which very very simplified the blue dots are a little bit easier to comprehend than having full C++ code on the screen but each of those little blue dots is a managed object and so when you hear the term managed object you're essentially referencing one of these devices or I'm sorry one of these nodes that has been instantiated so there is a very fundamental difference between a class and a managed object a class is really just the definition of something whereas a managed object is the instantiated instance of that particular node each of those managed objects has a class and a distinguished name so that tells me what it is and then who it is so you're able to differentiate between those very very clearly and then finally this is a very critical component to program out programmatic interaction with a pic all of the dealings you're gonna work with a pic on through the northbound API are going to be done through this object model so it's an important topic to sort of have your head start to wrap around so speaking of the programmatic interfaces I talked a little bit about northbound and southbound here's a little bit more detail about just exactly what those are so the northbound interface is essentially from the top from outside of the fabric entities that wish to program a pic are gonna do that through the northbound API so if you have automation tools orchestration tools you write a couple of scripts that are going to maybe go and query information from the fabric and type it out to external entities you'll do that through the northbound API and that northbound API is enabled through the rest interface and the cobra SDK the southbound API on the other hand is how epic is able to take its knowledge it's decorative state of the network the desire state and push that down to other entities so through protocols like op flex and through built-in sub api's within a pic like device packages it's able to take the intent the desired programmatic state that you push in through the northbound API and then push it down to subordinate entities that a pic is managing and that makes for a very powerful way to allow for you to not have to go and say I'm gonna automate 90% of my fabric but instead I'm gonna automate 100% of it because now I can take all this policy that I'm pushing in and get it down into the firewalls the load balancers may be other switches and hypervisors that are connected to the fabric so as far as the rest interface goes on the northbound side that's where the majority of the scope of the session is the southbound API itself is a very very very big animal right there's a lot of details to it there's white papers on CCO that you could read about if you want to know more about that if you're interested in developing device packages but for the scope of the session we there's just too much there to cover so let's go into what the northbound API provides to us so given that we're very dedicated at Cisco to leveraging these api's to making programmatic interactions something that all of our customers can consume we're also eating our own dog food right so our GUI our CLI web browser access that you make to the to the apec all the API tools the SDK itself all of them are going and talking to this REST API we don't do any any tricks where we say oh well you know this function is not exposed to the REST API so we're gonna go there and and do it some tricky way that you guys don't have access to know everything that you want to do with the fabric that we do through the CLI through the the rest interface I'm sorry through the GUI all of that is done through this this REST API and you can use that REST API to access your a pick cluster your leaves your spines everything that's in the fabric so we've we're very open about this and this is very beneficial to you guys who are going to be deploying this because now there's nothing that is is he didn't away from you you're available or you're able to access all of that as far as features and functionality of the REST API it is based on Native rest so it's got all the benefits they're stateless you know is HTTP based self documenting all of that we've got an extremely robust querying and filtering interface and I'll show you some more details about that now in that object model I talked about how much information is provided there well if you have all this information in the world it's not very good to have it there without being able to filter through it to sort of figure out what's there so we've provided a very very powerful filtering aquaria mechanism there there's no artificial divide between your configuration and administrative state and what that means is that on a router or a switch today you go and you issue show commands to get your operative or administrative state right and then or rather just the operable state and then you use compte to change administrative State to change the configuration so there's this this divide between them you can you can see show run to see what I'm trying to do and then you do like a show in tour show IP ospf neighbors to see how things are actually running and this can be you know a bit troublesome especially when you're doing things programmatically because you can no longer rely on one source of information to get everything that you need instead you can do multiple queries and look for it in multiple different places so this is a very very powerful important parameter here the object model supports the ability to overload the state of certain attributes there so that if you want to write a stateless application that just goes and uses a pic as your your data store how you're going to managed programatic state in there you can overload fields in there the description fields the owner key owner state all of those so that your application can go and sort of establish its state there so you can read back and see hey what did my app do here keep track of what maybe was a change that you made versus what was a change that a user made manually so you can ensure that the state is consistent then finally all of the objects that are in the object model do in fact support event-driven notifications so when things change on the fabric you're no longer left to polling and repeatedly ask it got a given interval what is happening but you're able to get notifications immediately it's question just what to talk about a minute ago configured an operational state provided to the same interface does it mean that I should not must not cannot actually go and do comforter on the devices that interact there there is no CAF term on the devices anymore the question was can you use compte on any of these leaves and spines and the answer is no cavity is is disabled as a CLI yeah but controller will also go and configure a essay or NetScaler something like this so I should not go there I mean I can right go to Netcare for example and do something but probably I should not that that question has a very detailed answer and maybe afterwards we can discuss it but essentially it depends on how the device package vendor has implemented their device package that's going to determine whether or not you can go and and manually configure them if you're ok with it maybe come up afterwards we can have a long discussion about that so again event notification you can get interrupt-driven feedback to your applications so you're not sitting there constantly checking it so we've got some background on object model what we can do now let's get started right let's make this into something where you can make it tangible so the first thing to get to get in your mind here is this REST API so the REST API is standard rest interface you've got get you've got posts you've got delete you don't have put because they sort of merged put and post together but essentially all these operations follow the standard rest definition get is used for reads that's a militant operation so if you do a get it's if you run it zero or more times the result will always be the same if nothing has changed on the back end so essentially it is to say it's a read-only operation by doing it you don't change anything post and delete those are both identity operations meaning that if you execute them one or many times with the same input they're going to result in the same output so as an example if I go and try to create the same tenant over and over again it's not gonna create a duplicate tenant instead it's just going to go into the apec API and say hey this tenant already exists I don't have to duplicate it so that's an important thing to understand here especially when you're dealing with it programmatically because you're you're not forced to check you know did I already create this is this here yet instead you could just say hey I need this to exist let me create it the only case where you might want to check is you know if there's two people that have conflict inconsiderate essentially from a programming standpoint you don't have to make those preliminary checks on it all of this is sort of detailing the the rest based attributes of it any apec in the cluster can handle it it is stateless sessions and requests can be sent to any epoch in the cluster and if you want to access leaves or you can do that through the a pic so you're not limited to just talking to the a pic you can talk to any node in the fabric and again the goal of this REST API is to give you the ability to read and write and and modify objects so as far as reading goes this is going to be your primary interface into pulling information out of the REST API so you can see here it's a fairly simple HTTP URL the first part of it is really just your your host your saying it's gonna be an API operation but then somewhere in the middle over here we see the ability to talk to either an mo or a class well an mo is a managed object I talked about how every node in the tree is a managed object that's what we mean here so if I want to go and talk to something specific like an individual EPG EPG being an endpoint group that represents a grouping of logical entities on the fabric I would reference that as an mo if I want to talk to a certain set of classes I can do that by making a class based query so I could say get me all of the information on layer 1 physical interfaces which is sort of like if you wanted to do a show int and then include on 10-gig interfaces that's how you would go and do the equivalent on the ACI fabric the rest of these parameters are really just giving more details more quantifiers about what you're trying to do filtering just returning certain objects with certain attributes all all of that so that takes care of reading information out what about if we want to push information into the REST API well that's where these create and update operations are used and this is essentially a post that's going to include a URI that describes what you want to do and then a payload that's going to be either XML or JSON that describes what it is that you're going to post there so we see here we've got a payload that includes a tenant the FV in front of this tenant is the package name the tenant is the class name and ultimately what that does is create a new tenant in the fabric we create an application profile so we've got fabric virtualization as the package application profile as the class name and that's going to create those certain objects in there and then we go and we attach an interface within an EPG to that application profile so essentially what you've done here is you've said I am making this interface be part of this EPG so if you look at the way you do it today when you go and you say switch port access VLAN what am i using here VLAN one that's essentially what you're doing here but for an EPG so that payload is just a XML or JSON representation of what your desired intent is now given that we have the ability to read and write information out of the REST API we also want to have the ability to browse through it because you don't have to go and write read queries to get every little bit of information out of there you would like to be able to browse them so for that purpose we have this object browser called vis or a and vis or a in Italian means viewer is there anybody Italian in the audience can you confirm that for me does it doesn't mean viewer right okay good thank you because I've only been told this by the developer who is Italian he may have been lying to me and that object viewer that browser allows you to find information about objects in the object model so in this case we're looking at a top system object and we get all sorts of information about it we get its address on the fabric we get the distinguished name for it so remember the managed object ID each of those has a distinguished name which shows who it is and this is what that distinguished name looks like we get information about who it is in the fabric MAC address all of these details so from a view point of dealing with this programmatically missoura is going to be a very very useful tool in your toolbox because you're going to be able to see in the current state of the MIT what do these objects read back how can I you that within my program to extract more information and make it more rich and show more details so it's a very very powerful tool here are a couple pointers just on how to access it and you could do both class-based queries and object based queries on VA's or a so the zora is good for seeing what's already there but what if you want to see how the GUI or how the CLI are making configuration changes well for this purpose we have this tool called the API inspector and the API inspector is really it's it's like Wireshark but for the GUI of a pic so if I am going in there I'm very new to a pic and actually I still do this today right I don't know how to how to do in the API what the GUI is doing because there's you know a lot of moving pieces in there or maybe it's dealing with objects I'm not familiar with so what I can do is use this API inspector to actually sniff what the gets what the posts are see what the payloads are and then sort of see how I can duplicate that on my own so a quick example of walking through how this would work we're going and we're creating a tenant here it's a little bit small but that tenant is called Cisco so we go through and the GUI create a new tenant then it's going to ask us for some more details it's going to ask us for a vrf that we want to add to it in this case you know I think I added one in the workflow but we'll take a look but we add that information and then finally in the API inspector and this is what it looks like it's really just sort of a logger it shows you all of the calls that have been made so some of this is pretty small but if you look at the slides afterwards you'll see there's a bunch of gets taking place to see what is there you also see that there's a bunch of or there's at least one post at the bottom and that last post happens to correlate to the request that I just made to create that new tenant so over here you can see that I've posted to this a pic with this request URI which probably looks familiar from a few slides ago when we had how to write information into the REST API and then here's the payload in JSON so you can see here all of that theory that we just talked about is actually applicable and visible very easily consumable yes question how does the authentication work so authentication is something that I'll cover in a little bit there's it's it's a separate actual call that's made but we'll go through this these calls are all authenticated what's shown in the the API inspector does not include all the authentication tokens all that because it's assumed that if you got to API inspector you already know what your authentication credentials are and all that and actually you're gonna see it in two three slides so a very very relevant question so again you've got details as to how you can go and interact with the REST API just based on sort of watching and learning so getting started these are the sort of steps are going to go through now here's the guy helping the lady find a topic in a book I thought it sort of fit well together I don't know but anyway the first things you're going to need the SDK and the documentation again this is a reference slide please go and download these slides after the presentation will be available on the the dev net page and you'll be able to have all this for reference but the Python SDK is available on definit so is the documentation on the model reference and you can also access that on your APIC if you happen to have one so once you get the SDK going and installed you're ready to move forward one note to remember if you're gonna download the eggs from your a pic make sure to rename them there's a document right down here in the bottom that explains the process there so just hit that URL and I shortened it so it might be a little bit easier to type but hit that and then it'll provide more details there but so just some steps you have to go through to get it working but once you've got all of this information sort of pre-populated then we go into the topic of authentication so what do those authentication requests look like well I've got both of the side by side over here we've got the rest requests and we've got the Cobra requests so on the rest side it's fairly straightforward we send a post preferably via HTTPS by default HTTP is disabled so you know if you want to enable that do so at your own peril but I would prefer you did HTTPS and we post a request to this API /mo slash triple a login so there's a set of rest calls that are specific to sort of these non authenticated operations that are documented in the rest user guide which is also from the last slide and triple a login is one of those and what we're gonna have in the payload is essentially username and password and what we get back from that is an authentication token so that authentication token is going to give us our 60 sorry our base64 encoded cert that essentially says here's what identifies you as you and if you include it with the rest of your requests they're gonna be authenticated if you do this through the SDK it's a little bit simpler because you don't have to go and track all of that you don't have to go and build your post all that simply a matter of importing the appropriate Python modules and then you create a login session you log into that mo directory which is what it's called because you're accessing managed objects and then you've got a session that's authenticated so authentication is fairly straightforward there's not a lot of tricks to it the one thing I would mention is that aside from doing a standard login session you also have the ability to do a cert based session so that means that if you have a program that's going and logging in and doing tricks maybe you don't want to use a username and a password to modify the APIC but instead you want to say give my program a certificate that he's going to store locally in a secure place as a private key and then he'll authenticate enta kate with a pic to see what he could do based on that certificate so that's also documented in the Python SDK just how you can do that in case you want some more information that so we have the ability to log into the APEC to establish a session now let's look at getting started with pulling information out of it some really really simple straightforward objects so again rest and Cobra examples side by side to me I always go the the Cobra side you are not gonna find me going and writing a lot of direct rest calls simply because Cobra does all the work for you you don't have to go and remember any complex rest syntax you have to go and manually parse any of the XML instead you get all the information back in nicely structured objects that sort of tell you what is what is what and what is adn what is a property all that so in any case if you want to go the rest approach well then we're gonna say get API slash class so I'm doing a class based query and I want to look up all of the objects that are of type FV set so remember the FV is the package name so that's fabric virtualization and then the set part this is client endpoint so essentially what this is going to give me is all of the server's all of the hosts that are attached to my fabric that's what that client endpoint means and what I get back in this information is the MAC address of it the IP address of it if it happens to have an IP in this case I was using a layer to bridge domain so it didn't have one associated with it and it also tells me the containment of what application and what EPG gives you so if you just think about this how can that information be leveraged well it means that I can go and query for every server on the network and be able to know what application it belongs to and that could be a very powerful thing for just resolving your cmdbs your single source of truth trying to make sure that what you have that's documented is accurate with what is the operable state in your network you can use it for a whole bunch of other things without just one idea as to how it could be useful we could do the same thing with Cobra by simply doing a lookup by class which again means that I'm looking for the the what rather than the who so I'm saying find me all the client endpoints and then I'm just doing a this is a very compact loop over here so again for the Python programmers problem makes perfect sense for anybody with a network background if you want to learn more about how this works look up list comprehensions python list comprehensions and you'll find out all about that it's really just a way for laying people like me to show off that I can combine everything in one line but that's so again our output is we've printed out all the distinguished names for these objects a little tip down here if you wanted to maybe debug cobra to see hey what's the rest call that it's making to do what I'm calling over here it's very simple import HTTP lib and then set the debug flag to true or two-to-one there so that's sort of a a simple example of using a a look-up by class let's take it a little step further and do a slightly more complex query so that lookup by class that we did is really just another wrapper around this dot query method and the dot query method exists on our mo directory object so over here what I've done is defined a function that's just a recursive displayer recursive print out of what's in my object hierarchy and I'm building a class query so where as on the previous screen I was using look up my class on this screen I'm saying build an actual class query and then set some attributes on that class query so when I set these attributes it actually goes and sets query string parameters in my lookup so then when I go and execute this doc query I print out the entire nested hierarchy of my class structure so well you could see here is that the output says you know print tree endpoints and I get my FV set but I also see that there's a bunch of other information underneath it all this other rig useful information is included in the MIT and if I were to print out more details about it I would find out what the name of the virtual NIC that's attached to this end point is I would also find out what the name of the VM that it's sitting on it's residing on is I could find out what the path to that particular node on the fabric is who the hypervisor is all this information so like you could imagine just by doing a simple thing like looking up client endpoints what type of information you could find out and then leverage that very effectively in applications that you're creating so it's a really powerful powerful object model with a lot of information you could query out of it so in that last slide I sort of showed you the dot subtree of filter parameter well there's a bunch of others here that map between the rest API and the kobra SDK this slide please think of it as a reference because I doubt that anybody in the back row can read this so you know maybe get the slides afterwards and you can read through this but it's very you know handy to print out at your cubicle and put it up on the wall just for if you're coding with this fairly often but essentially it's a matter of how you map the Prarie strings to the SDK so we've got an idea as to how we can query and read information out of the rest SDK or the REST API now how do we write information to it well again there's the rest method and then there's the kobra method essentially in the rest method we're saying let's build a tenant set some properties on them and then post them and that goes and creates that tenant and remember it's a I dumped it in operation so I could do this a hundred times 50 times a million times and it's not going to make a difference it's going to be the same result here we see how we can do this using the Cobra SDK so what we go through is we build the objects what we want to do we add them to a commit request or to a config request and then we commit them so build add commit and that's sort of the process you're going to go through and that will actually go and create objects for you so you see here that the code on the right to actually build that object hierarchy is a little bit lengthy because you have to go in and tell it what you're talking about well I am lazy very very very lazy and I would found myself doing this a lot and I didn't want to have to write the code manually so what I did is I created this tool called Aria and Aria is essentially a tool that allows you to take XML or JSON code that you capture either using the API inspector or your VA's or a tool or really any of the other ways that you can extract the XML or JSON from a pic and you feed that in as XML or JSON JSON and it spits out the Cobra code for you so like if you're a networking guy that is maybe a little bit you know not not looking forward to approaching Python or learning how to program or maybe this seems like it might be too complex go to this URL right here look at Aria download it it's gonna be your best friend if you want to go and create rapid prototypes for configuring and automating your a pick it's gonna allow it for you to very rapidly develop code so it's a fantastic tool from that extent so I wanted to give you a little use case here just how you can leverage all these pieces of information so simple use case here I want to get my OSPF neighbor ship information so in this case you know it's a typical operation to go and check with your neighbors are let's go and do that not just for a single leaf a single border leaf on my fabric but do it for all the border Leafs on the fabric and even take it a step further and show me what faults are present so you know this guy seems he has two two faults on there let's see what those faults are so we've got a simple set of code over here in the top part we're fetching our OSPF neighbors to do that we just query our OSPF adjacencies EP class and you can get this information again by looking through api inspector and looking at the GUI we're also including a subtree include that says show me the faults on it and then once we have that information it's gotten all of our OSPF neighbors and then all we have to do is go ahead and print it out in a fashion that's similar to how iOS or nx-os does it so let's see what this what this gives us I go and I run this script and it prints out for me again very similar to iOS and nx-os the neighbor ID the priority of that neighbor what the state of that routing adjacency is or neighbor ship is shows me the address of that tier and even the node the leaf that is trying to communicate with it so again if you don't want to go and have to check the OSPF state on every single individual leaf in the fabric using the GUI you can go ahead and use that script that's right on the screen and have it check it for all of them and not only that but we also print out the faults that are present on those so in this case the first one we see that it's stuck in the X start state so it's not not going and actually creating a an adjacency we see that actually a couple of them are stuck in that state this last one I think I configured a non-existent OSPF node there to get that so you see was what's being spit out there so again we we have an idea as to how the object model works how you can read information out of the rest api how you can write it how you can do queries even have an example of how to go and actually actually implement a useful use case so now let's go into best practices now a lot of this stuff is information that I've learned on my own because I've done it and I failed miserably and I found that hey you know what I should probably figure out a better way to do this or you know maybe it's it's just not the right way so a lot of this is is failure that I've experienced that I want to help you guys avoid so please write these down somewhere and when you're writing code you know just sort of reference them so here's some of the topics I'm going to cover and this is just sort of like the sub agenda so I'm not gonna go through them instead let's start jumping into them so within that object model right that tree based hierarchy what you'll find is that there are a lot of references between objects and what I mean by the references is that one managed object might point to another one so if I want to have an EPG that goes and adds a an interface to it that's going to be a reference it's gonna go from one object to another and when you're going and creating these these references it's highly discouraged to hard-code those references so as an example in this code it's sample of up here I'm not going and attaching an actual object I'm going and attaching the string that represents the distinguished name of that object which is typically a bad practice because I've just hard-coded that in there if that interface changes or if maybe the structuring of those distinguished names changes that could bite me in the long run you know I'm gonna have to go and find somewhere in my code where am I statically building these strings so instead it's highly recommended to use a lookup find out what this object is figure out who it is and then use the dot DN or maybe the dot name property on it to reference that particular string that would otherwise be hard-coded so that's that's the first one here and this one is a really important one you know we go through it a few times it really just goes back to avoiding hard coding in your code it's a fairly best practice in general a commit and query granularity so when we look at the rest api again it's a directory based structure so if you go into maybe your root directory on a linux box and you do a find command there and you say find this this specific file it's not going to go and get just search just the directory that you're looking in it's going to look through all of the directories so that means it's going to be very slow it's not going to be a quick operation so that's why when you're doing commits and queries on the REST API for the same reason you want to avoid doing things at the top level and instead doing them do them at a very specific level as specific as you can get so let me show you what I mean by that right I want to add a new endpoint group and that endpoint group is going to be part of a tenant called Cisco an application called new EPG call it new EPG now if all of this information here exists then I want to go and not just add the top of it because I'm gonna have to tell a pic all right add this or go into this Tennant go into this EPG go into this particular end point groups I want to add and then it's gonna have to go and navigate through those directories instead I can go and say no just add the EPG that I've added so then my query string my actual post URL is going to be very specific to the point about this EPG is what I'm working on as opposed to saying I'm working at the top level so that's sort of what I mean by that example a note this technique technique is not going to work if the hierarchy above what you're dealing with does not yet exist so just a heads up on that one if you're creating a new tenant you're gonna need to create that tenant and sort of work through it again I mentioned avoiding hard coding distinguished names so in this case up at the top line we see that we've got a from string on the DN method to look up a particular DN now within a pic a lot of the very critical classes the managed objects luckily for us they have fairly static distinguished names so common things like the infrastructure management management tree branch is something that's fairly hard coded so instead of having to go and resolve it from a hard-coded DN and sort of build it out I can instead go and create the objects that are going to be static that represent it and then go and add some interface policy on it so in this case I'm simply creating a new LACP link aggregation profile so instead of going in and saying okay here's my DN for it and then I want to create it there I can instead build the hierarchy to it and then reference it so this is a fairly you know it's not a hundred percent applicable but if you can follow this rule this sort of plays into the next one right how many people think that it's quicker to go and say look up something from the a pic get the end back and then go and post something to that DN versus going and saying here's what my DN is go and post it anybody want to say the first option is faster than the second good you guys are all very smart because it's not right you're doing two queries over the network instead of one query over the network so when you can avoid doing a lookup by class or a lookup by DN on hard on static DNS because it'll make your program a lot quicker to execute you're just gonna issue the one post or the one rest query to get to that information while building all of it in local memory and then it could be immediately used so it's a lot faster this neck is best practice is sort of I mean it's both in in conflict and in agreement with the zen of python does anybody know what the zen of python is if you go into a Python interpreter and you type in help this it has this this little poem by forget the name of the the guy but one of the developers of Python I don't think it was Guido but it pretty much has a list of things beautiful is better than complex or beautiful is better than ugly explicit is better than implicit sparse is better than dense well when you're dealing with the rest api it's a little bit better to use implicit properties what I mean by that is use the defaults because the rest api is smart it will go and populate defaults that are correct or preferable for your version of a pick and then for things that you don't populate there it'll automatically fill them in so you're able to just sort of build a very simple configuration on your side and then have a pick fill it out the same thing applies for tree structures you want to make them rather sparse as opposed to dense so when you go and you build out an EPG don't go and build out all the monitoring policies underneath there don't go and build out all the relationships that are sort of implicit that already exists there just filled out the defaults that are necessary and the reason to avoid that is because adding those in there is going to bloat your code and just make it very very full this next one I mean this is like when I first started learning Python I thought it was so great that I could just say from a particular package or module import star because then I don't have to type the entire namespace of it and then I quickly quickly realized that I was running into situations like this right what I was doing is I was clobbering objects in my namespace so within the object model of a CI there's about 5,300 objects and those 5300 objects do have namespace collisions they do have identical identical names between different namespaces so if you go and get into the practice of saying from an entire package import a particular class you might need to use another class and then you're gonna clobber the namespace of the first one so instead I would recommend one of two things either import your namespaces and maintain them individually or use aliases to avoid the clobbering of different objects and different namespaces this last one server-side filtering this is again you know you want to go and and minimize the amount of information that's trapping transported over the network so given that we have that really powerful querying and filtering interface leverage that as much as you can it might be a little bit difficult to get the query working just the way you want it but practice take a few shots at it email me I can probably help you with it and then you'll get back a smaller set of data so in this case I want to find the the managed object for interface one one on node 101 so what I do is I do a class query for a particular node I filter on that node and then I say I want to get the children where the child name is fabric path EP and then what I get back is a list of the interfaces on there which is actually going to be lift in cobra 1:03 that will allow for me to just return the DN of that interface so instead of getting a list of all of these objects all of these fabric path endpoints I can get just a specific one which will greatly increase the execution time how are others using this right so again I've mentioned that a lot of partners are using the REST API for taking businesses where they're based or where they specialize in modeling applications business rules the workflows and then converting those into something else useful in IT infrastructure so what we see is I don't know what's going on with the screen here but what we see here is that you could take a direct translation of the business rules and apply those into application centric policy another use case of what we're seeing it large deployments automated deployments making large repeated steps and doing those very very quickly within Cisco were heavily leveraging the REST API all of the testing for a pic is done using the REST API using Cobra to fully automate and QA the development process within advanced services we use it for automating test beds for customers and making sure that the functionality that we guarantee is working for their environment and then finally Cisco IT itself is heavier G Level II leveraging the apec automation of capabilities so I think that I mean hopefully you guys have gotten idea as to how powerful the REST API is you see that people are using it today it's it's a really powerful way to manage and interact with the data and it's gonna knowing it is going to really increase your value as an engineer as a developer being able to go up the stack and deal more closely with applications be able to sort of merge your skill sets and be more effective as a engineer and as a person so thank you guys very much I appreciate you coming I know were spinning finishing just on time if you have any questions please comment and ask thank you so much have a great day you

Channel: Cisco DevNet

Views: 8,157

Rating: 5 out of 5

Keywords:

Id: I-LJDPnKNfU

Length: 59min 37sec (3577 seconds)

Published: Mon Mar 09 2015