ACI Programmability

Information and Inspiration To Get Started

Quinn Snyder, Developer Advocate and Evangelist

@qsnyder
DEVNET-DC

#CiscoLive | #DevNetDay
Agenda
• What is the ACI Object Model?
• Overview
• Visore Viewer Exploration
• The ACI RESTful API
• URI Construction
• Authentication (Postman v. Python)
• Toolkits, SDKs, 3rd Party Tools
• More Information

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 2
What is the ACI Object
Model?
The ACI Object Model
The Foundation of Everything in ACI
• Everything in ACI is an object (MO)
• Object “class” identifies its type
• Parent/child relationships
exist between objects
• 1-1; 1-N depending on class
• When assembled, creates the
MIT/MIM
(Management Information
Tree/Model)
• Everything builds from “root”
• Seen as “uni” (policy universe)
#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 4
REST API All the Things

• ACI designed as “API first”;

nothing without API Web Cobra; ACI
3rd Party
GUI Arya Toolkit
• Everything built on top of the
REST API; most expose hierarchy
•

•
APIC GUI
Cobra SDK
REST API
• ACI Toolkit
• Plugins (CNI; vSphere) APIC Management
• 3rd Party Tools (Ansible, Terraform) Information Model (MIM)

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 5
Its All Relatively Distinguished
• Objects have 2 names
• Distinguished Name (DN)
• Unique identification within MIT
• Series of Relative Names building to
“uni” (root)
• Relative Name (RN)
• Identify object related to “siblings”
• Unique within a parent object, but
can be used in other classes

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 6
 Sample ACI Object Names
Object Example RN Example DN Class
System uni uni uni
Tenant tn-Heroes uni/tn-Heroes fvTenant
VRF/Context ctx-Development uni/tn-Heroes/ctx-Development fvCtx
Bridge Domain BD-Web uni/tn-Heroes/BD-Web fvBD
Subnet subnet—10.1.2.1/24 uni/tn-Heroes/BD-Web/subnet—10.1.2.1/24 fvSubnet
Application Profile ap-Save_The_Planet uni/tn-Heroes/ap-Save_The_Planet fvAp
EPG epg-Database uni/tn-Heroes/ap-Save_The_Planet/epg-Database fvAEPg
Client Endpoint cep-0000.1111.2222 uni/tn-Heroes/ap-Save_The_Planet/epg-Database/cep- fvCEp
0000.1111.2222

Filter flt-HTTP uni/tn-Heroes/flt-HTTP vzFilter

Contract brc-Web_Services uni/tn-Heroes/brc-Web_Services vzBrCP
Contract Subject subj-HTTP uni/tn-Heroes/brc-Web_Services/subj-HTTP vzSubj

Full ACI Model Reference: https://developer.cisco.com/site/aci/docs/apis/apic-mim-ref/

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 7
Visore: Object Model (and API) Browser
• Web page hosted on APIC
• http(s)://<apic-ip>/visore.html
• Recently updated; options have
moved
• Navigate the object model
• Search by class, DN
• Move up and down the MIT
• Expose ACI REST API calls

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 8
Visore: Searching by Class

• Useful for finding all instances of • Find all tenants

a specific type (autocomplete) (other than common)
• Example: All application profiles • Class: fvTenant
all EPGs, all client endpoints • Property: name != common
• Display URI to view ACI REST API call

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 9
Visore: URL Response
• URL for RESTful call no longer
displayed inline
• Reponse pop-up provides
selectable options
• Displays JSON’d (or XML’d)
output of response – handy to
compare

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 10
Visore: Searching by DN
• Useful for finding a specific object
and/or children
• Does not autocomplete like class query
• Example: app profile “Save_The_Planet”
• Display application profile
• DN: uni/tn-Heroes/ap-Save_The_Planet
• Display URI to view ACI REST API call

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 11
The ACI RESTful API
ACI REST API URI Construction
https://<ADDRESS>/api/<QUERY TYPE>/<IDENTIFIER>.<FORMAT>[?<QUERY PARAMS>]

• api - The main entry point for ACI API REST requests.
• QUERY TYPE
• node/class – Query and return all instances of a given class
• node/mo – Target a specific instance of an object from the MIT
• IDENTIFIER - Class Name or Distinguished Name
• FORMAT – Identify XML or JSON as type of content
• Used instead of HTTP Headers
• [?<QUERY PARAMS>] - optional parameters that impact returned results; scoping filters
• Example: query-target – Return Scope (self, children, subtree)

https://10.10.10.1/api/class/pcAggrIf.json?query-target=subtree

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 13
 ACI REST API URI Scoping Filters
Filter Type Syntax Description

query-target {self | children | subtree} This filter defines the scope of the query.

target-subtree-class <class name> This filter returns only elements that include the
specified class.
query-target-filter <filter expressions> This filter returns only elements that match conditions.

rsp-subtree {no | children | full} This filter specifies the child object level included in the
response.
rsp-subtree-class <class name> This filter returns only specified classes.

rsp-subtree-filter <filter expressions> This filter returns only classes that matching conditions.

rsp-subtree-include {faults | health :stats: …} This filter returns additional objects.

order-by <classname.property>| {asc| This filter sorts the response based on the property
desc} values.

#CiscoLive | #DevNetDay © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public
ACI REST API CRUD Operations
HTTP Method Details
GET Return an object by DN or all instances of a class
POST Create a new instance of an object or Update details
about an existing object.
DELETE Delete an object

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 15
ACI API with Postman
Postman: Manage Environments for Credentials
• Add variables for host, and
credentials
• Reference anywhere with
{{variable name}} syntax

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 17
Postman: APIC Login Request
• APIC uses a ticket (token) for
authenticating API calls
• POST to /api/aaaLogin.json
with credentials to receive token
• Once logged in, Postman
automatically includes token in
further requests as a session
cookie

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 18
Postman: Not the Cookie Monster
• Postman automatically saves the token as ‘APIC-Cookie’
• This cookie will be appended to the header in subsequent requests

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 19
ACI API with Python
Python: `requests` Makes It Easy
• requests allows you to focus import requests

on outcome, not language import json

requests.packages.urllib3.disable_warnings()
• Have to handle cookie tracking encoded_body = json.dumps({"aaaUser": {"attributes":
and refresh if needed {"name":"admin","pwd": "ciscopsdt”}}})

resp =
• Use of “cookie jar” to append requests.post("https://sandboxapicdc.cisco.com/api/aaaLogin.
json", data=encoded_body, verify=False)
login token to header for header = {"Cookie": "APIC-cookie=" + resp.cookies["APIC-
subsequent request cookie"]}

tenants =
requests.get("https://sandboxapicdc.cisco.com/api/node/class
/fvTenant.json", headers=header, verify=False)

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 21
Python: `requests` Makes It Easy
• Breaking it all down: import requests
import json

JSON-encoded body of the requests.packages.urllib3.disable_warnings()

username and password encoded_body = json.dumps({"aaaUser": {"attributes":

{"name":"admin","pwd": "ciscopsdt”}}})

resp =
HTTP POST of body to APIC requests.post("https://sandboxapicdc.cisco.com/api/aaaLogin.
json", data=encoded_body, verify=False)

aaaLogin.json URI header = {"Cookie": "APIC-cookie=" + resp.cookies["APIC-

cookie"]}

Storing returned token as tenants =

requests.get("https://sandboxapicdc.cisco.com/api/node/class
APIC-Cookie header /fvTenant.json", headers=header, verify=False)

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 22
ACI REST API Takeaways
• Leverages token in cookie or certificate
based authentication – need to account
for this
• Uses .json and .xml within URI instead
of Content-Type and Accept headers to
indicate data format
• API will target specific class type or
managed object (mo) via DN
• Scoping filters help target the information
you want
• REST API Guide available on Cisco.com
#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 23
SDKs, Toolkits, and 3rd
Party Tools
ACI Network Programmability Scripting Options

Direct API
Software
Pros: “Toolkits”
Development Kit
Limitless options Pros:
Pros:
Any Encapsulate common use cases
language/method Language Wrapper of
API Less code
Cons:
Simplifies Syntax and Cons:
Raw API syntax Management Not 100% Coverage
Session Management Cons: Availability
Individual Atomic Availability
Actions
Atomic API Interactions
#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 25
ACI Toolkit
• Python Libraries for Working with
APIC Controller
• Designed to quickly enable users
to use REST APIs
• Available on GitHub
• https://github.com/datacenter/acitoolkit

• Docs
• http://acitoolkit.readthedocs.io

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 26
ACI Toolkit: Object Models
• ACI Toolkit provides a simple, Context

user friendly object model

BridgeDomain Subnet

• Python classes for developer to

work with AppProfile EPG

• Three areas of objects Tenant

OutsideEPG
• Application Topology Object
Model
Contract ContractSubject
• Interface Object Model

• Physical Topology Model Filter

* Partial representation of the Application Topology Object Model

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 27
ACI Toolkit: Batteries Included Programmability
Sample Scripts
Toolkit Library

Toolkit Applications

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 28
Cobra Python SDK and PyACI
• Full SDK and Pythonic bindings for building ACI apps
• Cobra Python packages
• acicobra: for interacting with APIC
• acimodel: a model of the MIT
• Cobra download from APIC controller
• https://<apic address>/cobra/_downloads
• Version available on DevNet to complete labs against
sandbox
• PyACI Download
• https://github.com/datacenter/pyaci
• Docs
• https://pyaci.readthedocs.io/en/latest/
• https://cobra.readthedocs.io

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 29
Cobra: Code Made Easier with ARYA
• Cobra provides full MIT access; can be intimidating

• Export valid object from APIC, run ARYA against export, profit!

Export Manipulate
JSON/XML arya.py –f result to form
MO from file.json desired
APIC outcome

• Cobra applies all created/modified configuration objects in single atomic commit

• Source code at https://github.com/datacenter/arya

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 30
Cobra: Webarya – Flask + ARYA
• Flask web front-end for ARYA

• Clone repo, install requirements, run

locally
• Paste exported JSON/XML, receive
Cobra code
• Source code at
https://github.com/datacenter/webarya

#CiscoLive | #DevNetDay DEVNET-DC © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 31
Explore More
• REST API Documentation
• http://cs.co/ACI_API
• ACI Toolkit Documentation
• https://acitoolkit.readthedocs.io
• Cobra SDK Documentation
• https://cobra.readthedocs.io
• ACI Programmability Learning Labs
• http://cs.co/DevNet_ACI
• Always-On ACI Sandbox
• http://cs.co/ACI_SBX
• ACI on DevNet
• https://developer.cisco.com/aci

#CiscoLive | #DevNetDay © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public
Thank you

#CiscoLive | #DevNetDay
#CiscoLive | #DevNetDay