my cheat sheet ACI API

Physical network of spine/leaf switches in ACI mode ( not NXOS mode) Cluster of controllers (APIC controllers). The controllers operate the datacenter as a SDN, where applicaitons dynamically request resources from the network. ACI is a centralized application-level policy engine for physical, virtual, and cloud infrastructures.

• a cluster of servers, typically five, minimum three.
• centralized controller for the SDN
• Web HTML5 GUI
• RESTful API
• XML or JSON for northbound APIs
• 65 partner 3rd party integrations
• ACI APP Center extends functionality

The Object Model is the foundation for EVERYTHING in ACI

Tree structure of related objects, with every object having 1 parent, but a parent having 1 or many children. Scope is important as you could have a relative name "web-egp" in both production tenant as well as dev tenant. You can always use the full DN which shows you a name that includes all levels, from top to bottom. uni/tn-Prod/ap-Healing/epg-Web

Here are some Prefix Properties and their common name

tn - tenant
ctsx - Context/vrf
BD - bridge domain
subnet - subnet
ap - App profile
epg - EPG
cep - Client endpoint
ip - ip address
out - L3 external
flt - filter
brc - contract
subj - contract subject

When working with ACI API, you will almost always be using the full DN

Unlike other SDN solutions, ACI APIs open up EVERYTHING to API access, due to the ACI Object Model approach to EVERTHING.

The ACI REST API:

• accepts and returns HTTP or HTTPS messages
• encoded in JSON or XML
• any programming language can be used to generate the messages and JSON or XML documents, as long as they contain the API methods or managed object descriptions
• also provides a PUSH-based event notification. On changes in the MIT, an event is sent through a web socket

Cisco also provides these open source tools or frameworks:

• ACI Toolkit
• ACI SDK (Cobra)
• ACIrb (Ruby)
• Puppet
• Ansible

ACI supports three API approaches.

Actually there are more than 3: ARYA, Cobra, Visore, Moquery to name 4 more.

ACI REST APIdeals with raw API syntax, but can use any language / method you want. This can get complex. API will target specific class type or mo (managed object)

Rather than using the usual headers, type and accept, you simply call one of these two URI endings when writting the URI

• .json
• .xml

As the URL trailing type.. For example:

• https://{{apic}}/api/aaLogin.json
• https://{{apic}}/api/aaLogin.xml

That is also how you login to the ACI REST API. The returned page is a token which is automatically included in subsequent request as a cookie

{ 
   "totalCount" : 1
   "imdata": [
      {
	 "aaaLogin": {
	    "attributes": {
	       "token": "p3148fhap8eghjo2ihgpoaeirgypo
	       /ihtpq98wyegloiqhtgekjdhgpoqiunrq
	       "siteFingerprint": "lkjo3ignoqiw",
	       "refreshTimeoutSeconds": 600
      ...

• python library
• simple, easy, subset of full functionality
• encapsulate common use cases. So you need less code. You just reuse the

code someone else has written. Of course you are at the whim of whether your use case has been written by someone else. See acitoolkit.readthedocs.io

ACI Toolkit

"aka language bindings"

• Python library that implements a REST API
• Native bindings for all REST functions
• 1:1 representation of objects in cobra : MIT
• provides methods for lookups, and object CRUD
• full functionality up to lyaer 7, initial fabric builds etc.
• user:password-based authentication AND
• cerificate-based authentication/

COBRA is a language wrapper around the API. This simplifies your code syntax. Cobra is extensive and can get complicated. It comes with every release of the APIC, and is always available from the APIC directly (and obviously the correct version to go with the ACI s/w the APIC is running)

Best to look at a python script using the cobra library. This one is from the learning-labs-code-samples directory.

Key parts are:

arya is a tool that will convert APIC object documents from their XML or JSON form into equivalent Python code leveraging the Cobra SDK

• The GUI creates REST
• API Inspector shows REST
• arya.py creates code from REST
• Auto-generate code to automate task, without heavy lifting
• download from http://github.com/datacenter/arya

arya can take input from multiple source, including standard input. So, one can copy the JSON or XML extracted from:

• APIC Visore or
• API inspector, and

quickly generate the Python source code framework, which can then be modified, tokenized and rapidly turned into functional prototypes.

There are a LOT of libraries on https://github.com/datacenter

• Ruby implementation of the Cisco APIC REST API
• Enables direct manipulation of the MIT through the REST API, using standard Ruby language options

Moquery is a CLI object model query tool, while Visore is an object store browser (GUI)

From the readthedocs.io tutorial: The configuration object definition is done in this order:

1. tenant All of the configuration will be created within a single tenant named tutorial. This is done by creating an instance of the Tenant class and passing it a string containing the tenant name.

   tenant = Tenant('tutorial')

2. application profile The Application Profile contains all of the Endpoint Groups representing the application. The next line of code creates the application profile. It does this by creating an instance of the AppProfile class and passing it a string containing the Application Profile name and the Tenant object that this AppProfile will belong.

   app = AppProfile('myapp', tenant)

   Note that the parent class of AppProfile is Tenant. This is typical. The parent object must be an instance of this class’s parent class according to the acitoolkit object model.

3. Endpoint Group The Endpoint Group provides the policy based configuration for Endpoints that are members of the Endpoint Group. This is represented by the EPG class. In this case, we create an EPG with the name myepg and pass the AppProfile that we created to be the parent object.

   epg = EPG('myepg', app)

It seems that we can learn more about the ACI Toolkit by running it interactively as follows:

1. git clone https://github.com/datacenter/Simple-ACI-Toolkit

   This command will download the necessary libraries to use the ACI Toolkit syntax. Then to run CLI commands from your APIC type:

2. python acitoolkitcli.py -l admin -p password -u https://APIC_IP

   This will connect you to your APIC so you may run commands that will help you build your application network profiles. We can do things such as switching tenants, creating contexts, creating bridge domains, and creating end point groups (EPGs).

   Here are some examples of the common commands we might use to create these logical objects.

3. Switch to a tenant configuration mode:

   fabric# switchto tenant <tenant-name>
   fabric-tenant# switchback
   

1. Create a Context and don’t enforce contracts on it:

   fabric-tenant(config)# [no] context <context-name>
   fabric-tenant(config-ctx)# [no] allow-all
   

1. Create a bridge domain and assign it to a context:

   fabric-tenant(config)# [no] bridgedomain <bd-name>
   fabric-tenant(config-bd)# [no] context <context-name>
   

1. Create a subnet under the bridge domain:

   fabric-tenant(config-bd)# [no] ip address <ip-address>/<masklength> [name <subnet-name>]
   

If you go to the always-on sandbox, you will see a set of instructions for the lab, that I am duplicating here:

The server can be connected using login credentials: admin : ciscopsdt at this URL: https://sandboxapicdc.cisco.com

• git clone https://github.com/CiscoDevNet/aci-learning-labs-code-samples
• cd aci-learning-labs-code-samples
• python3.7 -m venv aci-learning-labs
• source aci-learning-labs/bin/activate
• pip install -r requirements.txt

Ansible includes many network modules by default • Includes Cisco as well as many other vendors • Initial support for ACI released with Ansible 2.4 • Additional modules planned for future release • Stay Tuned! More modules in Ansible 2.5

Sample playbook

    --- 
tasks:
  - name : Create Tenant
    aci_tenant:
      host: 192.168.1.1
         username: admin
         password: cisco123
         use_ssl: True
         validate_certs: False
         state: present
         tenant: New)tenant
         descriptions: Ne wennant.

 Managing tenants with Ansible
 aci_tenant

        tenant:   

More from Cisco Live DEVNET-200:

---

- name: Example 1 - Managing Tenants
  hosts: apic
  connection: local
  gather_facts: False
  vars:
    tenants:
    - Tenant1 - Tenant2
  tasks:
    - name: Create Tenants
      aci_tenant:
        host: "{{ ansible_host }}"
        username: "{{ username }}"
        password: "{{ password }}"
        state: "present"
        validate_certs: False
        tenant: "{{ item }}"
        description: "Tenant Created Using Ansible"
      with_items: "{{ tenants }}"