ESC uses NETCONF to configure and manage the network and its devices. NETCONF is a network management protocol to install, manipulate, operate and delete the configuration of network devices. Cisco NSO communicates with ESC using the open NETCONF protocol and YANG based data models. ESC manages Virtual Network Functions at a device level, and NSO manages the entire network service lifecycle. Together, they make it a complete orchestration solution that spans across both physical and virtual infrastructure.

Along with NETCONF notifications, the NETCONF/YANG model also provides operational data. You can run query to get details such as list of all tenants, networks, and deployments in ESC.

<esc_datamodel xmlns="http://www.cisco.com/esc/esc">
<tenants>
  <tenant nc:operation="delete">
    <name>abc-mix-tenant1</name>
  </tenant>
  <tenant nc:operation="delete">
    <name>abc-mix-tenant2</name>
  </tenant>
</tenants>
</esc_datamodel>

Examples of NETCONF/YANG API are as follows:

<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <source>
      <running/>
    </source>
    <config>
      <esc_datamodel xmlns="http://www.cisco.com/esc/esc">
        <tenants>
          <tenant>
            <name>mytenant</name>
          </tenant>
        </tenants>
      </esc_datamodel>
    </config>
  </edit-config>
</rpc>

An escEvent of type CREATE_TENANT with a status of SUCCESS is sent to NETCONF subscribers once the configuration activation is completed. This indicates that the activation workflow is complete and the configuration resource is successfully created in the VIM.

NETCONF notification after a tenant is successfully created:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2015-05-05T19:38:27.71+00:00</eventTime>
  <escEvent xmlns="http://www.cisco.com/esc/esc">
    <status>SUCCESS</status>
    <status_message>Tenant successfully created</status_message>
    <tenant>mytenant</tenant>
    <vm_source/>
    <vm_target/>
    <event>
      <type>CREATE_TENANT</type>
    </event>
  </escEvent>
</notification>

The operational data (Opdata) for the tenant shows the name and tenant_id. NETCONF request,

 
	<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get>
    <filter select="esc_datamodel/opdata/tenants/tenant[name=’mytenant’]" type="xpath"/>
  </get>
</rpc>

NETCONF response,

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <data>
    <esc_datamodel xmlns="http://www.cisco.com/esc/esc">
      <opdata>
        <tenants>
          <tenant>
            <name>mytenant</name>
            <tenant_id>dccd22a13cc64e388a4b8d39e6a8fa7f</tenant_id>
        </tenant>
      </tenants>
    </esc_datamodel>
  </data>
</rpc-reply>

For more details on series of notifications, event failure notifications, and opdata, see the Cisco Elastic Services Controller API Guide.

The NETCONF API configuration and RPC calls are validated. If the request is not valid, it is rejected. The NETCONF API does not send any error code to NB, unlike REST (for example, REST sends 404 not found error).

A sample error message (rejected request) is as follows

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
    <rpc-error>
        <error-type>application</error-type>
        <error-tag>operation-failed</error-tag>
        <error-severity>error</error-severity>
        <error-path xmlns:esc="http://www.cisco.com/esc/esc" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">/nc:rpc/esc:filterLog</error-path>
        <error-message xml:lang="en">Exception from action callback: Error when handling RPC
            calls: You can only query up to 30 logs.</error-message>
        <error-info>
            <bad-element>filterLog</bad-element>
        </error-info>
    </rpc-error>
</rpc-reply>

In ESC Release 2.2 and later, the no_gateway attribute allows ESC to create a subnet with the gateway disabled.

In the example below, the no_gateway attribute is set to true to create a subnet without gateway.

      <networks>
        <network>
           <name>mgmt-net</name>
            <subnet>
               <name>mgmt-net-subnet</name>
                <ipversion>ipv4</ipversion>
                <dhcp>false</dhcp>
               <address>10.20.0.0</address>
		       <no_gateway>true</no_gateway><!--  DISABLE GATEWAY -->
                <gateway>10.20.0.1</gateway>
                <netmask>255.255.255.0</netmask>
            </subnet>
          </network>
       </networks>

In ESC Release 2.2 and later, ESC shows OpenStack and VMware vCenter username in its Operational Data section.

The following configuration details are displayed in the Operational Data for,

OpenStack

• active_vim—displays the value as OpenStack

• os_auth_url—displays the OpenStack authentication URL

• admin_role—displays if the OpenStack user is an admin

• os_tenant_name—displays the tenant

• os_username—displays the Openstack user

• member_role—displays if the OpenStack user is a member

VMware vCenter

• active_vim—displays the value as VMware

• vcenter_ip—displays the vCentre IP address

• vcenter_port—displays if the vCentre port

• vcenter_username—displays the vCentre user

NETCONF Request Enhancement

Starting from ESC 2.2, user can create a single NETCONF request to configure multiple resources.

Note	A single request to configure multiple resources is supported using NETCONF only.

A single NETCONF request associates multiple resources based on the dependencies between the resources. For example, a subnet is dependent on a network, and a deployment is dependent on the image and flavor.

There are 2 types of dependencies in ESC.

1. Referential Dependency

2. Hierarchical Dependency

Referential Dependency

In referential dependency, one configuration has a reference to another configuration.

In the example below, deployment has referential dependency on image (abc-mix-cirros) and flavor (abc-mix-small). The image and flavor must be created before the deployment configuration.

   <images>
        <image>
            <name>abc-mix-cirros</name>
            ...
        </image>
    </images>
    <flavors>
        <flavor>
          <name>abc-mix-small</name>
            ...
        </flavor>
    </flavors>
    <tenants>
        <tenant>
          <name>abc-mix-tenant</name>
           <deployments>
             <deployment>
               <name>dep</name>
                <vm_group>
                  <name>Group1</name>
                    <image>abc-mix-cirros</image>
                    <flavor>abc-mix-small</flavor>
                        ...
                   </vm_group>
                </deployment>
             </deployments>
          </tenant>
      </tenants>

Hierarchical Dependency

In hierarchical dependency, one configuration is within another configuration.

In the example below, the subnet (abc-mix-shared-subnet1) is within the network (abc-mix-shared-net1). The subnet has a hierarchical dependency on the network.

<esc_datamodel xmlns="http://www.cisco.com/esc/esc">
<networks>
  <network>
    <name>abc-mix-shared-net1</name>
    <shared>true</shared>
    <admin_state>true</admin_state>
    <subnet>
      <name>abc-mix-shared-subnet1</name>
      <ipversion>ipv4</ipversion>
      <dhcp>true</dhcp>
      <address>10.193.90.0</address>
      <netmask>255.255.255.0</netmask>
      <gateway>10.193.90.1</gateway>
    </subnet>
  </network>
</networks>
</esc_datamodel>

A hierarchical dependency is a subset of referential dependency. These configuration dependencies of the resources allow NETCONF to perform multiple configurations using a single request.

The REST API is a programmatic interface to ESC that uses a Representational State Transfer (REST) architecture. The API accepts and returns HTTP or HTTPS messages that contain JavaScript Object Notation (JSON) or Extensible Markup Language (XML) documents. You can use any programming language to generate the messages and the JSON or XML documents that contain the API methods or managed object (MO) descriptions.

A typical request comes into ESC and is placed in the transactor queue in first in, first out (FIFO) order. The transactor gets the request from the queue, interprets the request, and performs an authorization check. After the request is confirmed, the transactor updates the MIT. This complete operation is done in a single transaction.

Note	For detailed reference information about API classes, properties, and data types, see the Cisco Elastic Services Controller API Guide.

Example of REST APIs

POST /v0/tenants/123 HTTP/1.1
Host: client.host.com
Content-Type: application/xml
Accept: application/xml
Client-Transaction-Id: 123456
Callback:/createtenantcallback
<?xml version="1.0" encoding="UTF-8"?>
<tenant xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<name>xyz</name>
<enabled>true</enabled>
<description>A description...</description>
</tenant>

REST response after a tenant is successfully created:

HTTP/1.1 201 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 200
Date: Sun, 1 Jan 2011 9:00:00 GMT
ESC-Transaction-Id: 123456
ESC-Status-Code: 200
ESC-Status-Message: Success …
<?xml version="1.0" encoding="UTF-8"?>
<tenant>
<external_tenant_id>234243490854004</external_tenant_id>
<internal_tenant_id>434344896854965</internal_tenant_id>
<name>xyz</name>
<enabled>true</enabled>
<description>A description...</description>
</tenant>

For more details on response callback, request parameters, see the Cisco Elastic Services Controller API Guide.

Note	Further in this document, examples for scenarios will be provided either using REST or NETCONF/YANG, but not both.

The ESC portal provides default admin access. To login:

1. Using your web browser, enter the IP address of ESC and port number:

   • Login via HTTPS: https://esc-mgmt-ip:9001

     Note	If you login using http://esc-vm-ip:9000 (supported prior to ESC Release 2.3), you will be redirected to https://esc-mgmt-ip:9001.

2. Enter the username and password, and login to the portal.

For more details on port, and browser requirements see the Cisco Elastic Services Controller Install and Upgrade Guide.

After logging into the ESC portal for the first time, you are prompted to change the default portal password (set up at the time of installation). For more information, on how to change the ESC portal passwords using either ESC CLI or the ESC portal, see Changing the ESC Portal Password in the Cisco Elastic Services Controller Install and Upgrade Guide.

The Cisco Elastic Services Controller dashboard provides a tabular representation of all the managed ESC resources, deployments, infrastructure, incoming requests, notifications, and visual indicators of system health. The following dashboard elements help you track, monitor and diagnose data and system health over time.

• Resources

• Deployments

• Infrastructure

• Incoming Requests

• Notifications

• System

The dashboard is best used in a monitoring desk context, where the system displaying the dashboard is dedicated for that purpose and might be distinct from the systems running the portal servers. The dashboard system should point its browser to the system running the portal servers.

If you notice unusual spikes or drops in activity, there could be communication failures or power outages on the network that you need to investigate.

Table below lists the details users can view in the portal:

Note	These tasks can also be performed using the NB APIs. See the Elastic Services Controller NB APIs for more details.

After logging into the ESC portal for the first time, you are prompted to change the default password. For more information, on how to change the ESC portal passwords using either ESC CLI or the ESC portal UI, see Changing the ESC Portal Password in the Cisco Elastic Services Controller Install and Upgrade Guide.