Cisco VMS Service Extensions
Understanding How Cisco VMS Service Extensions Work
Creating a VMS Service Extension Template XML File
Importing the Template XML File into NSO
Defining Service Extension Parameters for a Provider, Tenant Group, or Tenant
Specifying Default Value for a Service Extension Tenant Parameter
- Specify Service Extension Parameter Default Value for Tenants
- Specify Service Extension Parameter Default Value for Tenant Groups
Creating a Service Extension in the VMS Portal
Service Extensions on a Device
- Applying Service Extensions on a Device

Cisco VMS Service Extensions

This chapter provides an overview of VMS service extensions and also describes the process to create, import, and apply service extension template to a service workflow.

This chapter contains the following topics:

Understanding How Cisco VMS Service Extensions Work

VMS service extensions simplifies how configuration snippets can be applied to a service or a device. VMS leverages the underlying capability of Cisco Network Services Orchestrator (NSO) custom templates, which get pushed along with the derived configuration templates. Service extensions can be used, in most cases, to map services to device configurations, without the need for any additional programming.

VMS service extension templates use variables to map service attributes to the corresponding device configurations and are applied. The service extensions allow a declarative way to describe such manipulations. The VMS operator can apply a service extension template to an existing service chain in VMS or to a device, without having to manually go into the NSO CLI. This service extension template is used by NSO to add, modify, or delete service configuration snippets before NSO pushes the configuration to the devices.

You can apply VMS service extension templates to a service ordering workflow or a single device. When you import a service extension template into VMS, you can specify if the template is to be applied to a service workflow or a device.

When a service extension template is applied to service ordering workflow, VMS service workflow gathers the parameter values the tenant users enter during service ordering process. These values are passed to NSO, which further uses these values in the device configurations.

The following illustration depicts the end-to-end workflow that needs to be followed to work with service extension templates in VMS.

Figure 1. VMS Service Extensions Workflow

Creating a VMS Service Extension Template XML File

The VMS service extension template is an XML file. The structure of that file is defined by the YANG model.

The basic principles of defining a template are as following:

A template is an XML file (for example mytemplate.xml) that corresponds to a node in the device tree.
Each value in a template is stored as a string. This string value is converted to the actual value type of the YANG model when the template is applied.
The value part of the XML tag that needs to be configured must be represented with a variable name prefixed with '$' literal.
The templates allow for defining different behavior while applying the template. This is accomplished by setting tags such as merge, replace, delete, create or nocreate on the relevant nodes in the template.

For example, to create a template to set the NTP server on a device, the sample template XML file should be:

<config
    xmlns="http://tail-f.com/ns/config/1.0">
    <device
        xmlns="http://tail-f.com/ns/ncs">
        <name>ntp</name>
        <config tags="merge">
            <system xmlns="http://pica8.org/yang">
                <ntp-server-ip>{$NTP}</ntp-server-ip>
            </system>
            <ntp xmlns="urn:ios">
                <server>
                    <server-list>
                        <ip-address>{$NTP}</ip-address>
                    </server-list>
                </server>
            </ntp>
        </config>
    </devices>
</config>

After you create a service extension template, you need to do the following:

Import the template XML file into NSO. For details see, Importing the Template XML File into NSO.

Import the template XML file into VMS. For details see, Creating a Service Extension in the VMS Portal.

Importing the Template XML File into NSO

To import a template XML file into NSO, you need to:

Procedure

Step 1

Step 2

Create the Custom templates folder (only first time).

admin@ncs%sudo mkdir /var/opt/ncs/packages/custom-templates/templates/

Step 3

Create package-meta-data.xml file in /var/opt/ncs/packages/custom-templates folder (only first time).

admin@ncs%sudo vi package-meta-data.xml   <== copy content below

<ncs-package
    xmlns="http://tail-f.com/ns/ncs-packages">
    <name>custom-templates</name>
    <package-version>1.0</package-version>
    <description>Custom template store</description>
    <ncs-min-version>4.1</ncs-min-version>
</ncs-package>

Step 4

Verify the contents of the package-meta-data.xml file (only first time).

admin@ncs%/var/opt/ncs/packages$ cat /var/opt/ncs/packages/custom-templates/package-meta-data.xml 

<ncs-package
    xmlns="http://tail-f.com/ns/ncs-packages">
    <name>custom-templates</name>
    <package-version>1.0</package-version>
    <description>Custom Template Store</description>
    <ncs-min-version>4.1</ncs-min-version>
</ncs-package>

Step 5

Add service extensions custom templates to NSO, in the /var/opt/ncs/packages/custom-templates/templates folder.

Step 6

Enable NSO custom templates:

admin@ncs%set globals custom-template true
admin@ncs%commit

Step 7

Reload NSO.

admin@vms-ncs-tmepoc1-sm% request packages reload

Note

When you reload NSO, ensure that the new template is present in the /var/opt/ncs/packages/custom-templates/templates folder.
When the packages reload, ensure that all the CLI sessions are in operational mode and none of them are open in the Config mode.

Defining Service Extension Parameters for a Provider, Tenant Group, or Tenant

When a service extension template is imported into VMS, the operator needs to specify the metadata for each service extension parameter. In addition, the value of some of these parameters could be common across all devices for a service provider or for a tenant. In Cisco VMS 3.1 and later, when a service extension template is imported you can map the metadata and default values for service extension parameters. This is done by mapping template parameters to the predefined service extensions provider or tenant parameters during the template import process. The three types of service extension parameters are:

Provider Parameters - Defined at the service provider level. The provider parameters are available across all the tenants.
Tenant Group Parameters – Defined at the service provider level but the default value can be set for each tenant group.

Tenant Parameters - Defined by the service extension designer and the default value can be set for each tenant.

Note

When you define a tenant service extension parameter, you need to associate the parameter to a tenant or tenant group and can provide separate default values for each tenant or tenant group. For more information, seeSpecifying Default Value for a Service Extension Tenant Parameter .

The service extension parameters provide the following advantages:

Can be defined at the service provider or the tenant group or the tenant level.
Parameters are auto-mapped when a template XML file is imported into VMS and the parameter metadata gets inherited.
Follows the order of precedence—First tenant parameters are used, if one exists. Otherwise the provider parameter is used.
Set the default parameter values for provider or tenant parameter in service ord ering process.

To define service extension parameter, you need to:

Procedure

Step 1

Note

Cisco Virtual Managed Services now includes a new predefined role: Service Extension Designer. Service extension designers can import service extension templates, define service extension parameters, define default parameter values, and so on.

Step 2

From the Left Hand Side menu, choose Setting, and Extensions.

Step 3

To add service provider level parameters, do the following:

Click the Provider tab.
Click the Add Extension Parameter button.
Enter the parameter name.
Enter the parameter label that is displayed on the VMS portal.
Select the input type.
Select the display type.
Enter the default value for the parameter.
Click Save.

Step 4

To add Tenant Group parameters, do the following:

Click the Tenant Group tab.
Click the Add Extension Parameter button.
Enter the parameter name.
Enter the parameter label that is displayed on the VMS portal.
Select the input type.
Select the display type.
Click Save.

Step 5

To add tenant level parameters, do the following:

Click the Tenant tab.
Click the Add Extension Parameter button.
Enter the parameter name.
Enter the parameter label that is displayed on the VMS portal.
Select the input type.
Select the display type.
Click Save.

Specifying Default Value for a Service Extension Tenant Parameter

When you define service extension tenant parameter, you need to specify the default value for each tenant. This default value is inherited by the parameter when the service extension template is applied to a service workflow.

To specify service extension tenant parameter value, you need to:

Specify Service Extension Parameter Default Value for Tenants

Procedure

Step 1

Note

Step 2

From the Left Hand Side menu, choose Tenants.

The Manage Tenants screen appears.

Step 3

To specify the parameter default value, select the tenant user on the list and click the Edit icon.

Step 4

Specify the default value for the service extension parameter.

Step 5

Click Save.

Specify Service Extension Parameter Default Value for Tenant Groups

Procedure

Step 1

Note

Step 2

From the Left Hand Side menu, choose Tenants Group.

The Manage Tenants Groups screen appears.

Step 3

To specify the parameter default value, select the tenant user on the list and click the Edit icon.

Step 4

Specify the default value for the service extension parameter.

Step 5

Click Save.

Creating a Service Extension in the VMS Portal

Before you import service extension templates into VMS, you can define the service extensions global or tenant group or tenant parameters. For more information, see Defining Service Extension Parameters for a Provider, Tenant Group, or Tenant.

To create a Service Extension, you need to:

Procedure

Step 1

Note

Step 2

From the Left Hand Side menu, choose Configurations.

Step 3

Click the service for which you want to import the service extension template.

Step 4

Click the Service Extensions tab.

Step 5

Click the Add Service Extension button.

Step 6

Click the Upload File button, to import the service extension template XML file.

Note

The template name should match the exact name uploaded into NSO.

Step 7

Enter the template name and the description.

Step 8

Click Next.

Step 9

Do one of the following:

To apply the template to all the tenant, select All Tenants.
To apply the template to specific tenants, select Specific Tenants and select one or more tenant.

Step 10

Specify the XPATH that the service extension applies to. For more information, see table below.

Service Pack

XPATH

Device Type

cVPN Service Pack

/cloudvpn

Hub Router

/cloudvpn/cpe

CPEs

/cloudvpn/firewall

ASA Firewall

/cloudvpn/wsa

WSA Services

/cloudvpn/cpe[id='{DEVICE-ID}']

Note

This XPATH must be specified for device templates.

Corresponding device

IWAN Service Pack

/iwan/hub-sites/

Border Routers

/iwan/hub-sites/

Master Controllers

/iwan/sites/cpes

Branch Devices

/iwan/sites[./name='SITE2']/cpes

Only Branch Device SITE2

/iwan/sites[contains(name, 'SITE1')]/cpes

Branch Device Name Contains “SITE1”

/iwan/hub-sites/border-routers[name='{$ROUTER-ID}']

Specific router

/iwan/sites/cpes[name='{$CPE-ID}']

Note

This XPATH must be specified for device templates.

Corresponding device

Step 11

To apply a service extension template to a service order or a device, do one of the following:

To enable the service extension template for a service order, select Yes.
To enable the service extension template for a device, select No.

Step 12

Click Next.

The service extensions parameters are displayed.

VMS auto-maps the template parameters if the parameter name matches with the predefined service extension parameters, see Defining Service Extension Parameters for a Provider, Tenant Group, or Tenant.

Note

If you are enabling service extensions on a device, it is not mandatory to define the service extension parameters for a device. In this scenario, skip Step 13 and 14 and proceed directly to Step 15.

Step 13

To edit the parameter auto-mapping attributes, click the parameter and do the following:

Select the Function Pack Context check box.

Note

If functional pack context check box is selected, then the parameter will not be seen in the form when applying the extension. The value will be resolved by NSO.
If the check box is not selected, then the value should be provided by the user either by mapping it to a predefined (provider, tenant, tenant-group) parameter or by providing it when applying the extension.

Click Edit extension parameter mapping link to disassociate the auto-mapping.
Click Done.

Step 14

Specify the Input Type and Display Type attributes for the service extension parameters.

Note

If the Input Type and Display Type attribute is not specified for a parameter it is considered as a text field in the service ordering form.

Step 15

Click Save and Enable.

The service extension template is available to customers while they order the service.

Service Extensions on a Device

In addition to applying VMS service extension templates to a service ordering workflow, Cisco VMS provides you the capability to also apply these templates on a device. When you are importing a service extension template to VMS, you can specify whether the template has to be applied on a service workflow or on a device.

When a service extension template is applied to a device after the service is ordered, the service extension template is applied to the device outside the service ordering workflow and is available for the use of individual devices. The following table lists the various steps involved before applying the service extension templates to a device.


Steps	Related Section	Notes
1. Create a VMS Service Extension Template XML File.	Creating a VMS Service Extension Template XML File
2. Import the Template XML File into NSO.	Importing the Template XML File into NSO
3. Create a Service Extension in the VMS Portal.	Creating a Service Extension in the VMS Portal	While performing this procedure, make sure that you: Specify the XPATH of the device where the Service Extension has to be applied. For example, the XPATH for IWAN can be`/iwan/hub-sites/border-routers[name=’{$ID}’` or any other device where you want to apply the service extension. Adding a dollar parameter in the XPATH for a device ID automatically converts the Service Extension into a Device Extension. Enable the service extension template for a device by setting the service extension template option for a service order as 'No'. Skip Step 13 and 14 and proceed directly to Step 15, as it is not mandatory to define the service extension parameters for a device.
4. Apply Service Extensions on a Device.	Applying Service Extensions on a Device

Applying Service Extensions on a Device

To apply a service extension template to a device:

Procedure

Step 1	Log in to the Cisco VMS Portal.
Step 2	From the left pane of the Service Interface, click Devices to view the list of devices you have purchased in the Register Device window.
Step 3	Click the device for which you want to apply service extension template and click Device Extensions. The Device Extension dialog box appears.
Step 4	Click the service extension and specify the corresponding parameter value.
Step 5	Click Update.

Cisco Virtual Managed Services (VMS) 3.3 Platform User Guide

Bias-Free Language

Book Title

Cisco Virtual Managed Services (VMS) 3.3 Platform User Guide

Chapter Title