DEVNET-2000

ACI Programmability
Fundamentals
Start programming your APIC today!

John McDonough, Technical Leader, DevNet

Devarshi Shah,Technical Marketing Engineer, DCG
Agenda
• Exploring the ACI Object Model and REST API
• ACI Programmability with Python and ACI Toolkit
• ACI Meets NetDevOps in Ansible and Terraform!

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 3
The ACI Object Model
• Everything in ACI is an Object
• Object Class identifies its type
• Parent/Child relationships
between object
• 1 Parent to Many Children
• Assembled, create the MIT
• Everything builds from “root”
• Aka “uni”

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 4
Object Model & REST API = Foundation of
Programmability
• ACI designed as “API First”
• Everything built on top of the Python
Web ACI vSphere
REST API GUI
Cobra
Toolkit Plugin
SDK
• APIC GUI
• Cobra SDK
• PyACI REST API
• ACI Toolkit
• Plugins APIC Management
• ACI Kubernetes Integration
Information Model (MIM)

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 5
An Object by any other name…
Example:
• Objects have 2 names
• Relative Name (RN)
• Identify object related to “siblings”
• Unique within a parent object
• Distinguished Name (DN)
• Unique identification within MIT
• Series of Relative Names building to Mr. Smith Tom Smith Jill Smith
“uni/sys”
First names (relative) are used at
home.

But full names (distinguished)

are needed in larger contexts.
DEVNET-2000 © 2019 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—[Link]/24 uni/tn-Heroes/BD-Web/subnet—[Link]/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: [Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 10
Things to Know about the ACI REST API
• Leverages token in cookie or
certificate based authentication
• 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)
• REST API Guide available on
[Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 16
ACI REST API URI Construction
[Link] 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.

• Examples:
• query-target – Return Scope (self, children, subtree)
[Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 17
ACI REST API URI Construction Continued
[Link] TYPE>/<IDENTIFIER>.<FORMAT>[?<QUERY PARAMS>]
• [?<QUERY PARAMS>] - optional parameters that impact returned results.
• Examples:
• query-target-filter – Limit returned objects for Class Queries
[Link]
• rsp-subtree – Return Scope (no | children | full)
[Link]
• rsp-subtree-class – Limit returned objects for a Class Queries in the subtree
[Link]
• rsp-subtree – Request additional objects (fault-count | health | stats | relations | ..)
[Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 18
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

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 19
Setup Postman Environment for ACI APIC
• Add variables for host, and
credentials
• Reference anywhere with
{{variable name}} syntax

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 20
APIC Login Request
• APIC uses a ticket (token) for
authenticating API calls
• POST to /api/[Link]
with credentials to receive token
• Once logged in, Postman
automatically includes token in
further requests as session
cookie

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 21
Step 2: Query for All Tenants in Postman
• Query the Tenant Class
• GET
/api/node/class/[Link]

• .json indicates JSON is

preferred. .xml is also
supported
• Send and review response

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 22
Step 3: Create a New Tenant
• Target the root object of uni
• POST
/api/node/mo/[Link]

• .json indicates JSON is

preferred. .xml is also
supported
• Provide new object definition in
body
• Send and review response

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 23
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
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 27
ACI Toolkit
• Python Libraries for Working with
APIC Controller
• Designed to quickly enable users
to use REST APIs
• Available on GitHub
• [Link]
kit

• Docs
• [Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 28
Automating ACI with
Python and the ACI
Toolkit
ACI Programmability to Go - ACI Toolkit
Sample Scripts
Toolkit Library

Toolkit Applications

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 30
Get Started with the Toolkit Library
• Open a Python interpreter and
get started
• python –m [Link]
• Import ACI Toolkit

• Create a Session and Login to

the APIC
• Use the toolkit to create, query or
modify objects in ACI

netprog_basics/network_controllers/aci/device_info.py
netprog_basics/network_controllers/aci/toolkit_getting_started.py
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 31
ACI Toolkit Object Models
• ACI Toolkit provide a simple, user Context

friendly object model

BridgeDomain Subnet
• Python classes for developer to
work with
AppProfile EPG

• Three areas of objects Tenant

• Application Topology Object Model OutsideEPG

• Interface Object Model

• Physical Topology Model Contract ContractSubject

Filter

* Partial representation of the Application Topology Object Model

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 32
Working with ACI Toolkit Objects
• Query APIC for Objects with • View native ACI object definition
[Link]() method new_tenant.get_json()
tenants = [Link](session) • Push updates to APIC
• Create new object as instance of session.push_to_apic(
class new_tenant.get_url(),
data=new_tenant.get_json()
new_tenant = )
Tenant(“MyTenant”)
• Attach objects with methods
new_bd.add_context(new_vrf)

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 35
Sample Scripts $ cd samples/
$ ls *tenant*
[Link]
• “acitoolkit/samples” directory [Link]
[Link]
• Many examples to run or use as [Link]
starting points [Link]
[Link]
[Link]
[Link]
[Link]

$ ls *epg*
[Link]
[Link]
[Link]
[Link]
[Link]
[Link]
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 36
Toolkit Applications – ACI Diagram
$ ls acitoolkit/applications/
• ”acitoolkit/applications”
aci-diagram
directory configpush
eventfeeds
lint
reports
testharness
cableplan
connection_searchinheritance
multisite
search
visualizations
cli
endpointtracker
intraepg
[Link] object_browser
snapback
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 37
Toolkit Applications – ACI Diagram

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 38
Demo Time!

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 39
Cobra Python SDK and PyACI
• Comprehensive SDK and Python binding for building Python
applications with ACI
• Cobra Python packages
• acicobra: for interacting with APIC
• acimodel: a model of the MIT
• Cobra Download from APIC Controller
• [Link] address>/cobra/_downloads
• PyACI Download
• [Link]
• Docs
• [Link]
• [Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 40
ACI Meets NetDevOps
in Ansible and Terraform
Terraform is an Infrastructure Resources Manager

• Compose and combine infrastructure resources to build

and maintain a desired state
• Plan and execution are distinct actions
• Manages all resources through APIs
• Resources and data can be re-used within modules
• Terraform use core and plugins components for basic
functions and extensibility

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 42
How to install it?
• Go to [Link]/[Link]

• Pick you platform

• Unzip
• Move binary somewhere in your PATH
(e.g: /usr/local/bin)
• Run terraform commands

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 43
Terraform defines a high level syntax
• Resources are declared in TF file
• Syntax is HCL – HashiCorp Configuration Language
• Human understandable

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 44
Connecting to ACI
• You can use user/password or certificate base authentication
• Certificates based authentication is recommended though

path to user private key

Name of cert object in ACI

APIC address

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 47
Arguments are used to compose Resources
Type of resource Name of the resource
Project folder

[Link]

[Link]

[Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 48
Manage Relation Source Objects
• ACI leverages objects to build relations to other nodes in different part of the tree
• These objects are represented as arguments under the target Terraform resource
• Example with EPG that can have relation to VMM domain (fvRsDomAtt), Bridge-
Domain (fvBD) and Contract consumer/provider (vzBrCP)

“uni/vmmp-VMware/dom-VDS01”

“bd1”

“Web”

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 50
ACI Provider Resources
Available Resource Data Source
aci_tenant
aci_vrf
aci_bridge_domain
aci_subnet
aci_application_profile
aci_application_epg
aci_contract
aci_contract_subject
aci_filter
aci_filter_entry
aci_vmm_domain
aci_l3_outside
aci_external_network_instance_profile
aci_rest

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 51
Demo Time!

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 52
Now in Ansible! – ACI Modules
• Ansible includes many network
modules by default
• Includes Cisco as well as many
other vendors
• Over 65+ ACI Modules with MSO
modules added in 2.8
• ACI modules available with
Ansible 2.4 onwards

Subset of available modules shown

[Link]
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 53
Summing Up
Explore More and Get Hands On
• ACI Programmability Workshop • ACI Cloud APIC Workshop
• DEVWKS-2001 • DEVNET-2603
• ACI Terraform Workshop • REST API Documentation
• DEVWKS-1344 • [Link]
• ACI Programmability Learning Labs • ACI Toolkit Documentation
• [Link] • [Link]
• Always-On ACI Sandbox • Cobra SDK Documentation
• [Link] • [Link]
• ACI on DevNet • ACI Ansible Documentation
• [Link] • [Link]
• Code Samples • Terraform-ACI Provider and GO SDK
• [Link] • Terraform ACI Provider
• ACI Go Client
DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 66
 Cisco Webex Teams

Questions?
Use Cisco Webex Teams (formerly Cisco Spark)
to chat with the speaker after the session

How
1 Find this session in the Cisco Events Mobile App
2 Click “Join the Discussion”
3 Install Webex Teams or go directly to the team space
4 Enter messages/questions in the team space

[Link]/ciscolivebot#DEVNET-2000

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 68
Complete your online
session survey
• Please complete your Online Session
Survey after each session
• Complete 4 Session Surveys & the Overall
Conference Survey (available from
Thursday) to receive your Cisco Live T-
shirt
• All surveys can be completed via the Cisco
Events Mobile App or the Communication
Stations

Don’t forget: Cisco Live sessions will be available for viewing

on demand after the event at [Link]

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 69
Continue Your Education

Demos in Meet the Related

Walk-in
the Cisco engineer sessions
self-paced
Showcase labs 1:1
meetings

DEVNET-2000 © 2019 Cisco and/or its affiliates. All rights reserved. Cisco Public 70
Thank you