0% found this document useful (0 votes)
48 views34 pages

DevNetDay2020 - DataCenter - Intro To ACI

The document provides an overview of the ACI object model and the REST API in ACI. It discusses the object-oriented nature of ACI where everything is represented as an object or managed information tree. It also covers exploring the object model through the Visore browser and constructing URIs and performing CRUD operations through the REST API.
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
48 views34 pages

DevNetDay2020 - DataCenter - Intro To ACI

The document provides an overview of the ACI object model and the REST API in ACI. It discusses the object-oriented nature of ACI where everything is represented as an object or managed information tree. It also covers exploring the object model through the Visore browser and constructing URIs and performing CRUD operations through the REST API.
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 34

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

You might also like