RESTCONF Guide

Overview

The gateway was made to uniformize the API of performance measurement (PM) for the Skylight portfolio. This solution is based on the yang modelling. The gateway is in charge of managing performance Sessions; it converts the Yang model to any type of sub-system (such as Orchestrator-Sensor Control Sessions or Orchestrate-Agents Sessions).

Skylight Gateway Model – Objects

The Skylight yang is made of three critical objects:

1. Accedian-Service-endpoint
   This object represents a sender or a reflector. For example, you can have an agent, a Sensor Control interface, a VCE, or a PE Port/Interface.
   

   ---

   Note: On the current version (LA1-23.07), endpoint has a leaf reference to ne-config; this reference represents the parameters needed for CNC use cases for an agents session.

   ---

2. Accedian-session
   This object is a parameters session with a combination of n x Accedian-Service-endpoint with parameters representing the protocol targeted.
   For example, if we are doing a TWAMP Session, you will combine 2 Accedian-Service-endpoints: the first as the sender and the second as the reflector.

3. Accedian-service
   This object is a list of Sessions representing a key/value that will be used to identify the Sessions Data over the gNMI mechanism. (Those keys are: sender-id, reflector-id, service-id, and service-name. They are used as a registering key in the gNMI stream.)

Yang file of the Skylight Gateway model can be found here.

What is RESTCONF?

Yang was developed at first with NETCONF transport (SSH-based communication), but as more yang became used, a new JSON over http become another way of utilization. The current implementation of the Skylight Gateway only supports JSON-based communication over HTTPs in the current analytics lite deployment.

What is needed to use RESTCONF?

The current Skylight Gateway runs inside Skylight Lite (Referring to the Lite version because the actual use cases need to run on-premise). In this case, to gain access to the Skylight Gateway, you need to have login authentication. The main method is by providing an SSL certificate to the NGINX, which is the authentication engine of the Skylight Analytics Lite solution.

RESTCONF API consideration

The current system uses a synchronous communication principle, this means that if you are trying to use any CRUD (Create [POST] , Read [GET] , Update [PUT/PATCH], Delete [DELETE]) command type from this RESTCONF interface, you need to analyze the http return code and/or the JSON body.

Refer to the document Skylight 23.07 Accedian Yang Notifications Examples and Common Error Codes for Error/Return codes.
RestConf usage example:
PREREQUISITE: Agents need to be deployed with metadata that represent the ne-config from Accedian-service-endpoints. [Agent Configuration Example]

The current available Accedian-service-endpoints definition: [here]

ne-config: {
    ne-id : value”
    vlan-id : “value”
    ip : “value”
    sub-interface : “value”
}

Agent Metadata configuration example:

sensor-actuate:
    container_name: "Actuate_CiscoNSO_VM1_1"
    image: "gcr.io/sky-agents/agent-actuate-amd64:r22.11"
    environment:
      - AGENT_MANAGEMENT_PROXY=10.128.0.166
      - AGENT_METADATA_ne-id=PE_1
      - AGENT_METADATA_vlan-id=1000
    volumes:
      - secrets:/run/secrets
    depends_on:
      agent-init:
        condition: service_completed_successfully

Use case #1 - Create 2 Sessions between Agents, and Associate to a Service

This RESTCONF section shows how to create two endpoints: one as sender and one as reflector. Be careful of the ne-config; this should match the pre-requisite agent metadata configuration that you previously set when you deploy the agent.

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service-endpoint:service-endpoints

{
    "Accedian-service-endpoint:service-endpoint": [
        {
            "endpoint-id": "btep1_id",
            "endpoint-name": "btep1_3000",
            "description": "Twamp endpoint sender",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_1",
                    "vlan-id": "3000",
                    "ip": "10.0.100.1"
                }
            }
        },
        {
            "endpoint-id": "btep2_id",
            "endpoint-name": "btep2_3000",
            "description": "Twamp endpoint reflector",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_2",
                    "vlan-id": "3000",
                    "ip": "10.0.100.2"
                }
            }
        }
    ]
}
<Response [201]>

This RESTCONF section shows how to create two sessions (bts1_1 and bts1_2)

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-session:sessions
{
    "Accedian-session:session": [
        {
            "session-id": "bts1_1",
            "session-name": "btnameS1_1",
            "session-type": "Accedian-session-type:twamp-light",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        }
    ]
}
<Response [201]>

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-session:sessions
{
    "Accedian-session:session": [
        {
            "session-id": "bts1_2",
            "session-name": "btnameS1_2",
            "session-type": "Accedian-session-type:twamp-light",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        }
    ]
}
<Response [201]>

This RESTCONF section shows how to create one service called service_1, and we bundle sessions bts1_1 and bts1_2 inside this service. By doing this, we activate the gNMI streaming capability to be able to stream data when you register to service-id, service-name, sender-id, and reflector-id (reflector-id and sender-id are the corresponding endpoint-id).

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service:services
{
    "Accedian-service:service": [
        {
            "service-id": "service_1",
            "service-name": "service_name1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                }
            ]
        }
    ]
}
<Response [201]>

[GET] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service:services/service=service_1
<Response [200]>
{
    "Accedian-service:service": [
        {
            "service-id": "service_1",
            "service-name": "service_name1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                }
            ]
        }
    ]
}

Use case #2 - Create bulk Sessions/Services example

Bulk terminology is a way to concatenate from a single RESTCONF command many object creations.

This RESTCONF section shows how to create two endpoints from a single command:

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service-endpoint:service-endpoints
{
    "Accedian-service-endpoint:service-endpoint": [
        {
            "endpoint-id": "btep1_id",
            "endpoint-name": "btep1_3000",
            "description": "Twamp endpoint sender",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_1",
                    "vlan-id": "3000",
                    "ip": "10.0.100.1"
                }
            }
        },
        {
            "endpoint-id": "btep2_id",
            "endpoint-name": "btep2_3000",
            "description": "Twamp endpoint reflector",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_2",
                    "vlan-id": "3000",
                    "ip": "10.0.100.2"
                }
            }
        }
    ]
}
<Response [201]>

This RESTCONF section shows how to create four sessions in a single RESTCONF command:

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-session:sessions
{
    "Accedian-session:session": [
        {
            "session-id": "bts1_1",
            "session-name": "btnameS1_1",
            "description": "This is a description of bts1_1",
            "session-type": "Accedian-session-type:twamp-light",
            "group-id": "Grp1",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        },
        {
            "session-id": "bts1_2",
            "session-name": "btnameS1_2",
            "description": "This is a description of bts1_2",
            "session-type": "Accedian-session-type:twamp-light",
            "group-id": "Grp1",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        },
        {
            "session-id": "bts1_3",
            "session-name": "btnameS1_3",
            "description": "This is a description of bts1_3",
            "session-type": "Accedian-session-type:twamp-light",
            "group-id": "Grp1",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        },
        {
            "session-id": "bts1_4",
            "session-name": "btnameS1_4",
            "description": "This is a description of bts1_4",
            "session-type": "Accedian-session-type:twamp-light",
            "group-id": "Grp1",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": true,
                                "reflector-udp-port": 13000
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": true
                            }
                        }
                    }
                }
            ]
        }
    ]
}
<Response [201]>

This RESTCONF section shows how to create four services with four sessions in a single RESTCONF command:

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service:services
{
    "Accedian-service:service": [
        {
            "service-id": "bttest-service-id_1",
            "service-name": "bttest-service-name_1",
            "description": "A service description",
            "group-id": "Grp1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                },
                {
                    "session-id": "bts1_3"
                },
                {
                    "session-id": "bts1_4"
                }
            ]
        },
        {
            "service-id": "bttest-service-id_2",
            "service-name": "bttest-service-name_2",
            "description": "A service description",
            "group-id": "Grp1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                },
                {
                    "session-id": "bts1_3"
                },
                {
                    "session-id": "bts1_4"
                }
            ]
        },
        {
            "service-id": "bttest-service-id_3",
            "service-name": "bttest-service-name_3",
            "description": "A service description",
            "group-id": "Grp1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                },
                {
                    "session-id": "bts1_3"
                },
                {
                    "session-id": "bts1_4"
                }
            ]
        },
        {
            "service-id": "bttest-service-id_4",
            "service-name": "bttest-service-name_4",
            "description": "A service description",
            "group-id": "Grp1",
            "sessions": [
                {
                    "session-id": "bts1_1"
                },
                {
                    "session-id": "bts1_2"
                },
                {
                    "session-id": "bts1_3"
                },
                {
                    "session-id": "bts1_4"
                }
            ]
        }
    ]
}
<Response [201]>

Use case #3 - Notification on Service

For the notification mechanism available in the Skylight Gateway, a notification is based on the fact that we are sending an event from a state change of the three objects of the model:

• Accedian-service-endpoint:state-change-event
• Accedian-session:state-change-event
• Accedian-service:state-change-event

Those notifications (events) are sent using Server-Sent Events (a.k.a HTTP LonPolling) Reference : W3C.REC-eventsource-20150203. Client example can be provided on demand.

This RESTCONF section shows how to get those three state-change-event objects; this is requires for the registration.

Enabling all notifications
[GET] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/ietf-restconf-monitoring:restconf-state/streams
<Response [200]>
{
    "ietf-restconf-monitoring:streams": {
        "stream": [
            {
                "name": "notification-stream/sal-remote:data-changed-notification",
                "description": "Data change notification.",
                "access": [
                    {
                        "encoding": "XML",
                        "location": "http://nso-gw:8080/restconf/notification-stream/sal-remote:data-changed-notification"
                    },
                    {
                        "encoding": "JSON",
                        "location": "http://nso-gw:8080/restconf/notification-stream/sal-remote:data-changed-notification/JSON"
                    }
                ],
                "replay-support": true
            },
            {
                "name": "notification-stream/Accedian-service-endpoint:state-change-event",
                "replay-log-creation-time": "2023-08-25T15:46:44.058161014Z",
                "description": "This notification is sent when the state of the endpoint changes",
                "access": [
                    {
                        "encoding": "XML",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service-endpoint:state-change-event"
                    },
                    {
                        "encoding": "JSON",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service-endpoint:state-change-event/JSON"
                    }
                ],
                "replay-support": true
            },
            {
                "name": "notification-stream/Accedian-session:state-change-event",
                "replay-log-creation-time": "2023-08-25T15:46:44.232337269Z",
                "description": "This notification is sent when the state of the session changes",
                "access": [
                    {
                        "encoding": "XML",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-session:state-change-event"
                    },
                    {
                        "encoding": "JSON",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-session:state-change-event/JSON"
                    }
                ],
                "replay-support": true
            },
            {
                "name": "notification-stream/Accedian-service:state-change-event",
                "replay-log-creation-time": "2023-08-25T15:46:44.431385676Z",
                "description": "A top level notification providing state change information on the service and it's\nassociated service sessions and service endpoints",
                "access": [
                    {
                        "encoding": "XML",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service:state-change-event"
                    },
                    {
                        "encoding": "JSON",
                        "location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service:state-change-event/JSON"
                    }
                ],
                "replay-support": true
            }
        ]
    }
}

This RESTCONF section shows how to register to state-change-event object:

[GET] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/ietf-restconf-monitoring:restconf-state/streams/stream=notification-stream/Accedian-service-endpoint:state-change-event/access=json/location
<Response [200]>
{
    "subscribe-to-notification:location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service-endpoint:state-change-event/JSON"
}
[GET] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/ietf-restconf-monitoring:restconf-state/streams/stream=notification-stream/Accedian-session:state-change-event/access=json/location
<Response [200]>
{
    "subscribe-to-notification:location": "http://nso-gw:8080/restconf/notification-stream/Accedian-session:state-change-event/JSON"
}
[GET] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/ietf-restconf-monitoring:restconf-state/streams/stream=notification-stream/Accedian-service:state-change-event/access=json/location
<Response [200]>
{
    "subscribe-to-notification:location": "http://nso-gw:8080/restconf/notification-stream/Accedian-service:state-change-event/JSON"
}

This RESTCONF section shows the creation of two endpoints: one session using the previous endpoints and one service.

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service-endpoint:service-endpoints
{
    "Accedian-service-endpoint:service-endpoint": [
        {
            "endpoint-id": "btep1_id",
            "endpoint-name": "btep1_3000",
            "description": "Twamp endpoint sender",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_1",
                    "vlan-id": "3000",
                    "ip": "10.0.100.1"
                }
            },
            "group-id": "notif_bt"
        },
        {
            "endpoint-id": "btep2_id",
            "endpoint-name": "btep2_3000",
            "description": "Twamp endpoint reflector",
            "type": "Accedian-service-endpoint-type:ne-endpoint",
            "config": {
                "Accedian-service-endpoint-ne:ne-config": {
                    "ne-id": "pe_2",
                    "vlan-id": "3000",
                    "ip": "10.0.100.2"
                }
            },
            "group-id": "notif_bt"
        }
    ]
}
<Response [201]>


[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-session:sessions
{
    "Accedian-session:session": [
        {
            "session-id": "bts1",
            "session-name": "btnameS1",
            "session-type": "Accedian-session-type:twamp-light",
            "group-id": "notif_bt",
            "service-endpoints": [
                {
                    "endpoint-id": "btep1_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-sender": {
                                "admin-state": "true",
                                "reflector-udp-port": "13000"
                            }
                        }
                    }
                },
                {
                    "endpoint-id": "btep2_id",
                    "session-protocol": {
                        "Accedian-session-twamp-light:twamp-light": {
                            "session-reflector": {
                                "admin-state": "true"
                            }
                        }
                    }
                }
            ]
        }
    ]
}
<Response [201]>

[POST] -> https://dev1.cisco-nso.agentslab.analytics.accedian.io:443/restconf/data/Accedian-service:services
{
    "Accedian-service:service": [
        {
            "service-id": "service_1",
            "service-name": "service_name1",
            "group-id": "notif_bt",
            "sessions": {
                "session-id": "bts1"
            }
        }
    ]
}
<Response [201]>


This JSON body is an example of what can be received if the state of the endpoint=”btep1_id” changed from  NotReady → Ready

[
    {
        "Accedian-service:state-change-event": {
            "service-id": "service_1",
            "group-id": "notif_bt",
            "session-state-change": [
                {
                    "session-id": "bts1",
                    "service-endpoint-state-change": [
                        {
                            "endpoint-id": "btep1_id",
                            "status": "Ready"
                        }
                    ]
                }
            ]
        }
    }
]

This JSON body is an example of what can be received if the state of the session=”bts1” changed from Stopped → Running

[
    {
        "Accedian-service:state-change-event": {
            "service-id": "service_1",
            "group-id": "notif_bt",
            "session-state-change": [
                {
                    "session-id": "bts1",
                    "status": "Running"
                }
            ]
        }
    }
]

This JSON body is an example of what can be received if the state of the session=”bts1” changed from Running → Stopped

[
    {
        "Accedian-service:state-change-event": {
            "service-id": "service_1",
            "group-id": "notif_bt",
            "session-state-change": [
                {
                    "session-id": "bts1",
                    "status": "Stopped"
                }
            ]
        }
    }
]

More JSON body examples can be taken from the Skylight 23.07 Accedian Yang Notifications Examples and Common Error Codes document.

Managing Virtual Connection Endpoints

For detailed Information on adding and managing Virtual Connection Endpoints (VCE) for a particular Skylight module, please refer to the following section in Skylight sensor: control:
[Managing VCEs](Onpage:   The “Determining virtual disk size” section has a link to: https://docs.accedian.io/v1/docs/determining-the-quantity-and-size-of-virtual-disks   This is incorrect, the link should point to: https://docs.accedian.io/docs/virtual-machine-disk-configuration   On page:   The OpenMetrics Scraper section has a link to: https://api.analytics.accedian.io/session.html#operation/CreateConnectorInstanceV2   This is incorrect, the link should point to: https://api.analytics.accedian.io/session.html#operation/CreateConnectorConfigV2)