Third-Party Custom Application Integration with Cisco Catalyst SD-WAN

Third-party custom application integration with Cisco Catalyst SD-WAN

Table 1. Feature history

Feature name

Release information

Feature description

Third-party custom application integration

Cisco IOS XE Catalyst SD-WAN Release 17.16.1a

Cisco Catalyst SD-WAN Manager Release 20.16.1

Cisco SD-WAN Manager supports integration with third-party-developed Cisco IOx applications. These custom applications add functionality to devices that run Cisco IOS XE Catalyst SD-WAN software.

Information about third-party custom application integration with Cisco Catalyst SD-WAN

Cisco SD-WAN Manager supports integration with third-party-developed Cisco IOx applications. These are called custom applications, and add functionality to devices that run Cisco IOS XE Catalyst SD-WAN software.

Connectivity

A Cisco IOx application operates on a device, in a Docker container. The application may or may not include connectivity to other data sources and components, such as these:

Virtual port group interfaces

If the third-party-developed custom application has a networking requirement, Cisco SD-WAN Manager uses virtual port group (VPG) interfaces in the range of 11 to 22, based on their availability. There is no need to reserve specific VPG interfaces.

Supported platforms for third-party custom application integration

Table 2. Supported platforms

Platform series

Models

Supported from

Cisco Catalyst IR1100 Rugged Series Routers

Cisco Catalyst IR1101

Cisco IOS XE Catalyst SD-WAN Release 17.16.1a

Cisco Catalyst SD-WAN Control Components Release 20.16.1

Cisco Catalyst IR1800 Rugged Series Routers

Cisco Catalyst IR1821

Cisco Catalyst IR1831

Cisco Catalyst IR1833

Cisco Catalyst IR1835

Cisco IOS XE Catalyst SD-WAN Release 17.16.1a

Cisco Catalyst SD-WAN Control Components Release 20.16.1

Prerequisites for third-party custom application integration

Resource requirements

Ensure that each device has the CPU, memory, and storage resources required for the third-party-developed custom application. The resource requirements depend entirely on the details of the custom application.

Restrictions for third-party custom application integration

Upgrade limitation

Cisco SD-WAN Manager does not support upgrading a custom application. To upgrade to a newer version, uninstall the current version and install the new version of the application. See Uninstall a third-party custom application.

Application restart

Cisco SD-WAN Manager does not support restarting the third-party-developed custom application.

API key

The API key used for establishing a secure link with the third-party custom application has an expiration period of one year.

Multitenancy

  • In Cisco Catalyst SD-WAN Manager Release 20.16.x, multitenant environments do not support integration with third-party custom applications.

  • From Cisco Catalyst SD-WAN Manager Release 20.18.1, multitenant environments support integration with Cisco Secure Equipment Access only at the tenant level, not at the provider level.

Configuration group

If a third-party custom application is attached to any configuration group, the Export and Import functionalities will not work.

Configure third-party custom application integration, high level

Procedure

Step 1

Activate Cisco IOx on devices

Step 2

Upload the third-party custom application to Cisco SD-WAN Manager

Step 3

Create a Configuration Group Profile with a Custom Application Feature

Step 4

Add a Custom Application Feature to a Configuration Group

Step 5

Deploy a Configuration Group with a Custom Application Feature

What to do next

After the configuration steps, you can monitor the activity of the application operating on a device. See Monitor a third-party custom application on devices.

Activate Cisco IOx on devices

This procedure activates Cisco IOx on devices, which is necessary for running third-party custom Cisco IOx applications.

Before you begin

  • For Cisco Catalyst SD-WAN Manager Release 20.16.x, ensure to activate Cisco IOx on devices before running third-party custom Cisco IOx applications on the devices.

  • From Cisco Catalyst SD-WAN Manager Release 20.18.1, activating Cisco IOx on devices is not required.

Procedure

Step 1

Create a configuration group with a CLI add-on profile.

Step 2

In the CLI add-on profile, include the iox command to activate Cisco IOx. 

iox

Step 3

Use the standard configuration group deployment procedure in Cisco Catalyst SD-WAN Configuration Groups to deploy the configuration group to devices before installing a third-party custom Cisco IOx application.

Upload the third-party custom application to Cisco SD-WAN Manager

You can host a third-party custom application in one of the two ways:

  • Upload the third-party custom application to the SD-WAN Manager local repository, or

  • Upload the third-party custom application to a remote repository

Before you begin

Minimum supported release: Cisco Catalyst SD-WAN Manager Release 20.18.1 and later

Custom application package

Ensure that the third-party custom application package meets the requirements described in the Cisco IOx documentation.

In addition to the above package requirements for a third-party application, ensure the image_properties.xml file uses this format: 

<image_properties>
<vnf_type>app-hosting</vnf_type>
<name>Custom-App</name>
<arch>aarch64/x86_64</arch>
<version>0.85</version>
<imageType>dockertype</imageType> 
<applicationDescription><Custom App Description></applicationDescription>
<applicationVendor>Cisco Systems</applicationVendor>
<applicationMaxInstances>1</applicationMaxInstances>
</image_properties>
Table 3. image_properties.xml element descriptions

Elements

Description
vnf_type Specifies the VM functionality. It is always app-hosting when uploading the application image to SD-WAN Manager.

name

Name of the application. For third-party applications, use Custom-App.

arch

Architecture type of the third-party application. Possible values:

  • x86_64

  • aarch64

See the package.yml file to find the application's architecture.

version

Version of the third-party application as defined in the package.yml file.

imageType

Specifies the type of image: dockertype

applicationDescription

Description of the application, as defined in the package.yml file.

applicationVendor

Name of the application vendor.

applicationMaxInstances

Maximum number of application instances.

Procedure

Step 1

Method 1: If you choose to host the the third-party custom application image in the SD-WAN Manager local repository, follow these steps.

This option is available in a single-tenant environment, or for a service provider operating a multitenant environment.

  1. From the Cisco SD-WAN Manager menu, choose Maintenance > Software Repository.

  2. Click Virtual Images.

  3. Click Add New Virtual Image and select Manager.

  4. Choose your custom application image and click Upload.

    SD-WAN Manager creates an entry in Virtual Images for the locally hosted third-party custom application.

Step 2

Method 2: If you choose to host the third-party custom application on a remote repository server, follow these steps.

This option is available in a single-tenant environment, or for tenants in a multitenant environment. Tenants in a multitenant environment can use this option if the custom application image is not available in the local SD-WAN Manager repository.

  1. Set up a file server and register it in SD-WAN Manager, as described in Register Remote Server.

  2. From the Cisco SD-WAN Manager menu, choose Maintenance > Software Repository > Virtual Images.

  3. Click Add New Virtual Image and select Remote Server.

  4. Enter the third-party custom application image file name.

  5. For Select service type, choose App-Hosting.

  6. For Select app type, choose Custom-App.

  7. Enter the version of your custom application.

  8. For Select architecture, choose aarch64 or x86_64.

  9. In the Remote Server section, select the name of the remote server that you have registered.

    The Remote Server Details shows the details of the locally hosted server.

  10. Click Save.

SD-WAN Manager creates an entry in Virtual Images for the remotely hosted third-party custom application.

Create a Configuration Group Profile with a Custom Application Feature

Because third-party-developed custom applications are unique, Cisco SD-WAN Manager cannot validate the configuration against a common standard. To ensure that the application operates correctly, configure the parameters here according to the requirements of the application.

Before you begin

On the Configuration > Configuration Groups page, choose either

  • SD-WAN, or

  • SD-Routing

as the solution type.

Procedure

Step 1

From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.

Step 2

Create and configure a Custom Application feature in an Other profile.

  1. Enter a name and description for the feature.

    Table 4. Name and Description

    Field

    Description

    Name

    Name for the feature.

    Description

    Optionally, add a description.

  2. The basic settings are mandatory.

    Table 5. Basic Settings

    Field

    Description

    Application Name

    Enter a name for the custom application. You can use upper- or lower-case letters, but not spaces or special characters.

    This name appears as part of the event details on the Monitor > Logs > Events page.

    Virtual Image

    Choose a custom application image file from the drop-down list.

    The list shows custom application images uploaded to the virtual image repository in Maintenance > Software Repository > Virtual Images.

  3. If the custom application has a requirement for network configuration, click Add Configuration and enter the network connectivity details for up to three connections. This configures communication between the Cisco IOx application and

    • the device on which the application is operating, and

    • any external assets, such as a server if the application communicates with a server.

    Note

     

    At least one network configuration is required for a third-party custom application.

    Here are the options for the SD-WAN solution:

    Table 6. Network Configuration, SD-WAN Solution

    Field

    Description

    Name

    Name describing the entity for which you are configuring connectivity.

    Service VPN

    Service VPN providing the connectivity between the application and either (a) the device, or (b) an external asset.

    VPG IP Address

    IP address within the subnet mask defined in the Subnet Mask field for communication between the custom application and a device virtual port group (VPG) interface or external asset.

    Application IP Address

    IP address to assign to the custom application, for mapping to a VPG interface on the device.

    Subnet Mask

    Subnet mask for the VPG interface. The subnet mask defines an address space for the service VPN for communication between the custom application and a device VPG interface or external asset.

    Action

    Provides an option to delete a row.

    Here are the options for the SD-Routing solution:

    Table 7. Network Configuration, SD-Routing Solution

    Field

    Description

    Network Configuration

    Name

    Name describing the entity for which you are configuring connectivity.

    Communication Interface

    Physical or virtual interface providing connectivity between the application and either (a) the device, or (b) an external asset.

    Action

    Provides an option to delete a row.

  4. Some custom applications require information passed as variables, either global or device-specific. To add variables, click Add Variable and enter the details.

    The specifics of the valid key:value pairs depend entirely on the details of the custom application. Consult with the custom application developer for information about configuring variables. Note that these values are case sensitive.

    Maximum number of variables: 10

    Table 8. Environment Variables

    Field

    Description

    Key

    Key name for a variable.

    Value

    Value of the variable. Choose Device Specific to provide a specific key value for each device.

    Action

    Provides an option to delete a row.

  5. Some custom applications use data input provided through a serial interface. This option supports any serial port available on the platform.

    To add a data source, click Add Data Source and enter the serial port.

    Maximum number of serial ports: 7

    Table 9. Data Configuration

    Field

    Description

    Serial Line

    Enter a serial port available on the device. See the platform documentation for information about serial ports.

    Example: /dev/ttySerial

    Action

    Provides an option to delete a row.

What to do next

Also see Deploy a configuration group.

Add a Custom Application Feature to a Configuration Group

Procedure

Step 1

From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.

Step 2

In the solution drop-down list, choose either

  • SD-WAN, or

  • SD-Routing

as the solution type to display configuration groups only for this solution.

Step 3

Click the Configuration Groups tab.

Step 4

If you need to create a configuration group, follow the steps described in Using Configuration Groups in Cisco Catalyst SD-WAN Configuration Groups.

Step 5

For an existing configuration group, click Add Profile and add an Other Profile to the configuration group.

Step 6

In the configuration group, locate the Other Profile drop-down list and choose a Custom Application profile.

Deploy a Configuration Group with a Custom Application Feature

Before you begin

See Supported platforms for third-party custom application integration before deploying a configuration group with the Custom Application feature.

Activate Cisco IOx on devices before deploying the configuration group. See Activate Cisco IOx on devices.

Procedure

Step 1

Use the standard configuration group deployment procedure in Cisco Catalyst SD-WAN Configuration Groups to deploy a configuration group to devices in the network.

Step 2

If you are deploying to devices of the SD-WAN solution type, during deployment, enter any required device-specific variables for each router.

Step 3

If you want to monitor the progress of installing the application on a device, view the log messages for the installation.

  1. Click the task list button near the top right.

  2. Click the Deploy configuration group task.

    This opens a page showing the deployment progress for each device.

  3. Adjacent to a device, click the log icon in the Action column.

    The View Logs pane opens, showing the deployment progress for the device. When the deployment is complete, a success message, such as "Config Group successfully deployed to device," appears in the log.

    When you first deploy a configuration group with the Custom Application feature to a device, it triggers the device to install the application.

Verify that a third-party custom application is operating on a device, using the CLI

This verification method is applicable to devices in the SD-WAN or SD-Routing solutions.

Before you begin

Deploy a configuration group with a Custom Application feature to one or more devices. See Deploy a Configuration Group with a Custom Application Feature.

Procedure

Step 1

On a device running the Cisco IOx application, run this command.

Device# show iox-service

Step 2

Based on the output of the command in the previous step, do one of these:

  • If the command output shows that the IOxman service is running, then proceed to the next step.

  • If the command output shows that the IOxman service is not running, this indicates that the Cisco IOx application is not operating correctly. Reinstall the application. See Deploy a Configuration Group with a Custom Application Feature.

Step 3

On the same device, run this command. If the output shows the state as running for the application you are checking, this indicates that the application is operating correctly. 

Device# show app-hosting detail appid application-id

Example

The application name that you enter in the Custom Application feature determines the application ID that appears in the command output. See Create a Configuration Group Profile with a Custom Application Feature. In this example, the application ID is abc.

The command output is truncated here.

Device# show iox-service
IOx Infrastructure Summary:
IOx service (CAF)              : Running
IOx service (HA)               : Not Supported
IOx service (IOxman)           : Running
IOx service (Sec storage)      : Running
Libvirtd 5.5.0                 : Running
Dockerd v19.03.13-ce           : Running

Device# show app-hosting detail appid abc
App id                 : abc
Owner                  : iox
State                  : RUNNING
...

Monitor a third-party custom application on devices

Before you begin

Deploy a configuration group with a Custom Application feature to one or more devices. See Deploy a Configuration Group with a Custom Application Feature.

Procedure

Step 1

From the Cisco SD-WAN Manager menu, choose Monitor > Devices.

Step 2

Click a device name for a device in the SD-WAN solution.

Note

 

This monitoring method is applicable to devices in the SD-WAN solution, but not to devices in the SD-Routing solution.

Step 3

Click the Real Time tab.

Step 4

Enter any of these App Hosting commands in the Device Options field to view the resource usage or other details of applications operating on the device, including a third-party-developed custom applications:

  • App Hosting Details

  • App Hosting Utilization

  • App Hosting Network Utilization

  • App Hosting Storage Utilization

  • App Hosting Processes

  • App Hosting Attached Devices

  • App Hosting Network Interfaces

  • App Hosting Guest routes

Uninstall a third-party custom application

Uninstalling a third-party-developed custom application presumes that you have installed the application already. See Configure third-party custom application integration, high level.

Procedure

Step 1

Remove the Custom Application feature from the configuration group.

  1. From the Cisco SD-WAN Manager menu, choose Configuration > Configuration Groups.

  2. Click the Configuration Groups tab.

  3. Adjacent to a configuration group, click the arrow in the Actions column to expand the row to show the attached profiles.

  4. Adjacent to the Other Profile drop-down list, click the pencil icon to edit the profile.

  5. Within the profile, remove the Custom Application feature.

Step 2

Deploy the configuration group to devices. See Deploy a Configuration Group with a Custom Application Feature.

The procedure uninstalls the custom application from devices to which it had been deployed.