Server Infrastructure Required

This lab can be completed if you have access to the server infrastructure in a private lab or if you are at an event such as Cisco Live!

ACI 106: Arya

Learning Objectives

After completing this module you will be able to:

  • Install the Ayra Development Tool
  • Create a simple Python program/script using Arya

Arya Introduction

Arya is a very useful tool for learning how to develop new configurations with the Cobra SDK. Using Arya, you can export existing configurations from the APIC controller and convert them into example code projects. Arya has several benefits including:

  • Demonstrating the API configuration corresponding to the JSON, GUI or CLI commands
  • Allowing for faster learning of the Cobra SDK
  • Converting existing configurations into automated scipts to quickly provision new components in ACI

In ACI 103, we used Postman to build a tenant with an underlying VRF and bridge domain, as well as an Application Profile in. However, we have yet to complete a similar Application Profile using the Cobra SDK. In this module we'll start by installing Arya and getting familiar with the basics. We'll finish off by looking at how we can use Arya to quickly take the configuration we completed in ACI 103 and create a corresponding Python (.py) script.

Installation

If you are using a lab computer, you may already have Arya installed. You can confirm this by issuing the following command and checking for 'Arya' in the output list:

pip list

If you do need to install Ayra, it is part of the PyPi registry so you can simply issue:

pip install arya

Further information/installation instructions are also available at https://github.com/datacenter/arya

First Arya Conversion

In order to use Arya we'll need to first export a configuration from the APIC. We'll use the configuration from the 'ExampleSDKTenant' we built in Module 5. To download this configuration, do the following:

  1. Open an internet browser and navigate to:
    https://<IP-of-APIC>
    
  2. Login into the APIC and click on the tenants tab.
  3. Click on the 'ExampleSDKTenant' in the list.
  4. Right-click on the tenant name in the top left explorer window and click 'save-as' Figure

  5. Select 'Configuration Only' for the content, 'Subtree' for the Scope and 'JSON' for the format. Figure

  6. Select 'Download' to save to the file to your local machine.

Now to use Arya, we'll need three pieces of information:

  1. The location of arya.py: Arya is actually a python program in itself. You will likely see the file in the python interpreter's directory. [On a Windows lab computer, you will likely see it in C:\Python27]
  2. The name and location of the configuration file we just downloaded: The file will likely be downloaded as tn-ExampleSdkTenant.json. Feel free to open this file in a text editor, you will see a JSON configuration identical to some of the outputs we saw in ACI 102 when we used Postman to retrieve the JSON configuration of our tenant.
  3. The name and location of our new Python Script: This file doesn't exist yet but we'll use arya to create it. We'll call ours 'ExampleAryaTenant.py and choose a convenient directory.

To use Arya, issue the following command on your local machine (Be sure to update the file directory path for your local computer):

python <Path>\arya.py -f <path>\tn-ExampleSdkTenant.json > <path>\ExampleAryaTenant.py

Understanding the Arya Output File

You should now be able to open the newly created ExampleAryaTenant.py file in a text editor. However, before we use this script we'll need to investigate the output a little further.

Input Configuration

In the first few lines of the file we see the following code comments

'''
Autogenerated code using arya.py
Original Object Document Input:
............
'''

Note that this is actually the JSON config from the file we downloaded.

Auto-Raised Runtime Error

The next block of code is an expection which prevents the script from running. We can try to execute it as we've done before:

python <path>\ExampleAryaTenant.py

However, the program fails and we receive the following error:

Please review the auto generated code before executing the output. Some placeholders will need to be changed

This is an error purposefully added in the code to remind us that Arya will do its best to build a complete configuration but there will likely be some values that we will need to manually change before its ready to use. We see this error in the code:

raise RuntimeError('Please review the auto generated code before ' +
                    'executing the output. Some placeholders will ' +
                    'need to be changed')

This section of code must be deleted or commented out to proceed.

APIC Creditials

To connect this script with our APIC cluster, we'll need to update the IP address, username and password in the following section of code:

# log into an APIC and create a directory object
ls = cobra.mit.session.LoginSession('https://1.1.1.1', 'admin', 'password')
md = cobra.mit.access.MoDirectory(ls)
md.login()

APIC Configuration

The body of this configuration should look familiar. It is the configuration we created in ACI 104. However, you will notice that all the Managed Objects we created have a number of extra parameters we did not configure. For example, when we created a Bridge Domain we simply gave it a name but in this file there are quite a few parameters defined:

fvBD = cobra.model.fv.BD(fvTenant, ownerKey=u'', vmac=u'not-applicable', name=u'myBD', descr=u'', unkMacUcastAct=u'proxy', arpFlood=u'no', limitIpLearnToSubnets=u'no', llAddr=u'::', mac=u'00:22:BD:F8:19:FF', epMoveDetectMode=u'', unicastRoute=u'yes', ownerTag=u'', multiDstPktAct=u'bd-flood', unkMcastAct=u'flood')

You will also notice several MO's in the configuration which we did not create at all, including the Tenant Monitoring Policy MO, shown here:

fvRsTenantMonPol = cobra.model.fv.RsTenantMonPol(fvTenant, tnMonEPGPolName=u'')

These additions are due to the forgiving model within ACI. They represent the default values and MO's needed based on the objects we configured. For example, we did not specify an ARP Flooding policy within our bridge domain so the default value was applied the fvBD object:

arpFlood=u'no'

Similarily, every tenant must have a Managed Object to contain a policy for monitoring the network traffic. We didn't specify any monitoring policy for our tenant so the object was created and the policy was just left bank:

tnMonEPGPolName=u''

Lastly, you may notice that all of the parameters in this script include a 'u' before their definition, as is the case in the tenant name:

name=u'ExampleSdkTenant'

The 'u' simply indicates the following is a unicode type string. For our purposes we will not explore the specifics of unicode vs str text. The 'u' may be included or omitted.