CSO HTTP API Reference and Developer Guide

Juniper Networks, Inc.
1133 Innovation Way Sunnyvale, California 94089 USA
408-745-2000
www.juniper.net

Copyright © 2019, Juniper Networks, Inc. All rights reserved.

Juniper Networks, the Juniper Networks logo, Juniper, and Junos are registered trademarks of Juniper Networks, Inc. and/or its affiliates in the United States and other countries. All other trademarks may be property of their respective owners.
Juniper Networks assumes no responsibility for any inaccuracies in this document. Juniper Networks reserves the right to change, modify, transfer, or otherwise revise this publication without notice.

The information in this document is current as of the date on the title page.

YEAR 2000 NOTICE

Juniper Networks hardware and software products are Year 2000 compliant. Junos OS has no known time-related limitations through the year 2038. However, the NTP application is known to have some difficulty in the year 2036.

END USER LICENSE AGREEMENT

The Juniper Networks product that is the subject of this technical documentation consists of (or is intended for use with) Juniper Networks software. Use of such software is subject to the terms and conditions of the End User License Agreement (“EULA”) posted at http://www.juniper.net/support/eula.html. By downloading, installing or using such software, you agree to the terms and conditions of that EULA.

1. Introduction

Juniper® Contrail® Service Orchestration and Network Service Controller APIs offer the same capabilities that are available through the Contrail Service Orchestration (CSO) GUI.

This document is intended for application developers, software developers, and system administrators using CSO APIs to orchestrate processes for developing portals, applications, and automation.

Contrail Service Orchestration includes two key components: the Network Service Orchestrator and the Network Service Controller (NSC). Distributed deployments handle service orchestration using the CSO Network Service Controller (NSC). The NSC is a distributed domain controller that manages customer premises equipment (CPE) devices at multiple locations for enterprise customers.

The following CSO components connect to the CSO Network Service Orchestrator through the CSO’s RESTful APIs:

  • Administration Portal

  • Customer Portal

This document is designed to help you get started with the CSO APIs.

1.1. Before You Begin

Before you begin, you must understand the following:

  • CSO component architecture.

  • RESTful and RPC-based HTTP API architecture.

  • Message queuing and RabbitMQ message bus, to work with service assurance APIs.

  • Provisioning the virtual machines (VMs) for the CSO node or server.

  • Determining the size of the deployment.

  • IP address of the VM.

  • The fully qualified domain name (FQDN) of each Network Time Protocol (NTP) server.

  • Single sign-on for Administrator Portal.

  • Using transport layer security (TLS) to encrypt data.

  • Using the OpenStack Keystone authentication service or an external Keystone service for authentication of CSO operations.

  • IP addresses and default values of the microservices in the central region and in each regional region.

For more information, see Before You Begin.

The following guides provide information on the CSO installation, upgrade, and deployment:

1.3. Understanding REST and RPC for HTTP APIs

The CSO HTTP APIs are available through endpoints to which you can send HTTP requests. For each operation that maps to a remote procedure call (RPC), the request pattern is as follows:

  • HTTP-method: Specifies the type of operation. The methods can be: GET, PUT, POST, or DELETE.

  • Body: Includes the JavaScript Object Notation (JSON) object with "input" as root.

  • Response: Begins with the parent parameter "output".

The following sample request illustrates the pattern of an RPC request and its response:

POST /device-connectivity/disconnect-device

JSON Object Input

{
  "input" : {
    "connectionid" : "string",
    "deviceid" : "string",
    "webhook" : {
      "url" : "string"
    }
  }
}

Sample Response

{
  "output" : {
    "requestid" : "string"
  }
}

1.4. Microservice APIs

The CSO HTTP APIs are generated from a YANG model that enables descriptions of the available resources and functionality.

1.4.1. YANG Components

Each YANG file contains the following components:

  • Resources: objects

  • RPC: actions

1.4.2. Microservice YANG Example

Understanding the structure of YANG modeling files helps you use the APIs.

The following example uses "bank" as the module (object) to illustrate the YANG file structure for CSO microservices.

When using the CSO APIs, you do not use or access the YANG files directly. You work with JSON-formatted responses and send JSON-formatted request bodies with the corresponding structures.

module bank {
    yang-version 1;
    namespace "http://www.example.net/ns/bank";
    prefix "bank";

    import csp-common { prefix "csp"; }

    import ietf-yang-types {
        prefix yang;
    }

    organization "<organisation name>";
    description "bank";
    revision 2015-05-25 {
        description "Initial version";
    }

    list account {
        uses csp:entity;
        csp:vertex;
        key name;
        leaf balance {
            type uint32;
        }
        leaf first-name {
            type string;
        }
        leaf last-name {
            type string;
        }
        leaf age {
            type uint32;
        }
        leaf gender {
            type enumeration {
                enum M;
                enum F;
            }
        }
        list phone {
            csp:has-edge;
            key uuid;

            leaf uuid {
                type leafref {
                path "../../../phone/uuid";
            }
        }
    }

    list user {
        csp:ref-edge;
        key uuid;

        leaf uuid {
            type leafref {
                path "../../../user/uuid";
            }
        }
    }

    container credit {
        uses credit-info;
    }
}

grouping credit-info {
    leaf credit_name {type string;}
    leaf credit_score {type uint32;}
    leaf current_credit_cards {type uint32;}
    anyxml data {
        description "test";
    }
}

list user {
     description "A list of users in the system.";
     uses csp:entity;

     ordered-by user;
     config true;
     key "name";

     leaf user-type {
         type string;
     }
     leaf full-name {
         type string;
     }
 }

rpc transfer {
    description "Synchronize service instance with JSM.";
    input {

        leaf accountid {
           type yang:uuid;
        }

        leaf amount {
           type uint32;
        }
        container schedule {
            leaf date {type string;}
            leaf bydate {type string;}
            leaf recurring {type boolean;}
        }
    }
    output {
        leaf status {
            type enumeration {
                enum success;
                //transfer is successful
                enum incomplete_funds;
                //not enough funds for transfer
                enum overdraft;
                //overdraft
            }

        }
    }
}

rpc deposit {
    description "Deposits a credit to the account.";
    input {
        leaf accountid {
           type yang:uuid;
        }
        leaf amount {
           type uint32;
        }
    }

    output {
        leaf status {
           type string;
        }
        leaf transactionid {
            type yang:uuid;
        }
        leaf current_balance {
            type uint32;
        }
    }

}
}

1.4.3. Obtaining Component Information

When you send a valid GET request along with the authentication token to the following CSO services, the response provides information about the following services:

  • tssm: Tenant, site, and service management

  • topology-service: Topology services

  • activation-service-central: Activation Service (Central)

  • cslm: Certificate Management

  • cms-central: Configuration Management Service (Central)

  • data-view-central: Data View (Central)

  • dms-central: Device Management Service (Central)

  • iamsvc-noauth: IAM Utilities

  • iamsvc: Identity and Authorization Management

  • ims-central: Image Management Service (Central)

  • policy-mgmt: Intent-based Policy Management

  • inv-central: Inventory Management (Central)

  • job-service: Job Service

  • pslam: Policy and SLA Management Service

  • sd: Security Management

  • appvisibility: Security Management - Application Statistics

  • ecm: Security Management - Events

  • seci: Security Management - Reports

  • shared-object: Shared Object

  • signature-manager: Signature Manager

  • fmpm-provider: Alerts

Table 1 provides information about the different URIs and the services they provide:

Table 1. Component Information
URI Description

/tssm/customer

Lists all customers in the system

/tssm/site

Lists all sites in the system

/tssm/nfv-service-profile

Lists all service profiles in the system

/tssm/nfv-service-instance

Lists all service instances in the system

/topology-service/pop

Lists all POPs onboarded by the provider

Sample response for request /tssm/customer

{
    "customer": [
        {
            "fq_name": ["default-domain", "Customer-VJ", "Customer-VJ"],
            "uuid": "dc3ffc30-1b16-479d-959e-86a0ac9fc9bc",
            "uri": "/tssm/customer/dc3ffc30-1b16-479d-959e-86a0ac9fc9bc"
        }
    ],
    "total": 1
}

1.4.4. Obtaining Item Information

You can obtain information about specific objects, if you have a unique object identifier.
To obtain customer details associated with the specified UUID, use the following request:

/tssm/customer/dc3ffc30-1b16-479d-959e-86a0ac9fc9bc

To obtain customer details associated with the specified fully qualified name, use the following request:

/tssm/customer/dc3ffc30-1b16-479d-959e-86a0ac9fc9bc?detail=true

Sample Response

{
    "customer": {
    "tenant_type": "small",
        "parent_uuid": "88f5fb2d-7dd7-412c-afa4-0b1a1ef980ef",260
        "parent_type": "project",
        "tenantid": "88f5fb2d7dd7412cafa40b1a1ef980ef",
        "tenant_existed": "created",
        "display_name": "Customer-VJ",
        "name": "Customer-VJ",
        "fq_name": [
            "default-domain",
            "Customer-VJ",
            "Customer-VJ"
        ],
        "uuid": "dc3ffc30-1b16-479d-959e-86a0ac9fc9bc",
        "vpn_id": "6f880de0-930a-43f7-aeb1-5bd03a37da8d",
        "uri": "/tssm/customer/dc3ffc30-1b16-479d-959e-86a0ac9fc9bc",
        "networks": {
            "network": [
                {
                    "network_name": "Customer-VJ-l3vpn_l3vpn",
                    "vpn_id": "6f880de0-930a-43f7-aeb1-5bd03a37da8d"
                }
            ]
    },
        "deployment_scenario": "managed_wan",
        "parent_uri": "/tssm/project/88f5fb2d-7dd7-412c-afa4-0b1a1ef980ef"
    }
}

2. CSO and NSC

The API examples provided in this chapter are meant for illustrative purpose only. For more information about the specific APIs, see Chapter 7 - API Reference

Juniper Contrail Service Orchestration (CSO) is a product that is designed to help in the automation of distributed CPE domain as well as the ability to automate centralized provisioning of network services in a data center. CSO is a multitenant solution. It provides the ability to define a tenant topology, add sites to or delete sites from this topology, enable devices to be brought up automatically at the customer site, set up network connections defined in the topology, enable end-user configuration of CPE devices, and monitor devices and link status.

The Network Service Controller (NSC) is a CSO component that provides controller functionality of CSO except for the portals and design tools. The NSC is accessed mainly through APIs. NSC APIs enable third-party orchestrators to build customized portals on top of CSO. Both the CSO and NSC are managed through the same set of APIs.

This document provides an overview of the CSO architecture and the network model used for defining tenant topology, workflows needed to manage a distributed enterprise domain, API description for various workflow operations, and JSON input and output for the APIs.

CSO offers a number of customization possibilities for supporting various devices and connectivity options. Customization is expected to be performed by the Juniper Professional Services team or Juniper Networks-certified system integrators.

Figure 1 provides an overview of the CSO and NSC workflow.

on_and_off_premises
Figure 1. Network Service Controller Workflow

CSO can orchestrate virtualized network functions (VNFs) for both centralized and distributed domains. CSO manages distributed domains by using NSC APIs. The CSO and NSC use APIs to integrate with third-party orchestrators.

If a domain orchestrator uses the domain controller functions of NSC, the following functions are automatically handled by the NSC:

  • Topology definition of where an NFX device is placed

  • Zero Touch Provisioning (ZTP), of the CPE device at the customer premises

  • Device-initiated connection (NFX and VNFs)

  • Device management

  • Device network connectivity management

  • Device element management system (EMS) operations

  • Higher-level APIs to instantiate network service chains including configuring, starting, and stopping network services.

  • Monitoring device and connectivity functions for FMPM purposes.

  • Monitoring VNFs for FMPM purposes

2.1. API Basics

This section provides information about the API basics.

2.1.1. CSO Services REST Interface Architecture

CSO uses microservice architecture. A microservice has YANG object model definition. A microservice exposes its functionality through an HTTP interface:

  • Create, read, update, and delete (CRUD) operation on objects.

  • RPC actions for complex actions such as creating a tenant or configuring a site.

  • Notifications published on RabbitMQ when a certain condition is met.

Each microservice is exposed in a separate HTTP namespace. The generic URL to read an object is:

https://ip-address/namespace/object-type[/object-id]

Usually tenant, site and service management (TSSM) is the most common microservice that is used for REST APIs.

Example
The API to read the details of a specific customer:

https://ip-address/tssm/customer/<customer object uuid>

2.1.2. API Considerations for Performing RPC Operations

To perform RPC operations, send a POST request (with auth-token) to the API server.

Example

An API request to the TSSM microservice along with JSON code in the body that describes the tenant, using two JSON objects for tenant identification and topology type, respectively. The JSON body can contain as many child JSON objects, which describe sites for the tenant, as are needed.

/<CSO_Central_MS_ip>/tssm/onboard-tenant

HTTP Headers:

Key Value

Content-Type

application/json

X-Auth-Token

token

2.1.3. Authentication Using Keystone

Each API request must contain a valid authentication token (auth-token).
To obtain an authentication token, send a GET request with the following JSON-formatted payload:

http://<ip-address-of-Keystone-service>:5000/v3/auth/tokens

Sample Request

{
    "auth": {
        "scope": {
            "project": {
                "domain": {
                    "id": "<domain-id>"
            },
        "name": "<name>"
        }
    },
    "identity": {
        "password": {
            "user": {
                "domain": {
                    "id": "<domain-id>"
                },
            "password": "<password>",
            "name": "<name>"
        }
    },
    "methods": [
        "password"
    ]
  }
 }
}

A successful authentication request results in a response containing a response header with an alphanumeric value for the key '::X-Subject-Token::'. The value returned is supplied in all subsequent request headers until the token expires. It is used to authenticate the requests.

2.1.4. Monitoring Long-Running Jobs

Most of the API calls are asynchronous. The API calls returns a job ID. The northbound system is expected to monitor the job for completion status.

To monitor a long-running job, set up polling using GET requests with authentication tokens to your CSO server using the job-ID, and check for, the "status", "success", and "complete"* fields.

Send a GET request with authentication token to the CSO server:

/<csp-ms-vm>/job-service/job/<job-id>

The response contains information about the job, including start time, domain, job ID, type, and other data as shown in the following example.

Sample Response

{
 "job":
   {
      "status": "success",
      "start_time": 1471656407,
      "job_type": "csp.tssm_onboard",
      "results": "complete",
      "name": "onboard_walgreen101_csp.tssm_onboard_1471656407.25",
      "fq_name": ["default-domain",
                  "default-project",
                  "onboard_walgreen101_csp.tssm_onboard_1471656407.25"
                  ],
      "uuid": "<job-id>",
      "uri": "/job-service/job/<job-id>"
   }
}

2.1.5. API Categories

CSO, along with its NSC component provides the ability to define a tenant topology, add sites to, or delete sites from this topology, enable devices to be brought up automatically at the customer site, set up network connections defined in the topology, enable end-user configuration of CPE devices, and monitor device and link status.

Almost all of the CSO and NSC functionality is exposed through REST APIs. External applications can interface with CSO and NSC through these APIs.

Table 2 provides information about the categories of the exposed APIs:

Table 2. CSO and NSC API Categories
API Description

Catalog management

Manage network service descriptors and VNFs

VIM/POP management

Create define and manage VIM and POP data centers

Topology management

Insert and manage end-to-end CPE service topology (logical)

Site/customer creation

Manage customer or site objects and associate them with service topology nodes

Network design APIs

Define virtualized services and service chains

Site activation

Notify vCPE and uCPE device deployment topology and service placement

Identity management

Manage Identity for both enterprise and service provider users

Bootstrap service

Configure and manage device activation service

Device configuration

Define and manage the base configuration of VNF

Service placement/instantiation

Position and manage service chains in the customer topology

Device and service monitoring

Monitor the status of device network services and services topology

Root cause analysis/Troubleshooting

Trace and correlate between events alarms and logs

Zero touch and device management

Activate provision and manage NFX

Image management

Manage NFX device images

SD-WAN

Provision links for auto-VPN Discover VPN and distributed routing

Abstracted routing

Create Layer 2 and Layer 3 service chains

2.2. CSO and NSC API Background Information

This section provides background information on the CSO and NSC APIs.

2.2.1. Enterprise Networking Model

Figure 2 illustrates the elements that constitute an enterprise network and how they communicate with each other. The elements represent the automation points in the network. The network services are attached or configured as part of the solution orchestration to form the automation points.

nsc_topology
Figure 2. Enterprise Networking Topology

2.2.2. Site Property Hierarchy

The elements in the enterprise topology represent the customer sites based on their location, role, and management properties that is controlled by the NSC as shown in figure 3:

site_property_hierarchy
Figure 3. NSC Site Property Hierarchy

The following are the main elements of the enterprise networking topology:

  • On-premise spoke represents an automation endpoint that is part of customer premises equipment at some physical location such as a branch office or point-of-sale location. Typically, the on-premises spoke sites are connected using overlay connections to all hub sites.

  • On-premise hub represents an automation endpoint that is part of customer premises equipment at headquarter or the main branch office, and acts as a hub for overlay connections for many spoke devices.

  • Cloud spoke (AWS) represents an automation endpoint that is part of a customer’s virtual path connection (VPC) in the AWS cloud. Typically, the cloud spoke sites are connected using overlay connections to cloud hub sites.

  • Cloud hub (POP) represents an automation endpoint that is part of a data center of POP location, and acts as a hub for overlay connections from many cloud spoke devices. Cloud hubs are usually logical entities in a multitenant device (cloud hub device).

2.3. Enterprise Object Relationship

Enterprise Objects provides tools and frameworks for object-relational mapping. The enterprise objects consist of the following components:

  • Tenant – High-level object describing a tenant.

  • Site group – Object describing a group of sites. This object is used to group sites for ease of policy application.

  • Site – Represents a node location in the enterprise network.

  • Intent policy – Represents an enterprise-level service-level agreement (SLA) or security policy.

  • Department – Represents an enterprise-wide object used in intent policies. One or more sites can have references to this object.

  • LAN segment – Represents a VLAN, port group, or an IP prefix in the CPE device. When a LAN segment refers to its department, any intent policy at department level is moved into site-specific policy.

  • VPN – Represents a network segment in the enterprise. Network segmentation for a tenant can be configured in the following methods:

  • One department – One VPN. Each VPN represents a network segment in the enterprise.

  • All departments in one VPN - The enterprise has no network segmentation and the enterprise network is part of only one VPN.

  • Device – Represents the device at the CPE site.

  • Device template – Represents all the workflow descriptions for automating the device operations including zero-touch provisioning, VNF management, and device Return Material Authorization (RMA).

  • Configuration template – Represents the configuration templates used in various device workflows.

Figure 4 presents the relationship between the various enterprise objects and highlights the relationship between the various enterprise objects.

enterprise_object_relationship
Figure 4. Enterprise Object Relationship

Figure 5 provides information on the enterprise object model.

enterprise_object_model
Figure 5. Enterprise Object Model

2.4. Role-Based Access Control

A role defines permissions required by users to perform a set of tasks. The CSO administrator can assign users to one or more roles depending on the tasks that the user is expected to perform. User roles enable you to classify users based on the privileges to perform tasks on CSO objects. Roles assigned to a user determine the tasks and actions that the user can perform.

You can perform the following operations by using the role-based access control (RBAC) APIs:

For more information about the different tasks, payload, and response samples see Identity and Authorization Management

2.4.1. Creating a User with One Custom Service Provider Role

To create a user with one custom service provider (SP) role, send a POST request with the following JSON-formatted payload:

/iamsvc/create-user

JSON Object Input

{
   "input":{
      "name":"customUserOneSProle@mail.com",
      "project_role":[
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"8d04ea55-6d5f-45fe-ae1b-8e7defcff225"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"customUserOneSProle"
         },
         {
            "name":"last_name",
            "str_value":"customUserOneSProle"
         }
      ],
      "generate_password":true
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid":"6174a1d8-204a-47fd-b8b5-209c7705da49",
      "details":"new_user"
   }
}

2.4.2. Creating a User with Two Custom Service Provider Roles

To create a user with two custom SP roles at the SP level, send a POST request with the following JSON-formatted payload:

/iamsvc/create-user

JSON Object Input

{
   "input":{
      "name":"customUserTwoSProles@mail.com",
      "project_role":[
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"8d04ea55-6d5f-45fe-ae1b-8e7defcff225"
         },
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"50b0d647-89e8-4d1b-b7b0-397d3ba55e06"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"customUserTwoSProles"
         },
         {
            "name":"last_name",
            "str_value":"customUserTwoSProles"
         }
      ],
      "generate_password":true
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid":"6174a1d8-204a-47fd-b8b5-209c7705da49",
      "details":"new_user"
   }
}

2.4.3. Creating a User with One Tenant Role and One Service Provider Role at the Service Provider Level

To create a user with one tenant role and one SP role at the SP level, send a POST request with the following JSON-formatted payload:

/iamsvc/create-user

JSON Object Input

{
   "input":{
      "name":"customUserOneSProleOneTenantRole@mail.com",
      "project_role":[
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"8d04ea55-6d5f-45fe-ae1b-8e7defcff225"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"customUserOneSProleOneTenantRole"
         },
         {
            "name":"last_name",
            "str_value":"customUserOneSProleOneTenantRole"
         }
      ],
      "generate_password":true,
      "project_group_role":[
         {
            "project_group_id":"d3d553b6-1c55-49ee-b255-11ccff028305",
            "role_id":"6f5f91e2-a733-4feb-9775-6b4db3baa6b9"
         }
      ]
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid":"6174a1d8-204a-47fd-b8b5-209c7705da49",
      "details":"new_user"
   }
}

2.4.4. Creating a User with One Tenant Role at the Tenant Level

To create a user with one tenant role at the tenant level, send a POST request with the following JSON-formatted payload:

/iamsvc/create-user

JSON Object Input

{
   "input":{
      "name":"tenantUserOneTenantRole@mail.com",
      "project_role":[
         {
            "project_id":"95058babb1254382bdab758737262aeb",
            "role_id":"6f5f91e2-a733-4feb-9775-6b4db3baa6b9"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"tenantUserOneTenantRole"
         },
         {
            "name":"last_name",
            "str_value":"tenantUserOneTenantRole"
         }
      ],
      "generate_password":true
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid":"6174a1d8-204a-47fd-b8b5-209c7705da49",
      "details":"new_user"
   }
}

2.4.5. Creating a User with Two Tenant Roles at the Tenant Level

To create a user with two tenant roles at the tenant level, send a POST request with the following JSON-formatted payload:

/iamsvc/create-user

JSON Object Input

{
   "input":{
      "name":"tenantUserTwoTenantRoles@mail.com",
      "project_role":[
         {
            "project_id":"95058babb1254382bdab758737262aeb",
            "role_id":"6f5f91e2-a733-4feb-9775-6b4db3baa6b9"
         },
         {
            "project_id":"95058babb1254382bdab758737262aeb",
            "role_id":"d6e984d2-a9fc-43a1-beb8-5ba6b980a02c"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"tenantUserTwoTenantRoles"
         },
         {
            "name":"last_name",
            "str_value":"tenantUserTwoTenantRoles"
         }
      ],
      "generate_password":true
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid":"6174a1d8-204a-47fd-b8b5-209c7705da49",
      "details":"new_user"
   }
}

2.4.6. Editing a User at the Tenant Level

To edit a user at the tenant level, send a POST request with the following JSON-formatted payload:

/iamsvc/edit-user

JSON Object Input

{
   "input":{
      "name":"tenantWithAdmin@mail.com",
      "project_role":[
         {
            "project_id":"95058babb1254382bdab758737262aeb",
            "role_id":"9fe2ff9e-e438-4b18-94a9-0878d3e92bab"
         },
         {
            "project_id":"95058babb1254382bdab758737262aeb",
            "role_id":"c408eca4-6b47-4c6d-8b7f-d5cb4c38bded"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"tenantWithAdminUpdated"
         },
         {
            "name":"last_name",
            "str_value":"tenantWithAdminUPdated"
         }
      ],
      "generate_password":true,
      "uuid":"9fd00b5a-fd17-4e3c-b5e4-b4bdb9cc3261"
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid": "a571aa45-9998-41ed-8277-94592a4d37f0",
      "details":
   }
}

2.4.7. Deleting a User at the Tenant Level

To delete a user at the tenant level, send a POST request with the following JSON-formatted payload:

iamsvc/delete-user-if-no-other-project

JSON Object Input

{
   "input":{
      "uuid":"9fd00b5a-fd17-4e3c-b5e4-b4bdb9cc3261"
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "details":""
   }
}

2.4.8. Deleting a User at the Service Provider Level

To delete a user at the SP level, send a POSt request with the following JSON-formatted payload:

iamsvc/delete-user-if-no-other-project

JSON Object Input

{
   "input":{
      "uuid":"5f3fe710-7a84-45ab-8ee9-9985f1af9bc7"
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "details":""
   }
}

2.4.9. Editing a User at the Service Provider Level

To edit a user on the SP level, use the following RESTful API with the JSON-formatted payload to:

  • Update the first and last names of the user.

  • Add a new SP role.

  • Add existing toles.

  • Add payload.

iamsvc/edit-user

JSON Object Input

{
   "input":{
      "name":"userMSPAdmin@mail.com",
      "project_role":[
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"a9822f8a-598a-4178-a8ee-c86e51e638cd"
         },
         {
            "project_id":"42736b9c2a1a43509730591f8f1e55af",
            "role_id":"fc44c184-a724-42e0-a90d-3324c4419ba5"
         }
      ],
      "extra":[
         {
            "name":"first_name",
            "str_value":"userMSPAdminFirst"
         },
         {
            "name":"last_name",
            "str_value":"userMSPAdminLast"
         }
      ],
      "generate_password":true,
      "project_group_role":[
         {
            "project_group_id":"d3d553b6-1c55-49ee-b255-11ccff028305",
            "role_id":"9fe2ff9e-e438-4b18-94a9-0878d3e92bab"
         }
      ],
      "uuid":"a571aa45-9998-41ed-8277-94592a4d37f0"
   }
}

Sample Response

{
   "output":{
      "status":"success",
      "uuid": "a571aa45-9998-41ed-8277-94592a4d37f0",
      "details":
   }
}

2.4.10. Creating a Service Provider Role with Multiple Capabilities

To create a service provider role at the SP level with multiple capabilities, use the following RESTful API with the JSON-formatted payload:

iamsvc/create-role

JSON Object Input

{
  "input": {
    "name": "customSProle",
       "role_scope": "SP",
       "role_type": "custom",
       "capabilities": [
              "Dashboard:R","Alert Definitions:C,R,U,D","TenantDevices:R,Reboot,PushLicense","Network Services:R,Allocate,Detach"
        ],
       "description": "description"
   }
}

Sample Response

{
  "output": {
  "status": "success",
  "uuid": "b0790ffc-99f0-47ce-b3ce-9385bc5eeeaa",
  "details": ""
  }
}

2.4.11. Creating a Tenant Role on Service Provider Level with Single Capability

To create a tenant role at the SP level with single capability, use the following RESTful API with the JSON-formatted payload:

iamsvc/create-role

JSON Object Input

{
"input": {
"name": "customEnterpriseRole",
  "role_scope":"Enterprise",
    "role_type": "custom",
    "capabilities": [
        "Dashboard:R"
      ],
    "description": "description"
  }
}

Sample Response

{
  "output": {
  "status": "success",
  "uuid": "b0790ffc-99f0-47ce-b3ce-9385bc5eeeaa",
  "details": ""
  }
}

2.4.12. Editing a Role

To edit a role, use the following RESTful API with the JSON-formatted payload:

/iamsvc/edit-role

JSON Object Input

{
    "input": {
        "uuid": "d0f1c149-05c7-4c34-8ad1-c30ef5ec6efd",
"capabilities": [
        "Roles:C,R,U,D"
      ],
      "description": "description"
}
}

Sample Response

{
  "output": {
  "status": "success",
  "details": ""
  }
}

2.4.13. Deleting a Role

To delete a role, use the following RESTful API with the JSON-formatted payload:

/iamsvc/delete-role

JSON Object Input

{
    "input": {
        "uuid": "d0f1c149-05c7-4c34-8ad1-c30ef5ec6efd"
    }
}

Sample Response

{
  "output": {
  "status": "success",
  "details": ""
  }
}

2.5. Operating Company

Contrail Service Orchestration (CSO) supports operating companies in a service provider environment. An Operating Company (OpCo) can be created under the Global Service Provider (SP). An OpCo is a region-specific service provider that can create and manage its own tenants and provide services to them. Each OpCo is a subset of the global service provider and functions as a service provider for its own tenants. Each OpCo can use a common CSO instance instead of using its own CSO installation.

You can use RESTful APIs to create or delete an operating company. Use the following APIs to perform specific tasks:

2.5.1. Creating an Operating Company

To onboard an operating company, use the following API with the JSON-formatted payload:

create-opco
{
  "input": {
    "name": "opco1",
    "use_parent_tenant_users_authentication": true,
    "use_parent_msp_users_authentication": true,
    "password_expiration_interval": 0,
    "admin_user": {
      "name": "jdoe@opco1.com",
      "role_id": [
        "b54a5139-3fbe-48e3-bee0-0a3c2f595c50",
        "9fe2ff9e-e438-4b18-94a9-0878d3e92bab"
      ],
      "first_name": "Joe",
      "last_name": "Doe"
    }
  }
}

Sample Response

{
  "output": {
    "status": "in-progress",
    "reason": null,
    "jobid": "4eb2767e-baca-4571-b943-fade665fca93"
  }
}

2.5.2. Deleting an Operating Company

To delete an operating company, use the following API with the JSON-formatted payload:

delete-opco
{
"input":{
      "name":"opco1"
}
}

Sample Response

{
  "output": {
    "status": "in-progress",
    "reason": null,
    "jobid": "af0b7efa-abf2-4583-af51-231eb8ca4543"
  }
}

2.6. Distributed Services Deployment (SD-WAN)

Distributed Service Orchestration is managed through the NSC. You can perform the following tasks by using the RESTful APIs:

  • Define tenant topologies

  • Add or delete sites to existing topologies

  • Control automatic enabling of devices at the customer site

  • Set up network connections defined in the topology

  • Enable end-user configuration of CPE devices

  • Monitor device and link status

2.6.1. Distributed Services Deployment Workflow

Figure 6 provides an overview of a typical end-to-end SD-WAN workflow that the customer administrator is expected to follow.

on_and_off_premises
Figure 6. NSC SD-WAN Workflow

An administrator can perform the following SD-WAN workflow tasks:

  • CSP Deployment workflow - Use this workflow for SD-WAN day-zero preconfiguration, such as creating pre-load device profiles, defining VPN and routing topologies, and preparing relevant configuration templates. The POP workflow also can be preloaded if the customer is a service provider.

  • Device Profile workflow - Use this workflow to load device profiles, which provide information about the device type, connectivity options for the site, and initial configuration workflow data.

  • Network Service Package workflow - Use this workflow to load the service package that are defined using designer tools and configuration templates.

  • Create Tenant workflow - Use this workflow to define tenant-specific parameters, such as topology type and deployment type.

  • Create Site workflow - Use this workflow to define site-specific parameters, connectivity plans, topology-related connectivity parameters, and activation parameters.

  • Define Policy workflow - Use this workflow to define enterprise-wide SLA and security policies.

  • Device Activation workflow - Use this workflow to initially power on the device and enter the code for activation on the portal or device console. When the device is activated, the VPN routing topologies are automatically created. Additionally, if the device (site) is part of any enterprise-wide policies, the device-specific policy rules are automatically loaded onto the device.

  • Device Management workflow - Use this workflow to monitor device status and manage Administrator Portal.

  • SLA Policy Management workflow - Use this workflow to monitor and manage SLA performance in the Administrator Portal.

  • Security Policy Management workflow - Use this workflow to monitor and manage enterprise-wide security policies in Administrator Portal.

  • Service Management workflow - Use this workflow to deploy network services on-premise or centralized services in Administrator Portal.

For all workflows, CSO FMPM subsystems continuously monitors fault and performance data and updates the monitoring dashboards. Monitoring dashboards provide visibility into the network performance, service performance, and alert performance data. The FMPM subsystem also feeds data the route manager to continuously adjust network paths to meet SLA targets.

2.6.2. API Examples: Configuring the Enterprise Network

The information provided in this section is applicable only for customer portal development using the CSO and NSC APIs. You can skip this section, if you only need to read the operational state of the system and monitor the system status.

This chapter provides describes the following tasks:

Importing a POP

To import a POP, send a POST request to your CSO server, with JSON-formatted code in the payload that describes the POP:

POST http://<CSO_Central_MS_IP>/tssm/import-pop

JSON Object Input

curl -vk -X POST -H "Cache-Control: no-cache" \
-H "X-Auth-Token: bbf35b4c222e47e2848d186c0dfe8e24" \
-H "Content-Type: application/json" \
-d '
{
  "input": {
    "pop": [
      {
        "dc_name": "${regional_name}",
        "name": "${pop_name1}",
        "address": {
          "street": "1134 Innovation Way",
          "city": "Sunnyvale",
          "state": "CA",
          "zip_code": "94089",
          "country": "USA"
        },
        "device": [
          {
            "name": "${pe_device1}",
            "device_ip": "${pe_ip_addr1}",
            "family": "${pe_family}",
            "assigned_device_profile": "${pe_device_profile}",
              "authentication": {
                "username": "${pe_username}",
                "password": "${pe_password}"
              }
            }
          }
        ]
      }
    ]
  }
}
Adding a Cloud Hub Device

The following example shows how to add a cloud hub device to the system.

To add a cloud hub device, send a POST request to the CSO server with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/configure-sites

JSON Object Input

{
    "input": {
        "tenant_name": "Color",
        "job_name_prefix": "Create-Site-for-Yelow",
        "deployment_scenario": "managed_wan_v2",
        "site": [
            {
                "site_name": "Yelow",
                "cloud_hub_site_info": {
                    "hub_device": "Yellow",
                    "wan_links": [
                        "WAN_5",
                        "WAN_2",
                        "WAN_0",
                        "WAN_1",
                        "WAN_3",
                        "lo0.0"
                    ],
                    "pop": "Nature"
                },
                "site_basic_properties": {
                    "site_address": {
                        "country": "US"
                    },
                    "site_description": "",
                    "site_role": "HUB",
                    "cloud_service": "NONE",
                    "site_type": "cloud"
                }
            }
        ]
    }
}
}
Onboarding a Tenant

Send a POST request with the authentication token to your CSO server with a JSON-formatted body that describes the tenant using a minimum of two JSON objects, one each for tenant identification and the associated topology type. The JSON body can contain as many child JSON objects as needed to describe sites for the tenant.

To onboard a tenant into the system, send a POST request with the JSON-formatted payload:

POST http://<ip-addr>/tssm/onboard-tenant

JSON Object Input

{
    "input": {
        "tenant_admin": {
            "admin_user_name": "testtenant_admin@testtenant.com",
            "last_name": "admin",
            "admin_user_password": "Juniper123!",
            "first_name": "testtenant",
            "password_expiration_interval": 0
        },
        "tenant_type": "small",
        "tenant_name": "testtenant",
        "password_expiration_radio": "never",
        "departments": [
            {
                "vpn_name": "testtenant_DefaultVPN",
                "department_name": "Default"
            }
        ],
        "deployment": "SDWAN",
        "vpn": [
            {
                "vpn_name": "testtenant_DefaultVPN"
            }
        ],
        "managed_wan_topology_v2": {}
    }
}
Adding a Department

To add a department object for a tenant, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/add-department-to-site/

JSON Object Input

{
    "input": {
        "sites": [
            "Orange"
        ],
        "departments": [
            "CompanyName-test"
        ]
    }
}
Creating a Site

The tenant administrator uses the create site API to add a site object. You need the following information in order to use this API:

  • Site name

  • Site type

  • Site role

  • Device template

  • WAN and LAN links that needs to be activated on the site devices.

To create a site object for a tenant, send a POST request with the following JSON-formatted payload:

https://central-ms-ip/tssm/create-sites

JSON Object Input

{
    "input": {
        "tenant_name": "tenant_15549507",
        "deployment_scenario": "managed_wan_v2",
        "site": [
            {
                "site_name": "s-srx-15549507",
                "site_basic_properties": {
                    "local_breakout": {},
                    "gatewaySite": false,
                    "site_type": "on_premise",
                    "cloud_service": "EDGE",
                    "site_address": {
                        "country": "US",
                        "state": "CA",
                        "street": "juniper",
                        "zip_code": "94085",
                        "city": "sunnyvale"
                    },
                    "device_redundancy": false,
                    "network_seg": false,
                    "device_template": [
                        {
                            "wan_link_info": [
                                {
                                    "wan_link_type": "Internet",
                                    "provider": "ATT",
                                    "wan_link": "WAN_0",
                                    "subscribed_bandwidth": 1000,
                                    "exclusive_for_local_breakout": false,
                                    "_sys_reserved_row": "273518d4-7c64-dc05-badd-6e681366582c",
                                    "cost": 10,
                                    "default_link": false,
                                    "local_breakout_enabled": false,
                                    "cost_currency": "USD",
                                    "preferred_breakout_link": false,
                                    "backup_link": false
                                },
                                {
                                    "wan_link_type": "Internet",
                                    "provider": "COMCAST",
                                    "wan_link": "WAN_1",
                                    "subscribed_bandwidth": 500,
                                    "exclusive_for_local_breakout": false,
                                    "_sys_reserved_row": "452d8511-c61b-0d75-3a6c-d7873c174f7a",
                                    "cost": 20,
                                    "default_link": false,
                                    "local_breakout_enabled": false,
                                    "cost_currency": "USD",
                                    "preferred_breakout_link": false,
                                    "backup_link": false
                                }
                            ],
                            "template_name": "SRX_Advanced_SDWAN_CPE_option_1",
                            "lan_segment": [
                                {
                                    "department": "D1",
                                    "dhcp": false,
                                    "ip_prefix": "10.10.10.10/24",
                                    "lan_ports": [
                                        "LAN_4"
                                    ],
                                    "lan_segment_name": "lan"
                                }
                            ],
                            "device_name": "s-srx-15549507"
                        }
                    ],
                    "0": {
                        "department": "D1",
                        "dhcp": false,
                        "ip_prefix": "10.10.10.10/24",
                        "lan_ports": [
                            "LAN_4"
                        ],
                        "lan_segment_name": "lan"
                    },
                    "site_role": "SPOKE",
                    "sla_mgmt": "COARSE",
                    "device_profile_name": "SRX as SD-WAN CPE",
                    "site_name": "s-srx-15549507",
                    "site_group": null,
                    "site_contact": {
                        "phone_number": "514325544",
                        "contact_name": "admin",
                        "email_address": "a@juniper.net"
                    },
                    "dvpn_params": {
                        "delete_dvpn_threshold": "1",
                        "create_dvpn_threshold": "5"
                    },
                    "topology": "Bandwidth Optimized"
                }
            }
        ]
    }
}
Configuring a Site

Use the Configure site API to set up the overlay connectivity to the hub and the gateway sites. Ensure that you have the service provider credentials, in order to configure a site.

To configure a site object for a tenant, send a POST request with the following JSON-formatted payload:

https://central-ms-ip/tssm/create-sites

JSON Object Input

{
    "input": {
        "tenant_name": "tenant_15549507",
        "job_name_prefix": "tenant_15549507-s-srx-15549507",
        "site": [
            {
                "on_premise_site_info": {
                    "device": [
                        {
                            "device_template": "SRX_Advanced_SDWAN_CPE_option_1",
                            "is_gateway_site": false,
                            "wan_link": [
                                {
                                    "mesh_tag": [],
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_0",
                                                "internet_gw_ip": "10.155.95.254",
                                                "peer_device": "s-hub-15549507"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/0",
                                    "used_for_oam": true,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "static_ip_assignment": {
                                        "gateway_ip": "10.155.95.254",
                                        "ip_address": "192.168.30.2/24"
                                    },
                                    "local_breakout_enabled": false,
                                    "traffic_type": "DATA_ONLY",
                                    "vpn": [
                                        {
                                            "vpn_name": "tenant_15549507_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_0",
                                    "address_assignment": "STATIC",
                                    "mesh_overlay_link_type": "GRE_IPSEC"
                                },
                                {
                                    "mesh_tag": [],
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_1",
                                                "internet_gw_ip": "10.155.95.254",
                                                "peer_device": "s-hub-15549507"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/1",
                                    "used_for_oam": false,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "static_ip_assignment": {
                                        "gateway_ip": "10.155.95.254",
                                        "ip_address": "192.168.30.3/24"
                                    },
                                    "local_breakout_enabled": false,
                                    "traffic_type": "DATA_ONLY",
                                    "vpn": [
                                        {
                                            "vpn_name": "tenant_15549507_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_1",
                                    "address_assignment": "STATIC",
                                    "mesh_overlay_link_type": "GRE_IPSEC"
                                }
                            ],
                            "device_name": "s-srx-15549507",
                            "device_family": "juniper-srx",
                            "device_details": {
                                "serial_number": "SIMSRXSPOKE15555457",
                                "activation_code": "545454"
                            },
                            "oam_traffic": {
                                "ip_prefix": "10.155.95.2/32"
                            }
                        }
                    ],
                    "hub_sites": [
                        {
                            "hub_role": "PRIMARY",
                            "hub_name": "s-hub-15549507"
                        }
                    ],
                    "region": "regional",
                    "site_role": "spoke",
                    "ha_info": {
                        "ha_topology": "STANDALONE"
                    }
                },
                "site_name": "s-srx-15549507",
                "properties": {
                    "property": [
                        {
                            "name": "site_advanced_config",
                            "value": {
                                "timezone": "Africa/Abidjan",
                                "nameserver": [
                                    "8.8.8.8"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
}
Adding a LAN Segment

To add a LAN segment at a site, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/add-delete-lan-segments/

JSON Object Input

{
    "input": {
        "devices": [
            {
                "delete_lan_segments_list": [],
                "lan_segment": [
                    {
                        "additional_config": {
                            "dhcp": {}
                        },
                        "ip_prefix": "172.27.17.1/24",
                        "lan_segment_name": "LAN-test",
                        "vlan": 17,
                        "lan_ports": [
                            "LAN_5"
                        ],
                        "department": "CompanyName-test",
                        "dhcp": false
                    }
                ],
                "device_name": "Red_CPE1"
            }
        ]
    }
}
Deleting a LAN Segment

To delete a LAN segment from a site, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/add-delete-lan-segments/

JSON Object Input

{
   "input":{
      "devices":[
         {
            "device_name":"nfx150spoke",
            "delete_lan_segments_list":[
               "lans4444",
               "ls556"
            ],
            "lan_segment":[

            ]
         }
      ]
   }
}
Activating a Spoke Device

If a spoke device is using zero touch provisioning (ZTP), use the following API to activate the device. This API is expected to be invoked by the tenant administrator. Using this API, the tenant administrator provides the serial number and activation code for the device at a site to the system. This information is used to complete the zero touch provisioning of the device and bring it up to the provisioned state.

To activate a spoke device with ZTP enabled, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/start-device-bootstrap

JSON Object Input

{"input": {
    "device_uuid": asdasdasdasdasd1234sfss,
    "authenticate_device": {
        "serial_number": ABCDEF3456,
        "activation_code": 121212
    }
}};

To activate a spoke device which does not use ZTP, instead uses an interactive bring-up workflow, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/start-device-bootstrap

JSON Object Input

{"input": {
   "device_uuid":.asadasdasdasd1234
}};
Upgrading a Site

Use the site_upgrade RESTful APIs to perform the following functions:

Analyzing the Site Upgrade

To perform an upgrade analysis for a site, send a POST request with the following JSON-formatted payload:

http://<CSO_Central_MS_ip>/tssm/analyze_site_upgrade/

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the upgrade analysis for cloud hub devices.

Sample Response

{"output": {"report": [], "job_id": "0247ceb9-b097-410f-98b1-289c5302c155", "jobid": "0247ceb9-b097-410f-98b1-289c5302c155"}}
Obtaining the Site Upgrade Analysis Report

To obtain the site upgrade analysis report, send a GET request with the following JSON-formatted payload:

/tssm/get_upgrade_analysis_report

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the site upgrade for cloud hub devices.

Sample Response

{
     output : {
                          upgrade_needed : < MANDATORY|OPTIONAL|NOT_NEEDED >,
                          upgrade_impact_checks : [
                                {
                                      check_type : IMAGE_SUPPORT
                                      message : Support for this image is deprecated
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_SERVICES
                                      message : Tunnel to Hub will be re-established
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_HUB
                                      message : Hub needs to be upgraded
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_OTHER_SITES
                                       message : Since it is a Full-Mesh topology, other sites
                                                           need to be upgraded as well,
                                       message_type : WARNING
                                },
                                {
                                       check_type : COMPATIBILITY_WITH_NEW_FEATURES,
                                       message : AppQoE, Local-breakout will not work on
                                                            this site without upgrade
                                        message_type : INFO
                                }
                          ],
                          upgrade_steps :  [
                                  {
                                      description : Upgrade Image,
                                      expected_time : 20
                                  },
                                  {
                                      description : Modify Config,
                                      expected_time : 5
                                  }
                          ]
                         },
                         upgrade_total_expected_time : 25,


                         upgrade_pre_requisites : [
                              Download JUNOS 18.2 image to CSO before proceeding with
                                 upgrade,
                        ],
                         upgrade_post_recommendations : [
                              Please upgrade other sites and hub in the topology,
                        ]


      }
}
Performing the Upgrade

To upgrade a site, send a POST request with the following JSON-formatted payload:

 http://<CSO_Central_MS_ip>/tssm/upgrade-site/

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the site upgrade for cloud hub devices.

Sample Response

{
     output : {
                          upgrade_needed : < MANDATORY|OPTIONAL|NOT_NEEDED >,
                          upgrade_impact_checks : [
                                {
                                      check_type : IMAGE_SUPPORT
                                      message : Support for this image is deprecated
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_SERVICES
                                      message : Tunnel to Hub will be re-established
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_HUB
                                      message : Hub needs to be upgraded
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_OTHER_SITES
                                       message : Since it is a Full-Mesh topology, other sites
                                                           need to be upgraded as well,
                                       message_type : WARNING
                                },
                                {
                                       check_type : COMPATIBILITY_WITH_NEW_FEATURES,
                                       message : AppQoE, Local-breakout will not work on
                                                            this site without upgrade
                                        message_type : INFO
                                }
                          ],
                          upgrade_steps :  [
                                  {
                                      description : Upgrade Image,
                                      expected_time : 20
                                  },
                                  {
                                      description : Modify Config,
                                      expected_time : 5
                                  }
                          ]
                         },
                         upgrade_total_expected_time : 25,


                         upgrade_pre_requisites : [
                              Download JUNOS 18.2 image to CSO before proceeding with
                                 upgrade,
                        ],
                         upgrade_post_recommendations : [
                              Please upgrade other sites and hub in the topology,
                        ]


      }
}
Adding On-Premise Spoke Site

To add On-premise spoke site, send a POST request with the following JSON formatted payload:

{
    "input": {
        "tenant_name": "Color",
        "deployment_scenario": "managed_wan_v2",
        "site": [
            {
                "site_name": "White",
                "site_basic_properties": {
                    "local_breakout": {
                        "enabled": false
                    },
                    "site_name": "White",
                    "sla_mgmt": "FINE",
                    "cloud_service": "EDGE",
                    "site_address": {
                        "country": "US"
                    },
                    "device_redundancy": false,
                    "network_seg": false,
                    "device_template": [
                        {
                            "wan_link_info": [
                                {
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_breakout_enabled": false,
                                    "wan_link": "WAN_2",
                                    "subscribed_bandwidth": 2,
                                    "exclusive_for_local_breakout": false,
                                    "_sys_reserved_row": "55eefda7-44b7-bfd7-5561-31ce5ec7d433",
                                    "cost": 2,
                                    "access_type": "Ethernet",
                                    "default_link": false,
                                    "provider": "a",
                                    "cost_currency": "USD",
                                    "backup_link": false
                                },
                                {
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_breakout_enabled": false,
                                    "wan_link": "WAN_3",
                                    "subscribed_bandwidth": 2,
                                    "exclusive_for_local_breakout": false,
                                    "_sys_reserved_row": "05a5c566-0497-6867-2a3c-8598db7759bf",
                                    "cost": 2,
                                    "access_type": "Ethernet",
                                    "default_link": false,
                                    "provider": "a",
                                    "cost_currency": "USD",
                                    "backup_link": false
                                }
                            ],
                            "template_name": "NFX_Advanced_SDWAN_CPE_option_1",
                            "lan_segment": [
                                {
                                    "ip_prefix": "xx.xx.xx.x/24",
                                    "lan_segment_name": "WLan",
                                    "vlan": 110,
                                    "lan_ports": [
                                        "LAN_1"
                                    ],
                                    "department": "WDept",
                                    "dhcp": false
                                }
                            ],
                            "device_name": "White"
                        }
                    ],
                    "0": {
                        "ip_prefix": "xx.xx.xx.x/24",
                        "lan_segment_name": "WLan",
                        "vlan": 110,
                        "lan_ports": [
                            "LAN_1"
                        ],
                        "department": "WDept",
                        "dhcp": false
                    },
                    "site_type": "on_premise",
                    "site_role": "SPOKE",
                    "enable_mh": true,
                    "device_profile_name": "NFX_Advanced_SDWAN_CPE_option_1",
                    "site_group": "",
                    "topology": "Full Mesh"
                }
            }
        ]
    }
}
Configuring Spoke Site

To configure a spoke site, send a POST request with the following JSON formatted payload:

{
    "input": {
        "tenant_name": "Color",
        "job_name_prefix": "Color-White",
        "site": [
            {
                "on_premise_site_info": {
                    "device": [
                        {
                            "device_template": "NFX_Advanced_SDWAN_CPE_option_1",
                            "device_details": {
                                "serial_number": "DC0416AF0057",
                                "activation_code": "545454"
                            },
                            "oam_traffic": {
                                "ip_prefix": "xx.xx.xx.x/32"
                            },
                            "wan_link": [
                                {
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_0",
                                                "internet_gw_ip": "51.51.51.254",
                                                "peer_device": "Yellow"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/8",
                                    "used_for_meshing": true,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "access_type": "Ethernet",
                                    "traffic_type": "OAM_AND_DATA",
                                    "vlan_id": 960,
                                    "local_breakout_enabled": false,
                                    "used_for_oam": true,
                                    "static_ip_assignment": {
                                        "gateway_ip": "xx.xx.xx.xxx",
                                        "ip_address": "xx.xx.xx.x/24"
                                    },
                                    "vpn": [
                                        {
                                            "vpn_name": "Color_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_2",
                                    "address_assignment": "STATIC",
                                    "connect_to_hubs": true
                                },
                                {
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_2",
                                                "internet_gw_ip": "xx.xx.xx.xxx",
                                                "peer_device": "Yellow"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/9",
                                    "used_for_meshing": true,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "access_type": "Ethernet",
                                    "traffic_type": "DATA_ONLY",
                                    "vlan_id": 970,
                                    "local_breakout_enabled": false,
                                    "used_for_oam": true,
                                    "static_ip_assignment": {
                                        "gateway_ip": "xx.xx.xx.xxx",
                                        "ip_address": "xx.xx.xx.x/24"
                                    },
                                    "vpn": [
                                        {
                                            "vpn_name": "Color_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_3",
                                    "address_assignment": "STATIC",
                                    "connect_to_hubs": true
                                }
                            ],
                            "device_name": "White"
                        }
                    ],
                    "hub_sites": [
                        {
                            "hub_role": "PRIMARY",
                            "hub_name": "Yelow"
                        }
                    ],
                    "region": "regional",
                    "site_role": "spoke",
                    "ha_info": {
                        "ha_topology": "STANDALONE"
                    }
                },
                "site_name": "White",
                "properties": {
                    "property": [
                        {
                            "name": "site_advanced_config",
                            "value": {
                                "timezone": "Asia/Calcutta",
                                "nameserver": [
                                    "10.209.194.133"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
}
Configuring Gateway Site

To configure a spoke site, send a POST request with the following JSON formatted payload:

{
    "input": {
        "tenant_name": "Color",
        "job_name_prefix": "Color-White",
        "site": [
            {
                "on_premise_site_info": {
                    "device": [
                        {
                            "device_template": "NFX_Advanced_SDWAN_CPE_option_1",
                            "device_details": {
                                "serial_number": "DC0416AF0057",
                                "activation_code": "545454"
                            },
                            "oam_traffic": {
                                "ip_prefix": "xx.xx.xx.x/32"
                            },
                            "wan_link": [
                                {
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_0",
                                                "internet_gw_ip": "51.51.51.254",
                                                "peer_device": "Yellow"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/8",
                                    "used_for_meshing": true,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "access_type": "Ethernet",
                                    "traffic_type": "OAM_AND_DATA",
                                    "vlan_id": 960,
                                    "local_breakout_enabled": false,
                                    "used_for_oam": true,
                                    "static_ip_assignment": {
                                        "gateway_ip": "xx.xx.xx.xxx",
                                        "ip_address": "xx.xx.xx.x/24"
                                    },
                                    "vpn": [
                                        {
                                            "vpn_name": "Color_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_2",
                                    "address_assignment": "STATIC",
                                    "connect_to_hubs": true
                                },
                                {
                                    "overlay_tunnel": [
                                        {
                                            "peer_info": {
                                                "interface_name": "WAN_2",
                                                "internet_gw_ip": "xx.xx.xx.xxx",
                                                "peer_device": "Yellow"
                                            },
                                            "tunnel_endpoint_role": "SPOKE",
                                            "tunnel_type": "GRE_IPSEC",
                                            "tunnel_id": 0
                                        }
                                    ],
                                    "enable_pppoe": false,
                                    "wan_link_type": "Internet",
                                    "local_interface": "ge-0/0/9",
                                    "used_for_meshing": true,
                                    "nat_info": {
                                        "nat_enabled": false
                                    },
                                    "access_type": "Ethernet",
                                    "traffic_type": "DATA_ONLY",
                                    "vlan_id": 970,
                                    "local_breakout_enabled": false,
                                    "used_for_oam": true,
                                    "static_ip_assignment": {
                                        "gateway_ip": "xx.xx.xx.xxx",
                                        "ip_address": "xx.xx.xx.x/24"
                                    },
                                    "vpn": [
                                        {
                                            "vpn_name": "Color_DefaultVPN"
                                        }
                                    ],
                                    "wan_link_name": "WAN_3",
                                    "address_assignment": "STATIC",
                                    "connect_to_hubs": true
                                }
                            ],
                            "device_name": "White"
                        }
                    ],
                    "hub_sites": [
                        {
                            "hub_role": "PRIMARY",
                            "hub_name": "Yelow"
                        }
                    ],
                    "region": "regional",
                    "site_role": "spoke",
                    "ha_info": {
                        "ha_topology": "STANDALONE"
                    }
                },
                "site_name": "White",
                "properties": {
                    "property": [
                        {
                            "name": "site_advanced_config",
                            "value": {
                                "timezone": "Asia/Calcutta",
                                "nameserver": [
                                    "10.209.194.133"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Ensure that the following attribute is set, when you configure the site workflow for a gateway site:

"on_premise_gateway": true,

Set the following properties in the on-premise-site-info, to configure gateway site using a spoke site:

                    "name": "on_premise_site_info",
                    "value": {
                        "gateway_sites": [
                            {
                                "gateway_role": "PRIMARY_GW",
                                "gateway_name": "gw1-vsrx"
                            }
                        ],
Upgrading a Site

Use the site_upgrade RESTful APIs to perform the following functions.

  • Analyze the site upgrade

  • Obtain the site upgrade analysis report

  • Perform the site upgrade

Analyzing the Site Upgrade

To perform an upgrade analysis for a site, send a POST request with the following JSON formatted payload:

tssm/analyze_site_upgrade

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the upgrade analysis for cloud hub devices.

Example Response:

{"output": {"report": [], "job_id": "0247ceb9-b097-410f-98b1-289c5302c155", "jobid": "0247ceb9-b097-410f-98b1-289c5302c155"}}
Obtaining the Site Upgrade Analysis Report

To obtain the site upgrade analysis report, send a GET request with the following JSON formatted payload:

/tssm/get_upgrade_analysis_report

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the site upgrade for cloud hub devices.

Example Response:

{
     output : {
                          upgrade_needed : < MANDATORY|OPTIONAL|NOT_NEEDED >,
                          upgrade_impact_checks : [
                                {
                                      check_type : IMAGE_SUPPORT
                                      message : Support for this image is deprecated
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_SERVICES
                                      message : Tunnel to Hub will be re-established
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_HUB
                                      message : Hub needs to be upgraded
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_OTHER_SITES
                                       message : Since it is a Full-Mesh topology, other sites
                                                           need to be upgraded as well,
                                       message_type : WARNING
                                },
                                {
                                       check_type : COMPATIBILITY_WITH_NEW_FEATURES,
                                       message : AppQoE, Local-breakout will not work on
                                                            this site without upgrade
                                        message_type : INFO
                                }
                          ],
                          upgrade_steps :  [
                                  {
                                      description : Upgrade Image,
                                      expected_time : 20
                                  },
                                  {
                                      description : Modify Config,
                                      expected_time : 5
                                  }
                          ]
                         },
                         upgrade_total_expected_time : 25,


                         upgrade_pre_requisites : [
                              Download JUNOS 18.2 image to CSO before proceeding with
                                 upgrade,
                        ],
                         upgrade_post_recommendations : [
                              Please upgrade other sites and hub in the topology,
                        ]


      }
}
Performing the Upgrade

To upgrade a site, send a POST request with the following JSON formatted payload:

<CSO_Central_MS_ip>:80/tssm/upgrade_site

You can use either the device ID or the site ID as shown:

{
    "input" : {
       "site_uuids":[
          "06883ca4-a0b5-4d19-b153-7fdb97cae3e3",
      "e90d3cd8-118b-4b69-840d-7ba2e332785c"
         ]

    }
}
or
{
    "input" : {
       "device_uuids":[
          "9191a184-abe0-498d-915e-1cac8517bfd9",
      "0d0f66fc-bea3-4870-b20a-ccde834e817a"
         ]

    }
}
You can use the device ID to perform the site upgrade for cloud hub devices.

Example Response:

{
     output : {
                          upgrade_needed : < MANDATORY|OPTIONAL|NOT_NEEDED >,
                          upgrade_impact_checks : [
                                {
                                      check_type : IMAGE_SUPPORT
                                      message : Support for this image is deprecated
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_SERVICES
                                      message : Tunnel to Hub will be re-established
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_HUB
                                      message : Hub needs to be upgraded
                                       message_type : WARNING
                                },
                                {
                                      check_type : IMPACT_ON_OTHER_SITES
                                       message : Since it is a Full-Mesh topology, other sites
                                                           need to be upgraded as well,
                                       message_type : WARNING
                                },
                                {
                                       check_type : COMPATIBILITY_WITH_NEW_FEATURES,
                                       message : AppQoE, Local-breakout will not work on
                                                            this site without upgrade
                                        message_type : INFO
                                }
                          ],
                          upgrade_steps :  [
                                  {
                                      description : Upgrade Image,
                                      expected_time : 20
                                  },
                                  {
                                      description : Modify Config,
                                      expected_time : 5
                                  }
                          ]
                         },
                         upgrade_total_expected_time : 25,


                         upgrade_pre_requisites : [
                              Download JUNOS 18.2 image to CSO before proceeding with
                                 upgrade,
                        ],
                         upgrade_post_recommendations : [
                              Please upgrade other sites and hub in the topology,
                        ]


      }
}
Removing a Site

To remove a site, send a POST request with the following JSON-formatted payload:

https/<csp-ms-vm>/tssm/remove-site

JSON Object Input

root@centralmsvm:/opt/csp/logs/tssm-api/apidump# more 20180228082750587.json
{
    "input": {
        "tenant_name": "customer1",
        "remove_tenant": false,
        "job_name_prefix": "Site Delete for customer1",
        "sites": [
            {
                "site_name": "Orange"
            }
        ],
        "forced": true
    }
}
Deleting a Tenant

To delete a tenant, send a POST request with the following JSON-formatted payload:

https/<csp-ms-vm>/tssm/remove-site

JSON Object Input

{
   "input":{
      "job_name_prefix":"Tenant Delete",
      "tenant_name":"customer-A",
      "remove_tenant":true,
      "forced":true,
      "sites":[

      ]
   }
}
Deleting a POP Object

To delete a POP object, send a POST request with the following JSON-formatted payload:

POST http://<central-ip>/topology-service/remove-pop

JSON Object Input

{
    "input": {
        "job_name_prefix": "Delete-PoP",
        "pop": [{
            "name": "pop-A"
                }]
      }
}
Shipping a Device

To ship a device, send a POST request to with the following input payload:

http://<CSO_Central_MS_ip>:80/tssm/ship-device

JSON Object Input:

curl -vk -X POST -H "Cache-Control: no-cache" \
-H "X-Auth-Token: bbf35b4c222e47e2848d186c0dfe8e24" \
-H "Content-Type: application/json" \
-d '
{
  "input": {
    "shipped_device": [
      {
        "customer_name": "${customer1}",
        "site_name": "${site1}",
        "serial_number": "${serial_number1}",
        "activation_code": "${activation_code}"
      }
    ]
  }
}

2.6.3. API Examples: Viewing the Current Operational State of the System

This section provides information about the APIs that can be used to view the current operational state of the system:

Obtaining a List of Existing Tenants and Associated UUIDs

This API uses the TSSM microservice to obtain the list of tenants.
To obtain the list of existing tenants and associated UUIDS, send a GET request with the authentication token to your API server:

GET /<csp-ms-vm>/tssm/customer

The response to the GET request provides the list of all the user names and the associated UUIDs.

Sample Response

{
      "href": "http://xx.xxx.xx.xx/tssm/customer/d1ebc753-24a8-445a-bc4b-e51a296f6c87",
      "fq_name": [
        "default-domain",
        "Tenant_VJ",
        "Tenant_VJ"
      ],
      "uuid": "d1ebc753-24a8-445a-bc4b-e51a296f6c87" #tenant uuid
}

T