Developing Automation

About the REST APIs

Automation relies on the Application Policy Infrastructure Controller (APIC) northbound Representational State Transfer (REST) APIs. Anything that can be done through the Cisco APIC GUI can also be done using XML-based REST POSTs using the northbound APIs. For example, you can monitor events through those APIs, dynamically enable EPGs, and add policies.

You can also use the northbound REST APIs to monitor for notifications that a device has been brought onboard, and to monitor faults. In both cases, you can monitor events that trigger specific actions. For example, if you see faults that occur on a specific application tier and determine that there is a loss of connectivity and a leaf node is going down, you can trigger an action to redeploy those applications somewhere else. If you have certain contracts on which you detect packet drops occurring, you could enable some copies of those contracts on the particular application. You can also use a statistics monitoring policy, where you monitor certain counters because of issues that have been reported.

For information on how to construct the XML files submitted to the Cisco APIC northbound API, see Cisco APIC Layer 4 to Layer 7 Device Package Development Guide.

The following Python APIs, defined in the Cisco APIC Management Information Model Reference can be used to submit REST POST calls using the northbound API:

  • vns:LDevVip: Upload a device cluster

  • vns:CDev: Upload a device

  • vns:LIf: Create logical interfaces

  • vns:AbsGraph: Create a graph

  • vz:BrCP: Attach a graph to a contract


Note

For endpoint security groups (ESGs), you can use the same service graph deployment REST APIs that are available for endpoint groups. However, you must associate the contract to the ESGs.

Examples of Automating Using the REST APIs

This section contains examples of using the REST APIs to automate tasks.

The following REST request creates a tenant with a broadcast domain, a Layer 3 network, application endpoint groups, and an application profile: 

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">

        <!—L3 Network-->
        <fvCtx name="MyNetwork"/>

        <!-- Bridge Domain for MySrvr EPG -->
        <fvBD name="MySrvrBD">
            <fvRsCtx tnFvCtxName="MyNetwork"/>
            <fvSubnet ip="10.10.10.10/24">
            </fvSubnet>
        </fvBD>

        <!-- Bridge Domain for MyClnt EPG -->
        <fvBD name="MyClntBD">
            <fvRsCtx tnFvCtxName="MyNetwork"/>
            <fvSubnet ip="20.20.20.20/24">
            </fvSubnet>
        </fvBD>

        <fvAp dn="uni/tn-acme/ap-MyAP" name="MyAP">

            <fvAEPg dn="uni/tn-acme/ap-MyAP/epg-MyClnt" name="MyClnt">
                <fvRsBd tnFvBDName="MySrvrBD"/>
                <fvRsDomAtt tDn="uni/vmmp-Vendor1/dom-MyVMs"/>
                <fvRsProv tnVzBrCPName="webCtrct"> </fvRsProv>
                <fvRsPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/21]"
                  encap="vlan-202"/>
                <fvRsPathAtt tDn="topology/pod-1/paths-18/pathep-[eth1/21]"
                  encap="vlan-202"/>
           </fvAEPg>

            <fvAEPg dn="uni/tn-acme/ap-MyAP/epg-MySRVR" name="MySRVR">
                <fvRsBd tnFvBDName="MyClntBD"/>
                <fvRsDomAtt tDn="uni/vmmp-Vendor1/dom-MyVMs"/>
                <fvRsCons tnVzBrCPName="webCtrct"> </fvRsCons>
                <fvRsPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/21]"
                  encap="vlan-203"/>
                <fvRsPathAtt tDn="topology/pod-1/paths-18/pathep-[eth1/21]"
                  encap="vlan-203"/>
            </fvAEPg>
        </fvAp>
    </fvTenant>
</polUni>

The following REST request creates a VLAN namespace:

<polUni>
    <infraInfra>
        <fvnsVlanInstP name="MyNS" allocMode="dynamic">
            <fvnsEncapBlk name="encap" from="vlan-201" to="vlan-300"/>
        </fvnsVlanInstP>
    </infraInfra>
</polUni>

The following REST request creates a VMM domain:

<polUni>
    <vmmProvP vendor="Vendor1">
        <vmmDomP name="MyVMs">
            <infraRsVlanNs tDn="uni/infra/vlanns-MyNS-dynamic"/>
            <vmmUsrAccP name="admin" usr="administrator" pwd="in$1eme"/>
            <vmmCtrlrP name="vcenter1" hostOrIp="192.168.64.186">
                <vmmRsAcc tDn="uni/vmmp-Vendor1/dom-MyVMs/usracc-admin"/>
            </vmmCtrlrP>
        </vmmDomP>
    </vmmProvP>
</polUni>

The following REST request creates a physical domain:

<polUni>
    <physDomP name="phys">
        <infraRsVlanNs tDn="uni/infra/vlanns-MyNS-dynamic"/>
    </physDomP>
</polUni>

The following REST request creates a managed device cluster: 

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">
        <vnsLDevVip name="ADCCluster1" contextAware=1>
            <vnsRsMDevAtt tDn="uni/infra/mDev-Acme-ADC-1.0"/>
            <vnsRsDevEpg tDn="uni/tn-acme/ap-services/epg-ifc"/>
            <vnsRsALDevToPhysDomP tDn="uni/phys-phys"/>
            <vnsCMgmt name="devMgmt" host="42.42.42.100" port="80"/>
            <vnsCCred name="username"value="admin"/>
            <vnsCCredSecret name="password" value="admin"/>
        </vnsLDevVip>
    </fvTenant>
</polUni>

The following REST request creates an unmanaged device cluster:

<polUni>
    <fvTenant name="HA_Tenant1">
        <vnsLDevVip name="ADCCluster1" devtype="VIRTUAL" managed="no">
            <vnsRsALDevToDomP tDn="uni/vmmp-VMware/dom-mininet"/>
        </vnsLDevVip>
    </fvTenant>
</polUni>

The following REST request creates a device cluster context:

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">
        <vnsLDevCtx ctrctNameOrLbl="webCtrct" graphNameOrLbl="G1" nodeNameOrLbl="Node1">
            <vnsRsLDevCtxToLDev tDn="uni/tn-acme/lDevVip-ADCCluster1"/>
            <vnsLIfCtx connNameOrLbl="provider">
                <vnsRsLIfCtxToLIf tDn="uni/tn-acme/lDevVip-ADCCluster1/lIf-int"/>
            </vnsLIfCtx>
            <vnsLIfCtx connNameOrLbl="consumer">
                <vnsRsLIfCtxToLIf tDn="uni/tn-acme/lDevVip-ADCCluster1/lIf-ext"/>
            </vnsLIfCtx>
        </vnsLDevCtx>
    </fvTenant>
</polUni>

The following REST request creates a device cluster context used in route peering:

<polUni>
    <fvTenant dn="uni/tn-coke{{tenantId}}" name="coke{{tenantId}}">
        <vnsRtrCfg name="Dev1Ctx1" rtrId="180.0.0.12"/>
            <vnsLDevCtx ctrctNameOrLbl="webCtrct1" graphNameOrLbl="WebGraph"
              nodeNameOrLbl="FW">
                <vnsRsLDevCtxToLDev tDn="uni/tn-tenant1/lDevVip-Firewall"/>
                <vnsRsLDevCtxToRtrCfg tnVnsRtrCfgName="FwRtrCfg"/>
                <vnsLIfCtx connNameOrLbl="internal">
                    <vnsRsLIfCtxToInstP tDn="uni/tn-tenant1/out-OspfInternal/instP-IntInstP"
                      status="created,modified"/>
                    <vnsRsLIfCtxToLIf tDn="uni/tn-tenant1/lDevVip-Firewall/lIf-internal"/>
                </vnsLIfCtx>
                <vnsLIfCtx connNameOrLbl="external">
                    <vnsRsLIfCtxToInstP tDn="uni/tn-common/out-OspfExternal/instP-ExtInstP"
                      status="created,modified"/>
                    <vnsRsLIfCtxToLIf tDn="uni/tn-tenant1/lDevVip-Firewall/lIf-external"/>
            </vnsLIfCtx>
        </vnsLDevCtx>
    </fvTenant>
</polUni>

Note

For information about configuring external connectivity for tenants (a Layer 3 outside), see the Cisco APIC Basic Configuration Guide.

The following REST request adds a logical interface in a device cluster:

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">
        <vnsLDevVip name="ADCCluster1">
            <vnsLIf name="C5">
                <vnsRsMetaIf tDn="uni/infra/mDev-Acme-ADC-1.0/mIfLbl-outside"/>
                <vnsRsCIfAtt tDn="uni/tn-acme/lDevVip-ADCCluster1/cDev-ADC1/cIf-int"/>
            </vnsLIf>
            <vnsLIf name="C4">
                <vnsRsMetaIf tDn="uni/infra/mDev-Acme-ADC-1.0/mIfLbl-inside"/>
                <vnsRsCIfAtt tDn="uni/tn-acme/lDevVip-ADCCluster1/cDev-ADC1/cIf-ext"/>
            </vnsLIf>
        </vnsLDevVip>
    </fvTenant>
</polUni>

The following REST request adds a concrete device in a physical device cluster:

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">
        <vnsLDevVip name="ADCCluster1">
            <vnsCDev name="ADC1" devCtxLbl="C1">
                <vnsCIf name="int">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/22]"/>
                </vnsCIf>
                <vnsCIf name="ext">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/21]"/>
                </vnsCIf>
                <vnsCIf name="mgmt">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/20]"/>
                </vnsCIf>
                <vnsCMgmt name="devMgmt" host="172.30.30.100" port="80"/>
                <vnsCCred name="username" value="admin"/>
                <vnsCCredSecret name="password" value="admin"/>
            </vnsCDev>
            <vnsCDev name="ADC2" devCtxLbl="C2">
                <vnsCIf name="int">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/23]"/>
                </vnsCIf>
                <vnsCIf name="ext">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/24]"/>
                </vnsCIf>
                <vnsCIf name="mgmt">
                    <vnsRsCIfPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/30]"/>
                </vnsCIf>
                <vnsCMgmt name="devMgmt" host="172.30.30.200" port="80"/>
                <vnsCCred name="username" value="admin"/>
                <vnsCCredSecret name="password" value="admin"/>
            </vnsCDev>
        </vnsLDevVip>
    </fvTenant>
</polUni>

The following REST request adds a concrete device in a virtual device cluster:

<polUni>
    <fvTenant dn="uni/tn-coke5" name="coke5">
        <vnsLDevVip name="Firewall5" devtype="VIRTUAL">
            <vnsCDev name="ASA5" vcenterName="vcenter1" vmName="ifav16-ASAv-scale-05">
                <vnsCIf name="Gig0/0" vnicName="Network adapter 2"/>
                <vnsCIf name="Gig0/1" vnicName="Network adapter 3"/>
                <vnsCIf name="Gig0/2" vnicName="Network adapter 4"/>
                <vnsCIf name="Gig0/3" vnicName="Network adapter 5"/>
                <vnsCIf name="Gig0/4" vnicName="Network adapter 6"/>
                <vnsCIf name="Gig0/5" vnicName="Network adapter 7"/>
                <vnsCIf name="Gig0/6" vnicName="Network adapter 8"/>
                <vnsCIf name="Gig0/7" vnicName="Network adapter 9"/>
                <vnsCMgmt name="devMgmt" host="3.5.3.170" port="443"/>
                <vnsCCred name="username" value="admin"/>
                <vnsCCredSecret name="password" value="insieme"/>
            </vnsCDev>
        </vnsLDevVip>
    </fvTenant>
</polUni>

The following REST request creates a service graph in managed mode:

<polUni>
    <fvTenant name="acme">
        <vnsAbsGraph name = "G1">

        <vnsAbsTermNode name = "Input1">
            <vnsAbsTermConn name = "C1" direction = "output">
            </vnsAbsTermConn>
        </vnsAbsTermNode>
    
        <!-- Node1 Provides SLB functionality -->
        <vnsAbsNode name = "Node1" funcType="GoTo" >
            <vnsRsDefaultScopeToTerm
                tDn="uni/tn-acme/AbsGraph-G1/AbsTermNode-Output1/outtmnl"/>

            <vnsAbsFuncConn name = "C4" direction = "input">
                <vnsRsMConnAtt tDn="uni/infra/mDev-Acme-ADC-1.0/mFunc-SLB/mConn-external"/>
                <vnsRsConnToLIf tDn="uni/tn-acme/lDevVip-ADCCluster1/lIf-C4"/>
            </vnsAbsFuncConn>
    
            <vnsAbsFuncConn name = "C5" direction = "output">
                <vnsRsMConnAtt tDn="uni/infra/mDev-Acme-ADC-1.0/mFunc-SLB/mConn-internal"/>
                <vnsRsConnToLIf tDn="uni/tn-acme/lDevVip-ADCCluster1/lIf-C5"/>
            </vnsAbsFuncConn>
    
            <vnsRsNodeToMFunc tDn="uni/infra/mDev-Acme-ADC-1.0/mFunc-SLB"/>
        </vnsAbsNode>

        <vnsAbsTermNode name = "Output1">
            <vnsAbsTermConn name = "C6" direction = "input">
            </vnsAbsTermConn>
        </vnsAbsTermNode>
    
        <vnsAbsConnection name = "CON1">
            <vnsRsAbsConnectionConns
                tDn="uni/tn-acme/AbsGraph-G1/AbsTermNode-Input1/AbsTConn"/>
            <vnsRsAbsConnectionConns
                tDn="uni/tn-acme/AbsGraph-G1/AbsNode-Node1/AbsFConn-C4"/>
        </vnsAbsConnection>
    
        <vnsAbsConnection name = "CON3">
            <vnsRsAbsConnectionConns
                tDn="uni/tn-acme/AbsGraph-G1/AbsNode-Node1/AbsFConn-C5"/>
            <vnsRsAbsConnectionConns
                tDn="uni/tn-acme/AbsGraph-G1/AbsTermNode-Output1/AbsTConn"/>
        </vnsAbsConnection>
    </vnsAbsGraph>
  </fvTenant>
</polUni>

The following REST request creates a service graph in unmanaged mode:

<polUni>
    <fvTenant name="HA_Tenant1">
        <vnsAbsGraph name="g1">

            <vnsAbsTermNodeProv name="Input1">
                <vnsAbsTermConn name="C1">
                </vnsAbsTermConn>
            </vnsAbsTermNodeProv>

            <!-- Node1 Provides LoadBalancing functionality -->
            <vnsAbsNode name="Node1" managed="no">
                <vnsRsDefaultScopeToTerm
                  tDn="uni/tn-HA_Tenant1/AbsGraph-g1/AbsTermNodeProv-Input1/outtmnl"/>
                <vnsAbsFuncConn name="outside" attNotify="true">
                </vnsAbsFuncConn>
                <vnsAbsFuncConn name="inside" attNotify="true">
                </vnsAbsFuncConn>
            </vnsAbsNode>

            <vnsAbsTermNodeCon name="Output1">
                <vnsAbsTermConn name="C6">
                </vnsAbsTermConn>
            </vnsAbsTermNodeCon>

            <vnsAbsConnection name="CON2" adjType="L3" unicastRoute="yes">
                <vnsRsAbsConnectionConns
                  tDn="uni/tn-HA_Tenant1/AbsGraph-g1/AbsTermNodeCon-Output1/AbsTConn"/>
                <vnsRsAbsConnectionConns
                  tDn="uni/tn-HA_Tenant1/AbsGraph-g1/AbsNode-Node1/AbsFConn-outside"/>
            </vnsAbsConnection>

            <vnsAbsConnection name="CON1" adjType="L2" unicastRoute="no">
                <vnsRsAbsConnectionConns
                  tDn="uni/tn-HA_Tenant1/AbsGraph-g1/AbsNode-Node1/AbsFConn-inside"/>
                <vnsRsAbsConnectionConns
                  tDn="uni/tn-HA_Tenant1/AbsGraph-g1/AbsTermNodeProv-Input1/AbsTConn"/>
            </vnsAbsConnection>

        </vnsAbsGraph>
    </fvTenant>
</polUni>

The following REST request creates a filter and a security policy (contract):

<polUni>
    <fvTenant dn="uni/tn-acme" name="acme">
        <vzFilter name="HttpIn">
            <vzEntry name="e1" prot="6" dToPort="80"/>
        </vzFilter>

        <vzBrCP name="webCtrct">
            <vzSubj name="http">
                <vzRsSubjFiltAtt tnVzFilterName="HttpIn"/>
            </vzSubj>
        </vzBrCP>
    </fvTenant>
</polUni>

The following REST request provides graph configuration parameters from an application EPG:

<polUni>
   <fvTenant dn="uni/tn-acme" name="acme">

      <!-- Application Profile -->
      <fvAp dn="uni/tn-acme/ap-MyAP" name="MyAP">
    
          <!-- EPG 1  -->
          <fvAEPg dn="uni/tn-acme/ap-MyAP/epg-MyClnt" name="MyClnt">
              <fvRsBd tnFvBDName="MyClntBD"/>
              <fvRsDomAtt tDn="uni/vmmp-Vendor1/dom-MyVMs"/>
              <fvRsProv tnVzBrCPName="webCtrct">                    
              </fvRsProv>                    
              <fvRsPathAtt tDn="topology/pod-1/paths-17/pathep-[eth1/20]" encap="vlan-201"/>
              <fvSubnet name="SrcSubnet" ip="192.168.10.1/24"/>
          </fvAEPg>  
    
          <!-- EPG 2 -->
          <fvAEPg dn="uni/tn-acme/ap-MyAP/epg-MySRVR"  name="MySRVR">
             <fvRsBd tnFvBDName="MyClntBD"/>
             <fvRsDomAtt tDn="uni/vmmp-Vendor1/dom-MyVMs"/>
             <fvRsCons tnVzBrCPName="webCtrct">                           
             </fvRsCons>                        

             <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any" nodeNameOrLbl="any"
               key="Monitor" name="monitor1">
                 <vnsParamInst name="weight" key="weight" value="10"/>
             </vnsFolderInst>

             <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any" nodeNameOrLbl="any"
               key="Service" name="Service1">
                 <vnsParamInst name="servicename" key="servicename"
                   value="crpvgrtst02-8010"/>
                 <vnsParamInst name="servicetype" key="servicetype" value="TCP"/>
                 <vnsParamInst name="servername" key="servername"
                   value="s192.168.100.100"/>
                 <vnsParamInst name="serveripaddress" key="serveripaddress"
                   value="192.168.100.100"/>
                 <vnsParamInst name="serviceport" key="serviceport" value="8080"/>
                 <vnsParamInst name="svrtimeout" key="svrtimeout" value="9000"/>
                 <vnsParamInst name="clttimeout" key="clttimeout" value="9000"/>
                 <vnsParamInst name="usip" key="usip" value="NO"/>
                 <vnsParamInst name="useproxyport" key="useproxyport" value=""/>
                 <vnsParamInst name="cip" key="cip" value="ENABLED"/>
                 <vnsParamInst name="cka" key="cka" value="NO"/>
                 <vnsParamInst name="sp" key="sp" value="OFF"/>
                 <vnsParamInst name="cmp" key="cmp" value="NO"/>
                 <vnsParamInst name="maxclient" key="maxclient" value="0"/>
                 <vnsParamInst name="maxreq" key="maxreq" value="0"/>
                 <vnsParamInst name="tcpb" key="tcpb" value="NO"/>
                 <vnsCfgRelInst name="MonitorConfig" key="MonitorConfig"
                   targetName="monitor1"/>
              </vnsFolderInst>
      
              <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                nodeNameOrLbl="any" key="Network" name="Network">
                 <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                   nodeNameOrLbl="any" key="vip" name="vip">
                     <vnsParamInst name="vipaddress1" key="vipaddress"
                       value="10.10.10.100"/>
                 </vnsFolderInst>
                 <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                   nodeNameOrLbl="any" devCtxLbl="C1" key="snip" name="snip1">
                     <vnsParamInst name="snipaddress" key="snipaddress"
                       value="192.168.1.100"/>
                 </vnsFolderInst>
                 <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                   nodeNameOrLbl="any" devCtxLbl="C2" key="snip" name="snip2">
                     <vnsParamInst name="snipaddress" key="snipaddress"
                       value="192.168.1.101"/>
                 </vnsFolderInst>
                 <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                   nodeNameOrLbl="any" devCtxLbl="C3" key="snip" name="snip3">
                     <vnsParamInst name="snipaddress" key="snipaddress"
                       value="192.168.1.102"/>
                 </vnsFolderInst>
              </vnsFolderInst>

              <!-- SLB Configuration -->
              <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
               nodeNameOrLbl="any" key="VServer" name="VServer">
                 <!-- Virtual Server Configuration -->
                 <vnsParamInst name="port" key="port" value="8010"/>
                 <vnsParamInst name="vip" key="vip" value="10.10.10.100"/>
                 <vnsParamInst name="vservername" key="vservername"
                   value="crpvgrtst02-vip-8010"/>
                 <vnsParamInst name="servicename" key="servicename"
                   value="crpvgrtst02-8010"/>
                 <vnsParamInst name="servicetype" key="servicetype" value="TCP"/>
                 <vnsFolderInst ctrctNameOrLbl="any" graphNameOrLbl="any"
                   nodeNameOrLbl="any" key="VServerGlobalConfig" name="VServerGlobalConfig">
                     <vnsCfgRelInst name="ServiceConfig" key="ServiceConfig"
                       targetName="Service1"/>
                     <vnsCfgRelInst name="VipConfig" key="VipConfig"
                       targetName="Network/vip"/>
                 </vnsFolderInst>
              </vnsFolderInst>
          </fvAEPg>
      </fvAp>
   </fvTenant>
</polUni>

The following REST request attaches a service graph to a contract:

<polUni>
    <fvTenant name="acme">
        <vzBrCP name="webCtrct">
            <vzSubj name="http">
                <vzRsSubjGraphAtt graphName="G1" termNodeName="Input1"/>
            </vzSubj>
        </vzBrCP>
    </fvTenant>
</polUni>