The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Cisco Elastic Services Controller (ESC) can be deployed in one of the following ways:
As part of the Cisco Orchestration suite—ESC is packaged with Cisco Network Services Orchestrator (NSO), and available within Cisco Solutions such as Virtual Managed Services (vMS).
When ESC is deployed as a part of the vMS, VPN, vRouter and so on, these applications interface with ESC through the Northbound APIs. ESC supports both REST and NETCONF northbound interfaces for operations and transactions. In addition, in ESC Release 2.0 and later, the ESC portal supports CRUD operations for some of the task for Virtual Network Function lifecycle management.
This chapter contains information about the Northbound APIs and the ESC portal.
Elastic Services Controller (ESC) supports REST and NETCONF northbound interfaces for operations and transactions. The northbound interfaces interact with the NB client, NSO or any OSS. For REST interface interactions, callbacks are triggered, and for NETCONF/YANG interface interactions, NETCONF notifications are triggered.
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
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.
Referential DependencyIn 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.
![]() 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 is a simplified Web-based tool for an ESC administrator to create, read, update, or delete (CRUD) operations related to VNF lifecycle management. As an administrator you can create and view the real-time activities of ESC such as deploying, undeploying, healing and scaling.
The ESC portal is enabled by default while creating an ESC VM on OpenStack, VMware vCenter or KVM. For more information on enabling or disabling the ESC portal, see Cisco Elastic Services Controller Install and Upgrade Guide.
To start, stop and check the status of the ESC Portal, do the following:
ssh user-name@ip-address-of-esc-vm
sudo su
status esc_ui
To start ESC UI, run start esc_ui
To stop ESC UI, run stop esc_ui
To restart ESC UI, run restart esc_ui
![]() Note | If the UI becomes unresponsive, restart the UI by executing the restart esc_ui from the ESC prompt. |
![]() Note | The recommended browser screen size is 1920 pixels by 1080 pixels. |
The ESC portal provides default admin access. To login:
Using your web browser, enter the IP address of ESC and port number:
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.
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.
The Resources dashboard displays information related to the resources (inband) managed by the ESC Portal. On OpenStack, you can view the number of active VMs, deployed VMs, VMs in error state, images, tenants, flavors, and networks. On VMware vCenter, you can view the number of active VMs, deployed VMs, VMs in error state, images, and networks.
The Deployments dashboard displays a high level summary of deployments that are currently being deployed. You can view the name and status of the deployments, and the number of VMs that are deployed in the deployment.
The Infrastructure dashboard displays information about the virtual infrastructure manager, the status and IP address of the VIM.
The Incoming Requests dashboard displays the requested action, callback URL, the type of incoming request and the time when the request was sent. ESC integrates with other applications through northbound APIs (both REST and NETCONF) to list incoming request details.
The Notifications dashboard displays notifications received on the Portal from ESC.
The System dashboard comprises of the following tabs:
Performance tab—Displays the tabular and graphical representation of the performance data.
Storage tab—Displays the disk usage information.
vCPU Utilization tab— Displays the usage of vCPUs in the ESC VM.
Component Health tab—Displays the health of various ESC processes such as network, database, and tomcat.
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. |
Task |
Navigate |
Description |
||
---|---|---|---|---|
To view Dashboard |
Go to Dashboard |
View the summary of all the managed ESC resources, infrastructure, notifications, and the system health. |
||
To view notifications |
Choose |
Displays notifications received on the Portal from ESC.
|
||
To view existing deployments (for both OpenStack and VMware vCenter) |
Go to Deployments |
Shows all the deployed VMs, and VM groups and their status. |
||
To view tenants |
Go to Resources > Tenants |
Provides a list of tenants, along with its name, description and ID. ESC does not support multi-tenancy on VMware vCenter. Portal does automatic rollback of resources if the resources failed to be created on the VIM. In some cases (because of conflicting dependencies), the tenant has to be deleted manually after getting a rollback failure notification. |
||
To view networks, sub-networks and interfaces |
Go to Resources > Networks |
|
||
To view VNF Images |
Go to Resources > Images |
Provides a list of images for the selected resources. |
||
To view VNF deployment flavors (OpenStack only) |
Go to |
Provides a list of flavors for the selected resources. |
||
To view the switch details (VMware vCenter only) |
Go to Resources > Switches |
Provides a list of switches, its names, descriptions, UUIDs and hosts. |
||
To view logs |
Go to System > Log To view settings, Click the gear icon at the top right corner. |
You will find real-time logs for ESC events throughout the VNF lifecycle. In the Settings page, you can filter error, trace, warning, thread activities, rest calls, database, transitions, and timer messages. Displays real-time logs for ESC events, such as messages from the external systems, messages from ESC to external systems, and some key events such as spin up, spin down, failures and services. ESC log view retrieves the last 5 MB (around 16000 lines) of the log file. |
||
To view incoming requests to ESC |
Go to System > Incoming Requests |
Lists all the incoming requests to ESC such as Transaction ID and request details. |
||
To view configurations |
Go to System > Configuration |
Lists all the configuration parameters used for configuring VMs, monitoring rules, applying policies during VM deployments, and so on. |
||
To view boot parameters (OpenStack only) |
Go to System > Boot Parameters |
Lists all the boot parameters used to boot ESC. |
||
To view host details (OpenStack only) |
Go to System > Host details |
Lists the host details such as Operating System (OS), version of the OS, System uptime , RAM, Storage and other details. |
||
To view the health of ESC (OpenStack only) |
Go to System > Health |
Show the health of ESC, Confd status, Operational status and other details. |
||
To view the infrastructure details (OpenStack only) |
Go to Infrastructure > Instances |
All VMs running on the virtualization infrastructure. |
||
To view the Hypervisors (OpenStack only) |
Go to Infrastructure > Hypervisors |
All hypervisors running on the virtualization infrastructure. |
||
To deploy a VNF |
|
Deploys a VNF.
The drag and drop feature executes a REST call as of now and does not execute NETCONF calls. |
||
To undeploy a VNF |
Undeploys VNF(s). |
|||
To view VDC (VMware vCenter only) |
Choose |
View list of all Virtual Datacenters. |
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.