npm package: @itentialopensource/l2-l3-vpn
Description: A IAP demo demo for handling and managing L2VPN (Layer 2 Virtual Private Network) and L3VPN (Layer 3 Virtual Private Network) services.
Author: Itential Artifacts
Latest version: 1.3.3-2019.3.1

# L2-L3-VPN

## Table of Contents

- [Intro](#intro)
- [Supported device types](#supported-device-types)
- [Test environment](#test-environment)
- [Installation](#installation)
  - [L2VPN Service Model](#l2vpn-service-model)
  - [L3VPN Service Model](#l3vpn-service-model)
  - [NSO Netsims](#nso-netsims)
- [Provisioning L2VPN service via Service Catalog](#provisioning-l2vpn-service-via-service-catalog)
- [Provisioning L3VPN service via Service Catalog](#provisioning-l3vpn-service-via-service-catalog)
- [Running workflows via Postman](#running-workflows-via-postman)
- [Uninstall](#uninstall)
- [FAQ](#faq)

## Intro

This artifact will demo Itential platform capabilities for handling and managing L2VPN (Layer 2 Virtual Private Network) and L3VPN (Layer 3 Virtual Private Network) services.

<!-- ![Create L3 Service](https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/L3Workflow.png) -->
<table><tr><td>
	<img src="https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/L3Workflow.png" alt="Create L3 Service" width="800px">
</td></tr></table>

The components used in this artifact are:

* L2VPN Service Model: An NSO package that contain multiple files that model an L2VPN service. This is a demo service model that represent the minimum L2VPN service configurations. The service package runs on the Cisco NSO platform and will be managed from the user interface by Itential Platform.
* L3VPN Service Model: An NSO package that contain multiple files that model an L3VPN service. This is a demo service model that represent the minimum L3VPN service configurations. The service package runs on the Cisco NSO platform and will be managed from the user interface by Itential Platform.
* Workflows: Workflows are important components in the Itential platform that enable engineers to design complex network services with no to low code environment. The files included in this artifact represent the logic and flow required to provision L2VPN and L3VPN services.
* Command Templates: Command templates enable engineers to run commands directly on devices. These commands can represent pre-checks that run before provisioning a service, and post-checks to run after service configuration. The commands included in this artifact are generic commands that show device configurations before a service is configured, and the difference between configurations after a service is configured.
* Forms: Form Builder is an application in the Itential Platform. You can create custom forms to take input from users and pass it along to a workflow. The forms can be created manually or automatically by parsing YANG files from the Service Model package. The ability to validate inputs, set certain formats, or behave in certain conditions is provided. The forms included in this artifact are forms that require minimum user input to configure a service.
* Service Catalog: An Itential Platform application that integrates Forms and Workflows together. The Service Catalog items included in this artifact map the service creation forms to the workflows that provision and configure the service.

## Supported device types

* Cisco IOS
* Cisco IOS-XR

## Test environment

This artifact has been tested on:

* Itential Platform: 2019.1
* NSO Ver: 4.5.3
* NEDs Ver:
  * cisco-ios: 6.0.9
  * cisco-xr: 7.1
  * itential-tools: 1.14.2
* Mongo: v3.4.17
* Node JS: v8.11.2
* Redis: 4.0.1
* Python: 2.7.15
* Java: 1.8.0

## Installation

Install this artifact using App Artifacts. Additionally, there are a few NSO packages to install manually.

### L2VPN Service Model

* Copy the service model folder to the NSO packages folder Ex: `cp -Rv <!--PWD-->/l2-l3-vpn/package/assets/service-models/IAP\ Artifact-l2vpn /var/opt/ncs/packages/`
* Navigate to the src folder inside the copied service model directory: `cd IAP\ Artifact-l2vpn/src`
* Compile the service mode. Run `make clean all`
* Log into NSO cli: `ncs_cli -u admin`
* Load the packages: `request packages reload`
* Confirm the operation status of the package is up: `show packages package oper-status`
* Ex. output:
```
admin@ncs> show packages package oper-status 
                                                                                       PACKAGE                
                        PROGRAM                                                        META     FILE          
                        CODE     JAVA           BAD NCS  PACKAGE  PACKAGE  CIRCULAR    DATA     LOAD   ERROR  
NAME                UP  ERROR    UNINITIALIZED  VERSION  NAME     VERSION  DEPENDENCY  ERROR    ERROR  INFO   
--------------------------------------------------------------------------------------------------------------
IAP-Artifact-l2vpn  X   -        -              -        -        -        -           -        -      -      
Itential Tools      X   -        -              -        -        -        -           -        -      -      
cisco-ios           X   -        -              -        -        -        -           -        -      -      
cisco-iosxr         X   -        -              -        -        -        -           -        -      -      

[ok][2019-06-04 14:12:05]
admin@ncs> 

```

### L3VPN Service Model

* Copy the service model folder `IAP Artifact-l3vpn` to NSO packages folder normally located at `/var/opt/ncs/packages`
* Navigate to the src folder inside the service model directory: `cd IAP Artifact-l3vpn/src`
* Compile the service mode. Run: `make clean all`
* Login to NSO cli: `ncs_cli -u admin`
* Load the packages: `request packages reload`
* The package reload summary may indicate a missing python dependency Ex. `admin@ncs> *** ALARM package-load-failure: [ImportError: No module named netaddr]`. To resolve this issue, `pip install netaddr`, and perform a package reload once again
* Confirm the operation status of the package is up: `show packages package oper-status`
* Ex. output:
```
admin@ncs> show packages package oper-status 
                                                                                       PACKAGE                
                        PROGRAM                                                        META     FILE          
                        CODE     JAVA           BAD NCS  PACKAGE  PACKAGE  CIRCULAR    DATA     LOAD   ERROR  
NAME                UP  ERROR    UNINITIALIZED  VERSION  NAME     VERSION  DEPENDENCY  ERROR    ERROR  INFO   
--------------------------------------------------------------------------------------------------------------
IAP-Artifact-l2vpn  X   -        -              -        -        -        -           -        -      -      
IAP-Artifact-l3vpn  X   -        -              -        -        -        -           -        -      -      
Itential Tools      X   -        -              -        -        -        -           -        -      -      
cisco-ios           X   -        -              -        -        -        -           -        -      -      
cisco-iosxr         X   -        -              -        -        -        -           -        -      -      

[ok][2019-06-04 14:12:05]
admin@ncs> 
```

### NSO Netsims

This artifact requires Cisco IOS and IOSXR devices to run. `IOS and IOSXR will be used with the L3VPN` service. `IOSXR will be used with the L2VPN service`. This step will guide you through building the netsim devices used in running this artifact. We suggest running this artifact for the first time on blank netsim devices, but using real lab devices is also possible.

* Navigate to your nso run directory: normally `cd /var/opt/ncs/`
* Create a netsims network and add the number of devices required with the default name: `ncs-netsim create-network packages/cisco-ios 2 ios`. This will create a network with two virtual ios devices named ios0 and ios1.
* Add additional devices to the network: `ncs-netsim add-to-network packages/cisco-iosxr 2 iosxr`. This will add two virtual iosxr devices to the netsim network.
* Start the netsim devices: `ncs-netsim start`
* Export the netsim devices settings to load in NSO: `ncs-netsim ncs-xml-init> load.xml`
* Login to nso cli: `ncs_cli -u admin`
* Switch to configurations mode: `config`
* Load the XML settings file to the devices: `load merge load.xml`
* Commit with the dry run option to validate devices information and authgroups: `commit dry-run outformat native`
* If information and authgroups are correct, commit: `commit`
* Fetch the devices' ssh keys: `request devices fetch-ssh-host-keys`
* Connect to the devices: `request devices connect`
* Sync from the devices: `request devices sync-from`

## Provisioning L2VPN service via Service Catalog

* Login to the Itential Automation Platform
* Go to **Service Catalog** to provision a service. Click IAP Artifacts L3VPN Create Service.
  <!-- ![Service Catalog](https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/serviceCatalog.png) -->
  <table><tr><td>
    <img src="https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/serviceCatalog.png" alt="Service Catalog" width="800px">
  </td></tr></table>
* The L2VPN Service Model form is pre-populated with default values. It only requires the name of the device (iosxr). Change the other default values, as needed. 
  *  **To fill the PE information, click the site row. This opens another window. At the top of the form there is a breadcrumb trail that allows you to return to the previous screen in the form**.
  <!-- ![Create L2 Service](https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL2.png) -->
  <table><tr><td>
    <img src="https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL2.png" alt="Create L2 Service" width="800px">
  </td></tr></table>
* Go to Active Jobs to monitor and complete the workflow.
* Please note: there is a manual step at the end of the workflow that offers the option to rollback when the automation completes.

## Provisioning L3VPN service via Service Catalog

* Login to the Itential Automation Platform
* Go to **Service Catalog** to provision a service. L3VPN-Create-Service.
* The L3VPN Service Model form is pre-populated with default values. It only requires the name of the CE device (ios) and PE device (iosxr). Change the other default values, as needed.
  * **To fill the PE information click the site row. This opens another window. At the top of the form there is a breadcrumb trail that allow you to return to the previous screen in the form**.
  <!-- ![Create L3 Service](https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL3-1.png) -->
  <table><tr><td>
    <img src="https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL3-1.png" alt="Create L3 Service" width="800px">
  </td></tr></table>
  <!-- ![Create L3 Service](https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL3-2.png) -->
  <table><tr><td>
    <img src="https://gitlab.com/itentialopensource/pre-built-automations/l2-l3-vpn/raw/master/img/createL3-2.png" alt="Create L3 Service" width="800px">
  </td></tr></table>
* Go to Active Jobs to monitor and complete the workflow.
* Please note: there is a manual step at the end of the workflow that offers the option to rollback when the automation completes.

## Running workflows directly

* Login to the Itential Automation Platform
* Navigate to Workflow-Builder, and click the start workflow button next to the L2 or L3 workflow.
* once requested, fill the job variables with values. 
* L2VPN Ex. 
```
{
	"instanceData": 
    {
      "/ncs:services/IAP-Artifact-l2vpn:l2vpn": [{
        "id": 12321,
        "bandwidth": "10",
        "pwid": "4000",
        "qos_policy": "Q-5rt-95sd",
        "location": [{
          "location": "Atlanta"
        }, {
          "location": "Dallas"
        }],
        "device": [{
          "location": "Atlanta",
          "device": "iosxr0",
          "description": "testingDescriptionSite1",
          "interface": "11",
          "svlan": "232",
          "neighbor": "2.2.2.2",
          "mtu": "2000"
        }, {
          "location": "Dallas",
          "device": "iosxr1",
          "description": "testingDescriptionSite2",
          "interface": "33",
          "svlan": "45",
          "neighbor": "2.2.2.1",
          "mtu": "2000"
        }]
      }]
    }
}
``` 
* L3VPN Ex.
```
{
	"instanceData": 
    {
      "/IAP-Artifact-l3vpn:l3vpn": [{
        "vpn-id": "123456",
        "vpn-name": "testingName",
        "description": "testingDescription",
        "site": [{
          "site-id": "1",
          "ce": "ios0",
          "site-description": "testingSiteDescription",
          "lan-link": [{
            "lan-interface-name": "0/1",
            "lan-ip": "192.0.2.0/21",
            "lan-description": "testingLanDescription"
          }],
          "wan-link": [{
            "pe": "iosxr0",
            "pe-interface-name": "0/0/0/1",
            "vlan": "123",
            "pe-as-num": "321",
            "pe-router-ip": "192.0.2.0/21",
            "pe-ip": "192.0.2.0/21",
            "ce-wan-interface-name": "0/0",
            "ce-wan-ip": "192.0.2.0/21",
            "wan-description": "testingWanDescription"
          }]
        }]
      }]
    }
}
``` 
* Go to Active Jobs to confirm the data, monitor the job, check the pre-checks, dry run, and post-checks.

## Running workflows via Postman

* Similarly, the service can also be initiated using a REST call. To test, run a post request using Postman or any other http request application.
* L2VPN Ex.
```
POST: workflow_engine/startJob/:workflow

Parameters:
workflow	 string	   Workflow name (URL Parameter)
description	 string	   Description for the job (Body Parameter)
variables	 object	   Job's variables (Body Parameter)

Sample Request:
curl -X POST \
  --url 'https://{{host}}:{{port}}/workflow_engine/startJob/IAP Artifacts L2VPN Multisite Create Workflow?token={{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "testingL2VPN",
  "variables": {
    "instance": { 
      "/ncs:services/IAP-Artifact-l2vpn:l2vpn": [{
          "id": 12321,
          "bandwidth": "10",
          "pwid": "4000",
          "qos_policy": "Q-5rt-95sd",
          "location": [{
            "location": "Atlanta"
          }, {
            "location": "Dallas"
          }],
          "device": [{
            "location": "Atlanta",
            "device": "iosxr0",
            "description": "testingDescriptionSite1",
            "interface": "11",
            "svlan": "232",
            "neighbor": "2.2.2.2",
            "mtu": "2000"
          }, {
            "location": "Dallas",
            "device": "iosxr1",
            "description": "testingDescriptionSite2",
            "interface": "33",
            "svlan": "45",
            "neighbor": "2.2.2.1",
            "mtu": "2000"
          }]
        }]
      }
    }
  }`
```
* L3VPN Ex.
```
POST: workflow_engine/startJob/:workflow

Parameters:
workflow	 string	   Workflow name (URL Parameter)
description	 string	   Description for the job (Body Parameter)
variables	 object	   Job's variables (Body Parameter)

Sample Request:
curl -X POST \
  --url 'https://{{host}}:{{port}}/workflow_engine/startJob/IAP Artifacts L3VPN Multisite Create Workflow?token={{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "testingL3VPN",
  "variables": {
    "instance": {
      "/IAP-Artifact-l3vpn:l3vpn": [{
        "vpn-id": "123456",
        "vpn-name": "testingName",
        "description": "testingDescription",
        "site": [{
          "site-id": "1",
          "ce": "ios0",
          "site-description": "testingSiteDescription",
          "lan-link": [{
            "lan-interface-name": "0/1",
            "lan-ip": "192.0.2.0/21",
            "lan-description": "testingLanDescription"
          }],
          "wan-link": [{
            "pe": "iosxr0",
            "pe-interface-name": "0/0/0/1",
            "vlan": "123",
            "pe-as-num": "321",
            "pe-router-ip": "192.0.2.0/21",
            "pe-ip": "192.0.2.0/21",
            "ce-wan-interface-name": "0/0",
            "ce-wan-ip": "192.0.2.0/21",
            "wan-description": "testingWanDescription"
          }]
        }]
      }]
    }
  }
  }`
```

## Uninstall

To remove the artifact:
* Uninstall using App Artifacts
* Remove the service models form: `/var/opt/ncs/packages`
* Login to NSO cli: `ncs_cli -u amdin`
* Reload the packages: `request packages reload`
* Confirm the packages have been removed: `show packages package oper-status`

## FAQ

* In certain settings, NSO may require an extra Python library called `netaddr` in order to load the attached service models. This library can be installed via the `pip` command Ex. `pip install netaddr`
* In certain scenarios, Service Catalog services or manual workflow tasks are not visible to the current user; To fix this issue please follow the steps:
  * If the current user installed the artifact: try log out and re-login to the platform.
  * Make sure that the current user or its group is associated with the **Itential Artifact** group via the SETTINGS > AUTHORIZATION menu. 
  * If current user doesn't have access to the SETTING menu, please contact your platform-admin