CSO HTTP API Reference and Developer Guide
Copyright
Juniper Networks, Inc.
1133 Innovation Way Sunnyvale, California 94089 USA
408-745-2000
www.juniper.net
Copyright © 2021, 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.
1.2. Related Information
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-deviceJSON 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:
| 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-86a0ac9fc9bcTo obtain customer details associated with the specified fully qualified name, use the following request:
/tssm/customer/dc3ffc30-1b16-479d-959e-86a0ac9fc9bc?detail=trueSample 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.
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-tenantHTTP 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/tokensSample Request
{
"auth": {
"identity": {
"methods": ["password"],
"password": {
"user": {
"domain": {
"id": "default"
},
"name": "{{username}}",
"password": "{{password}}"
}
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "{{project}}"
}
}
}
}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_demo101_csp.tssm_onboard_1471656407.25",
"fq_name": ["default-domain",
"default-project",
"onboard_demo101_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:
| 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.
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:
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.
-
Enterprise 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 Enter hub sites.
-
Povider 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. Provider hubs are usually logical entities in a multitenant device (Provider 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.
Figure 5 provides information on the 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-userJSON 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-userJSON 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-userJSON 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-userJSON 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-userJSON 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-userJSON 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-projectJSON 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-projectJSON 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-userJSON 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-roleJSON 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-roleJSON 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-roleJSON 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-roleJSON Object Input
{
"input": {
"uuid": "d0f1c149-05c7-4c34-8ad1-c30ef5ec6efd"
}
}Sample Response
{
"output": {
"status": "success",
"details": ""
}
}2.4.14. Accepting Usage Policy
To set the usage policy acceptance information for the current user, use the following RESTful API with the JSON-formatted payload:
/iamsvc/accept-usage-policyJSON Object Input
{
leaf user_id {
type yang:uuid;
description
"UUID of the user whose usage policy information has to be set.";
}
leaf policy_url {
type yang:uuid;
description
"The url for the usage policy accepted";
}
leaf policy_id {
type yang:uuid;
description
"The id for the usage policy accepted";
}
}Sample Response
{
leaf status {
type response;
description
"Status of the RPC call.";
}
leaf details {
type string;
description
"Details of the set user usage policy details, error message if failure occurs.";
}
}
csp:doc-privacy-lvl "public";
}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.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.
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-popJSON 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 Provider Hub Device
The following example shows how to add a Provider hub device to the system.
To add a provider hub device at Global level, send a POST request to the server with the following JSON-formatted payload:
http://<CSO_Central_MS_ip>/tssm/configure-sitesJSON Object Input
{
"input": {
"tenant_name": "default-project",
"job_name_prefix": "sbmesh-hub1-cl",
"site": [{
"on_premise_site_info": {
"region": "regional",
"pop": "sbmesh-pop1",
"site_role": "HUB",
"ha_info": {
"ha_topology": "STANDALONE"
},
"device": [{
"wan_link": [{
"wan_link_type": "MPLS",
"local_interface": "ge-0/0/2",
"overlay_tunnel": [],
"static_ip_assignment": {
"ip_address": "54.1.22.1/24",
"gateway_ip": "54.1.22.254"
},
"traffic_type": "DATA_ONLY",
"wan_link_name": "WAN_2",
"address_assignment": "STATIC",
"vlan_id": 1122
}, {
"wan_link_type": "MPLS",
"local_interface": "ge-0/0/3",
"overlay_tunnel": [],
"static_ip_assignment": {
"ip_address": "54.1.23.1/24",
"gateway_ip": "54.1.23.254"
},
"traffic_type": "DATA_ONLY",
"wan_link_name": "WAN_3",
"address_assignment": "STATIC",
"vlan_id": 1123
}, {
"wan_link_type": "Internet",
"local_interface": "ge-0/0/0",
"overlay_tunnel": [],
"static_ip_assignment": {
"ip_address": "54.1.20.1/24",
"gateway_ip": "54.1.20.254"
},
"traffic_type": "DATA_ONLY",
"wan_link_name": "WAN_0",
"address_assignment": "STATIC",
"vlan_id": 1120
}, {
"wan_link_type": "Internet",
"local_interface": "ge-0/0/1",
"overlay_tunnel": [],
"static_ip_assignment": {
"ip_address": "54.1.21.1/24",
"gateway_ip": "54.1.21.254"
},
"traffic_type": "DATA_ONLY",
"wan_link_name": "WAN_1",
"address_assignment": "STATIC",
"vlan_id": 1121
}],
"device_name": "sbmesh-hub1-cl",
"device_template": "Auto_SRX_Advanced_SDWAN_HUB_option_1",
"device_details": {
"serial_number": "84a23ab28a47",
"boot_image": ""
},
"vpn_authentication": "preshared_key",
"oam_traffic": {
"ip_prefix": "37.0.0.2/32"
}
}],
"site_capabilities": "OAM_AND_DATA"
},
"site_name": "sbmesh-hub1-cl",
"user_defined_properties": [{
"name": "oam-ce-vlan",
"value": "1129"
}, {
"name": "oam-ce-intf",
"value": "ge-0/0/0"
}, {
"name": "oam-ce-intf-prefix",
"value": "54.1.29.1/24"
}, {
"name": "oam-gateway",
"value": "54.1.29.2"
}, {
"name": "ebgp_peer_as",
"value": "54000"
}]
}]
}
}To add an enterprise hub device at Tenant level, send a POST request to the CSO server with the following JSON-formatted payload:
http://<CSO_Central_MS_ip>/tssm/configure-sitesJSON 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-tenantJSON 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": [
"Demo"
],
"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://<cso-host>/tssm/create-sites
NOTE: cso-host is the domain name, it changes with the change of instances in CSO.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 enterprise-hub and the provider-hub 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://<cso-host>/tssm/create-sites
NOTE: cso-host is the domain name, it changes with the change of instances in CSO.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-bootstrapJSON 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-bootstrapJSON Object Input
{"input": {
"device_uuid":.”asadasdasdasd1234”
}};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 enterprise 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_reportYou 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"
]
}
}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”,
]
}
}