Introduction to ACI Programming and APIs Paul Lesiak, Solutions Architect BRKDEV-2971

Transcription

1

2 Introduction to ACI Programming and APIs Paul Lesiak, Solutions Architect BRKDEV-2971

3 Abstract Introduction to ACI Programming and APIs This session will offer an introduction to Application Centric Infrastructure. It will present the basic constructs of ACI policy including application profiles, endpoint groups, and tenants. It will also discuss the programmatic APIs, including Python and REST, available to create and manage ACI policy, and best practices for programmatic interaction with ACI

4 Agenda Introduction Overview of ACI ACI Object Constructs Programmatic Interfaces Use Cases Best Practices Conclusion

5 Introduction

6 Introduction Goal for this session: Introduce attendees to Cisco ACI and APIC DC Educate about the programmatic interfaces available Give steps to get started with developing for APIC Provide best practices for working with the API and SDK Out of scope for this session: Comprehensive course on ACI Teach Python programming

7 Business Value Stack $$$ Knowledge Business Applications Infrastructure

8 Leveraging Programmability Speed Efficiency / Cost Quality Partners Customers Integrators Cisco Everyone Automate common tasks Troubleshooting tasks Deployment workflows

9 ACI Solution Overview External Network POLICY WEB POLICY APP POLICY DB Application APIC Virtualization Network Physical HYPERVISOR HYPERVISOR HYPERVISOR

10 ACI and APIC DC Application Centric Infrastructure (ACI) represents network configuration with application based semantics Fabric functions as single switch: Scale, Mobility, Telemetry, Automation Cisco APIC is a centralized point of management for physical, virtual and cloud infrastructure Robust implementation designed around open standards and open APIs

11 Unflattening network configuration Network configuration today is based around flat configurations This does not represent the richness of applications and business We need representation as something more flexible

12 ACI Object Model A modeled representation of everything APIC knows Network, Compute, Application, etc Management Information Tree (MIT): Tree based structure poluni toproot compuni MIT has distinct branches for different functional areas Every node is a managed object: has a class & distinguished name Critical component to working with APIC, beyond programmatic interaction

13 Network Config as Object Model Network configuration is represented as tiered objects Root Tenant Policy Universe Infra Fabric Virtual Network VRF VRF Bridge Domain /24 Bridge Domain /24 Bridge Domain 1 Tenants VLANs Nodes Hypervisors Application s And everything else

14 Distinguished Name DN is used as a globally unique identifier for an object in the MIT Formed by getting relative name (RN) and appending it to parent RN until reaching toproot RN naming rule depends on object Can be found in APIC model documentation fvap fvaepg poluni fvtenant vzfilter vzentry Example: uni/tn-tenant/ap-app1/epg-epg1 vzbrcp vzsubj toproot fabricpathepcont fabricpathep Example: topology/pod-1/paths-101/pathep-[eth1/1] fabrictopology fabricpod fabricnode vmmprovp vmmdomp vmmctrlrp

15 Programmatic Interfaces Northbound API accepts configuration and provides access to management functions for controller Northbound API Native REST API Python SDK ( Cobra ) Southbound APIs extend declarative intent from fabric to subordinate devices Southbound API L4-7 Device Packages OpFlex Not in scope for this session Automation Tools REST APIC Provisioning Scripts Dev Pkg Firewall APIC OpFlex Switch

16 REST Interface GUI CLI Web Browser Object Browser (visore) API Tools Python SDK R E S T APIC Cluster + Leaves & Spines

17 Features and Functionality Native REST interface GUI can be used as reference / how to get things done guide Robust querying and filtering interface Configured and operational state provided through same interface Object model supports parameters useful for overloading application state Event driven notification via websockets

18 Getting Started

19 REST API: Basics Standard REST methods supported Method Action Behavior GET Read Nullipotent POST Create / Update Idempotent DELETE Delete Idempotent Payloads can be either XML or JSON Specified by the file extension in URI Content-Type and Accept header is ignored Stateless No state for requests or sessions HTTP1.1 / HTTPS (default) Handled by any APIC in cluster Access to switches via APIC Create, read, update & delete Managed Objects

20 REST API: Read Operations http(s):// host:port /api /{mo class} /{dn classname}.{xml json}?[options] http or https protocol APIC host and port API Operator Specify Managed Object or Class Operator Distinguished name or Object Class Encoding for response Specify filters, selectors or modifiers to query, joined using ampersand (&)

21 Lookup by DN Read properties for a specific EPG <imdata totalcount="1"> <fvaepg childaction="" configissues="" configst="applied" descr="" dn="uni/tn-cisco/ap-software/epg-download" lcown="local" matcht="atleastone" modts=" t22:19: :00" monpoldn="uni/tn-common/monepg-default" name="download" pctag="49189" prio="unspecified" scope=" " status="" triggerst="triggerable" uid="0"/> </imdata>

22 Lookup by Class Read properties every L1 Physical Interface <imdata totalcount="1134"> <l1physif adminst="up" autoneg="on" bw="0" childaction="" delay="1" descr="" dn="topology/pod-1/node-102/sys/phys-[eth1/32]" dot1qethertype="0x8100" ethpmcfgfailedbmp="" ethpmcfgfailedts="00:00:00:00.000" ethpmcfgstate="0" id="eth1/32" inhbw="unspecified" layer="layer2" lcown="local" linkdebounce="100" linklog="default" mdix="auto" medium="broadcast" modts=" t22:07: :00" mode="trunk" monpoldn="uni/infra/moninfra-default" mtu="9000" name="" portt="leaf" routermac="not-applicable" snmptrapst="enable" spanmode="not-aspan-dest" speed="10g" status="" switchingst="disabled" trunklog="default" usage="discovery"/> </imdata>

23 Get all the properties Read the object and complete subtree Response subtree query option is set to "full" to get everything under the object being queried <imdata totalcount="1"> <compvm cfgdos="ubuntu Linux (32-bit)" childaction="" descr="" dn="comp/prov-vmware/ctrlr-[vc-1]- vcenter_1/vm-vm-1001" guid="5024a300-1fde-aa80-72d4-7c33ef63a688" id="0" lcown="local" modts=" T17:04: :00" monpoldn="" name="32bit_ubuntu" oid="vm-1001" os="" state="poweredon" status="" type="virt"> <compvnic adaptertype="vmxnet3" addresstype="assigned" childaction="" descr="" guid="" id="0" ip=" " lcown="local" mac="00:50:56:a4:d0:d0" modts=" t17:04: :00" monpoldn="" name="network adapter 1" oid="4000" operst="up" rn="vnic-00:50:56:a4:d0:d0" status="" type="virt"/> <comprshv childaction="" forceresolve="no" lcown="local" modts=" t22:39: :00" rtype="mo" rn="rshv-[comp/prov-vmware/ctrlr-[vc-1]-vcenter_1/hv-host-12]" state="formed" statequal="none" status="" tcl="comphv" tdn="comp/prov-vmware/ctrlr-[vc-1]-vcenter_1/hv-host-12" ttype="mo"/> </compvm> </imdata> The target Dn references another object in this case, the hypervisor, so you can get more information by querying this Dn

24 REST API: Create/Update Operations http(s):// host:port /api /mo /dn.{xml json}?[options] <fvtenant name="newtenant"> <fvap name="newapplication"> <fvaepg name="webtier"> <fvrspathatt encap="vlan-1" mode="regular" tdn="topology/pod-1/paths-17/pathep-[eth1/1]"/> </fvaepg> </fvap> </fvtenant> Payload is XML/JSON representation of API Command Body

25 Object Browser: Visore APIC has built in object browser to navigate the object tree and inspect the state of objects Point the web browser to Visore: Search for a particular object or dn (fvtenant, topsystem, topology/pod- 1/node-101)

26 Sniffer: API Inspector API calls made by GUI are captured GET, POST Navigating through panes fetches data with GET requests Submitting configuration changes uses POST requests

27 Capturing API Calls POST url: { "fvtenant": { "attributes": { "name": "Cisco", "status": "created" }, "children": [] } }

28 Getting Started 1. Get the Cobra SDK 2. Get the documentation 3. Establish authenticated session 4. Simple queries 5. Inserting data into object store

29 SDK and Documentation Can be downloaded from APIC*: Available on DevNet Downloads -> Python Egg Files You will need to reference the Management Information Model. Bookmark it or Python SDK docs (and install directions) or APIC REST API User Guide s/datacenter/aci/apic/sw/1- x/api/rest/b_apic_restful_api_user_guide. html *

30 Establish authenticated session REST Login with username and password in payload POST /api/mo/aaalogin.xml <aaauser name='admin' pwd='insieme'/> Response headers include Cookie APIC-cookie Store this and use it for future requests Cobra import cobra.mit.access import cobra.mit.session ls = cobra.mit.session.loginsession( ' 'admin', 'insieme') md = cobra.mit.access.modirectory(ls) md.login() md now contains an authenticated APIC session

31 Simple Queries REST Query for all client endpoint objects GET /api/class/fvcep.xml <?xml?><imdata><fvcep dn="uni/tn- Cisco/ap-Blog/epg-MySQL/cep- 00:50:56:82:D2:FE" encap="vlan-501" id="0" ip=" " lcc="vmm" lcown="local" mac="00:50:56:82:d2:fe" mcastaddr="not-applicable" name="00:50:56:82:d2:fe uid="0"/></imdata> Parse XML results and process as needed Cobra Use the lookupbyclass method to find all endpoints (fvcep) endpoints = md.lookupbyclass('fvcep') print([str(ep.dn) for ep in endpoints]) ['uni/tn-cisco/ap-blog/epg-mysql/cep- 00:50:56:82:D2:FE', 'uni/tn-cisco/ap- Blog/epg-MySQL/cep-00:50:56:82:C3:D0'] Tip: To inspect http requests use debuglevel on httplib: import httplib httplib.httpconnection.debuglevel = 1

32 Query Filters in Cobra Built in helpers.lookupbyclass and.lookupbydn use.query under the covers For advanced queries, you can use.query directly In this example, we recursively print a full subtree for all endpoints def printtree(mos, indent=0): for mo in mos: print ' ' * indent, str(mo.meta.classname) printtree(mo.children, indent=indent+2) cq = cobra.mit.access.classquery('fvcep') cq.subtree = 'full' endpoints = md.query(cq) printtree(endpoints) >>> printtree(endpoints) cobra.model.fv.cep cobra.model.fv.rsnic cobra.model.fv.rsvm cobra.model.fv.rsceptopathep cobra.model.fv.rshyper cobra.model.fv.reportingnode

33 Query Filters Usually more efficient as less number of MOs need to be serialized and returned Filter the response returned using the supplied condition(s): Syntax: Returns only the MOs that satisfies the condition(s) Filter type Syntax Cobra Query Property Description query-target {self children subtree} AbstractQuery.queryTarget Define the scope of query target-subtree-class <class name> AbstractQuery.classFilter Respond only elements including specified class query-target-filter <filter expressions> AbstractQuery.propFilter Respond only elements matching conditions rsp-subtree {no children full} AbstractQuery.subtree specifies child object level included in the response rsp-subtree-class <class name> AbstractQuery.subtreeClassFilter Respond only specified classes rsp-subtree-filter <filter expressions> AbstractQuery.subtreePropFilter (>1.0.2m) Respond only classes matching conditions rsp-subtree-include {faults health :stats : } AbstractQuery.subtreeInclude Request additional objects order-by <classname.property> {asc desc} NotImplemented Sort the response based on the property values

34 Committing Configuration Changes REST Create a new tenant belonging to policy universe POST /api/mo/uni.xml <fvtenant name="cisco"/> Cobra Build your objects and commit them topmo = cobra.model.pol.uni('') fvtenant = cobra.model.fv.tenant(topmo, name='cisco') c = cobra.mit.request.configrequest() c.addmo(fvtenant) md.commit(c) Tip: To get the configured XML body for the object you've created/modified, add the rsp-include query parameter: POST /api/mo/uni.xml?rsp-subtree=modified Another Tip: Disable the annoying Requests Insecure Warning. Put this at the top of your script: import requests.packages.urllib3 requests.packages.urllib3.disable_warnings()

35 APIC REST to Python Adapter: arya.py GUI creates REST API Inspector shows REST arya.py creates code from REST Auto-generate code to automate tasks, without heavy lifting Available at XML/JSON arya.py Python code {"fvtenant":{"attributes":{"dn":"uni/tn- Cisco","name":"Cisco","rn":"tn- Cisco","status":"created"},"children":[{"fvBD":{"attribut es":{"dn":"uni/tn-cisco/bd- CiscoBd","mac":"00:22:BD:F8:19:FF","name":"CiscoBd","rn": "BD- CiscoBd","status":"created"},"children":[{"fvRsCtx":{"att ributes":{"tnfvctxname":"cisconetwork","status":"created, modified"},"children":[]}},{"fvsubnet":{"attributes":{"dn ":"uni/tn-cisco/bd-ciscobd/subnet- [ /8]","ip":" /8","rn":"subnet- [ /8]","status":"created"},"children":[]}}]}},{"fv Ctx":{"attributes":{"dn":"uni/tn-Cisco/ctx- CiscoNetwork","name":"CiscoNetwork","rn":"ctx- CiscoNetwork","status":"created"},"children":[]}}]}} fvtenant = cobra.model.fv.tenant(topmo, name='cisco') fvctx = cobra.model.fv.ctx(fvtenant, name='cisconetwork') fvbd = cobra.model.fv.bd(fvtenant, mac='00:22:bd:f8:19:ff', name='ciscobd') fvrsctx = cobra.model.fv.rsctx(fvbd, tnfvctxname=fvctx.name) fvsubnet = cobra.model.fv.subnet(fvbd, ip=' /8')

36 Using arya (1/2) Get input configuration 1. Right-click save XML 2. Monitor API inspector 3. Query APIC for config Easiest: Right-click save XML Select "only configuration" and "subtree"

37 Using arya (2/2) # arya.py -f accportprof-vm-vpc10.xml #!/usr/bin/env python ''' Autogenerated code using arya.py Original Object Document Input: <?xml version="1.0" encoding="utf-8"?><imdata totalcount="1"><infraaccportp descr="" dn="uni/infra/accportprof-vm-vpc10" name="vm-vpc10" ownerkey="" ownertag=""><infrahports descr="" name="vm-vpc10" ownerkey="" ownertag="" type="range"><infrarsaccbasegrp fexid="101" tdn="uni/infra/funcprof/accbundle-vm-vpc10"/><infraportblk descr="" fromcard="1" fromport="10" name="block1" tocard="1" toport="10"/></infrahports></infraaccportp></imdata> ''' raise RuntimeError('Please review the auto generated code before ' + 'executing the output. Some placeholders will ' + 'need to be changed') # list of packages that should be imported for this code to work import cobra.mit.access import cobra.mit.request import cobra.mit.session import cobra.model.infra import cobra.model.pol from cobra.internal.codec.xmlcodec import toxmlstr # log into an APIC and create a directory object ls = cobra.mit.session.loginsession(' 'admin', 'password') md = cobra.mit.access.modirectory(ls) md.login() Now, just substitute in APIC IP and credentials and remove this safety exception # the top level object on which operations will be made poluni = cobra.model.pol.uni('') infrainfra = cobra.model.infra.infra(poluni) # build the request using cobra syntax infraaccportp = cobra.model.infra.accportp(infrainfra, ownerkey='', name='vm-vpc10', descr='', ownertag='') infrahports = cobra.model.infra.hports(infraaccportp, ownerkey='', type='range', name='vm-vpc10', descr='', ownertag='') infrarsaccbasegrp = cobra.model.infra.rsaccbasegrp(infrahports, fexid='101', tdn='uni/infra/funcprof/accbundle-vm-vpc10') infraportblk = cobra.model.infra.portblk(infrahports, name='block1', descr='', fromport='10', fromcard='1', toport='10', tocard='1') # commit the generated code to APIC print toxmlstr(infrainfra) c = cobra.mit.request.configrequest() c.addmo(infrainfra) md.commit(c) Complete executable Cobra script to create the vpc profile

38 Sample: Get fabric OSPF neighbors Typical operations task is to check neighbors Want to have the same look and feel Take advantage of single fabric API to get details from entire fabric Solution: Query fabric for all OSPF neighbors, and output status in IOS/NX-OS fashion

39 Get fabric OSPF neighbors: Code def showospf(md): cq = cobra.mit.request.classquery('ospfadjep') cq.subtreeinclude = 'faults' return md.query(cq) Fetch Neighbors neis = showospf(md) fields = [('Neighbor ID ', 'id'), ('Pri', 'prio'), ('State ', 'operst'), ('Address ', 'peerip'), ('Node', 'dn')] for field in fields: print '{:<{width}}'.format(field[0], width=len(field[0])), for ne in neis: for f in fields: print '{:<{width}}'.format(getattr(ne, f[1]), width=len(f[0])), for fault in ne.children: print 'Fault Present: ', fault.descr Print

40 Get fabric OSPF neighbors: Results Proper IOS/NX-OS style results with fault details Neighbor ID Pri State Address Node exstart topology/pod-1/node-103 Fault Present: OSPF adjacency is not full, current state Exstart full topology/pod-1/node exstart topology/pod-1/node-102 Fault Present: OSPF adjacency is not full, current state Exstart initializing topology/pod-1/node-102 Fault Present: OSPF adjacency is not full, current state Initializing

41 Sample: Print all EPGs used on all Leafs Need to perform impact analysis Check which app tiers will be impacted by leaf downtime (code upgrade, etc) Quick way to find EPGs used on Leafs REST API provides "Trace" method to find this

42 Print all EPGs used on all Leafs: Code ls = cobra.mit.session.loginsession(apicuri, apicuser, apicpassword) md = cobra.mit.access.modirectory(ls) md.login() leaf_nodes = md.lookupbyclass('fabricnode', propfilter='eq(fabricnode.role, "leaf"') for leaf_node in leaf_nodes: epg_ref = md.query(cobra.mit.request.tracequery(leaf_node.dn, 'fvepp')) print leaf_node.dn for epg in epg_ref: print ' ', epg.epgpkey

43 Print all EPGs used on all Leafs topology/pod-1/node-103 uni/tn-ciscolive/ap-test/epg-test1 uni/tn-ciscolive/ap-test/epg-test2 uni/tn-ciscolive/ap-test/epg-test3 topology/pod-1/node-161 uni/tn-common/ap-firewall/epg-asa-ha topology/pod-1/node-164 uni/tn-common/ap-firewall/epg-asa-ha uni/tn-common/ap-loadbalancer/epg-f5 topology/pod-1/node-105 uni/tn-ciscolive/ap-test/epg-test1 uni/tn-ciscolive/ap-test/epg-test2 uni/tn-ciscolive/ap-test/epg-test3 topology/pod-1/node-163 uni/tn-common/ap-firewall/epg-asa-ha uni/tn-common/ap-loadbalancer/epg-f5

44 Best Practices

45 Best Practices 1. Utilize built in naming and Dn methods 2. Be granular/specific with your commits and queries 3. Avoid multiple lookups by starting off with static Dn s instead of resolving 4. Don t use from in imports to avoid namespace collisions 5. Use REST API filtering to reduce result set

46 1. Built in naming and Dn methods When making references between Managed Objects, do not manually build Dn strings fvrspathatt = cobra.model.fv.rspathatt(fvaepg, encap='vlan-2', tdn='topology/pod- 1/paths-101/pathep-[eth1/1]') Instead, lookup the object and use the.dn property fvrspathatt = cobra.model.fv.rspathatt(fvaepg, tdn=interface.dn)

47 2. Commit and Query Granularity The API uses a directory based architecture Closer to your target means less time and more accurate queries Following this practice also helps avoid context root issues APIC stores data in distributed data stores If you go up too high, no single APIC can own the data

48 2.1. Commit and Query Granularity Want to add a new end point group? Don't do this: topmo = cobra.model.pol.uni('') fvtenant = cobra.model.fv.tenant(topmo, name='cisco') fvap = cobra.model.fv.ap(fvtenant, 'NewApp') fvaepg = cobra.model.fv.aepg(fvap, 'NewEpg') c = cobra.mit.request.configrequest() c.addmo(topmo) md.commit(c) Do this: c.addmo(fvaepg) Tip: This technique will not work if the parent Mo does not exist. E.g., if the Tenant and App Profile do not exist, you cannot add an EPG

49 3. Avoid lookups when you can Issuing a remote query will always be slower than defining locally As shown in the last example, you can build static Mo's for many context roots Avoid two REST queries, by building your object locally Don't do this: topmo = md.lookupbyclass('poluni') lookupbyclass and lookupbydn both call.query() and incur a lookup penalty Do this: topmo = cobra.model.pol.uni('') Built in local memory and available for immediate usage

50 4. Don't import * and avoid 'from' in imports Basic Python practice Name space collisions are annoying The Object Model contains ~5k objects: there are object name collisions Avoid them by using namespaces Or use "from import as " Don't do this: from cobra.model.actrl import Inst from cobra.model.action import Inst a = Inst(...) # We clobbered actrl.inst Do this: import cobra.model.actrl import cobra.model.action a = cobra.model.actrl.inst(...) Or this: from cobra.model.actrl import Inst as ActrlInst

51 5. Server side filtering It's possible to perform multiple lookups, process results, and repeat for complex searches The powerful filtering on the REST API allows concise queries Get Mo for interface eth1/1 on node 101: cq = cobra.mit.request.classquery('fabricpathepcont') cq.propfilter = 'eq(fabricpathepcont.nodeid, "101")' cq.subtree = 'children' cq.subtreeclassfilter = 'fabricpathep' interface = [i for i in md.query(cq)[0].children if i.name == 'eth1/1'][0] print interface.dn Tip: Cobra >1.0.2m supports. subtreepropfilter attribute, allowing this loop to be avoided topology/pod-1/paths-101/pathep-[eth1/1]

52 Applicability

53 How others are using these Partners with application and business modeling Direct translation of business rules to application policy Customers with large / repeated deployments Repeated EPG-as-VLAN build outs Template based definitions for new tenant onboarding Within Cisco Fully automated QA / solution test process Advanced Services rapid testbed deployment Cisco IT heavily leveraging APIC automation

54 Conclusion

55 Conclusion APIC APIs are being used today Cisco APIC provides open API for complete platform access Powerful data manipulation and processing True object oriented interface Rapid development and prototyping

56 Participate in the My Favorite Speaker Contest Promote Your Favorite Speaker and You Could Be a Winner Promote your favorite speaker through Twitter and you could win $200 of Cisco Press products (@CiscoPress) Send a tweet and include Your favorite speaker s Twitter handle Two hashtags: #CLUS #MyFavoriteSpeaker You can submit an entry for more than one of your favorite speakers Don t forget to View the official rules at

57 Complete Your Online Session Evaluation Give us your feedback to be entered into a Daily Survey Drawing. A daily winner will receive a $750 Amazon gift card. Complete your session surveys though the Cisco Live mobile app or your computer on Cisco Live Connect. Don t forget: Cisco Live sessions will be available for viewing on-demand after the event at CiscoLive.com/Online

58 Continue Your Education Demos in the Cisco campus Walk-in Self-Paced Labs Table Topics Meet the Engineer 1:1 meetings Related sessions BRKACI Automating Operational Tasks in Cisco ACI BRKACI Dev-Ops and the Application Centric Infrastructure - Open Standards and Open API's

59 Thank you

60