Orchestrator NB API Expansion - Design

[juztas]

Here is the draft hit list for the expansion of the SENSE NB API. The development task group include @xi-yang @R-Jimenez @juztas @scaly789 .

Item in the below is checked off when there is a Feature tagged issue is taking care of it.

1. Service Intent

   • [x] 1a. Make SENSE API intent format consistent with StackV-Service profile format (DNC for now)
   • Swagger doc upgrade 2.0
   • [x] 1b. List / show service profiles - create from UI and read-only for API
   • [x] 1c. Manage "service intents" versions"
   • history list (filter?) / view details
   • reference to (service_profile + edit-params + appended with queries) for service create
   • New intent version UUID saved along with instance UUID

2. Service Instance

   • [x] 2a. Show service details (creation time, status, alias, owner name)
   • [x] 2b. List/View service_intent by serviceUUID (overlap with 1c.)
   • [x] 2c. Lookup serviceUUID by service_alias
   • [x] 2d. + Reinstate op with intent UUID
   • [x] 2e. + Modify op with new intent data (full)
   • [x] 2f. Service logging (default == all, opt: loggign level + filters)
     • Error / failure info extraction ?

3. Lookup / Discovery

   • [ ] 3a. Restrictive: for F-Visualization role user only (?)
   • 3a+. - R21 enhancement -- identify uesr home domains / nodes / interfaces for restrictive access (list managed by admin)
   • [x] 3b. List all domains URI
   • opt: Filter by name substring and regex
   • opt: list all network domains vs end-stie domain
   • [x] 3c. List all peering points for network domain (with isAlias to other domain)
   • opt: Filter by name substring and regex
   • [x] 3d. List all end hosts for end-site domain
   • opt: with data interfaces
   • opt: Filter by name substring and regex
   • [x] 3e. List data interfaces for an end-host
   • opt: with vlan ranges
   • opt: with ip address pools (minus allocated ?)
   • opt: Filter by name substring and regex
   • [x] 3f. List service instances using an end-host data interface.
   • opt: Filter by name substring and regex
     • Provide details for ones owned by this user?
     • Anonymity for others? Only provide source - destination + bandwidth usage ?
   • opt: Filter by destination (port / node / domain URI or name)

4. Extra

   • [x] 4a. Document extra /sevice and /instance resources as needed
     • force_cancel, force_retry, verify etc. (as incorporated into API client packages)
   • [x] 4b. configure OAuth / Keycloak on SwaggerHub ...
   • [ ] 4c. Make an Ansible module (sense-service) for provisioning only
   • [ ] 4d. More formal error code / message structure definition

** Reference: SENSE-O NB API Swagger Doc

On the Orchestrator side, new development will be done in the StackV/Feature-sense_nbi_rework-M11-xyang branch.

A new API will be documented as SENSE-O NB API 2.0.

---

Original:

Here is the APIs and manifests for submission we need

1. Query to get all Edge points, like urn:ogf:network:es.net:2013::wash-cr5:6_1_1:+i ...
2. Extend this query to get connections - e.g. I want to get full list of any endpoint and how they are connected to each other. (This might require change on Network-RM to provide this information). In the future - it should also provide the capacity on each port and how many links are from A to B, B to C and so on...
3. Query to get information about the delta. status call returns only string with OK/FAILED... Is there a call to get all historical info? Like submit time, commit time, failure message - full info about a specific delta since it appeared on the system.
4. Submit intent and request path from A to B;
5. Submit intent and request path from A to B with starttime in 1hr;
6. Submit intent and request path from A to B with starttime in 1hr and endtime in 2hrs;
7. Submit intent and request path from A to B with endtime in 1hr;
8. Submit intent and request path from A to B with IP only on A with 192.168.0.1/24;
9. Submit intent and request path from A to B with IP on A with 192.168.0.1/24 and on B 192.168.0.2/24;
10. Submit intent and request path from A to B with IP on A with qos of 1gigabit;
11. Cancel intent based on UID;
12. Get all intents submitted based on state (OK, FAILED, ...)
13. Get intent status and all information related to it.
14. Resubmit intent which had uid XXXXX
15. Get full logs of intent request XXXXX

[xi-yang]

1. By python ./test/test_api_methods.py, query for end-site works while query for WAN domains failed.

# Testing Method #1
====================================================================================================
Request:
https://sense-o.es.net:8443/StackV-web/restapi//sense/discovery/edgepoints/urn:ogf:network:ultralight.org:2013
Response (code=200):
{
  "edge_points": [
    {
      "capailities": [], 
      "peer_uri": "urn:ogf:network:ultralight.org:2013:s0:1_3:+", 
      "stp": {
        "assign_ip": null, 
        "ipv4_prefix_list": null, 
        "type": "ethernet/vlan", 
        "uri": "urn:ogf:network:ultralight.org:2013:s0:1_3:transfer-6.ultralight.org:enp4s0f1", 
        "label": null
      }, 
      "peer_name": null
    }, 
    {
      "capailities": [], 
      "peer_uri": "urn:ogf:network:ultralight.org:2013:s0:1_2:+", 
      "stp": {
        "assign_ip": null, 
        "ipv4_prefix_list": null, 
        "type": "ethernet/vlan", 
        "uri": "urn:ogf:network:ultralight.org:2013:s0:1_2:sdn-dtn-1-7.tier2:enp143s0", 
        "label": null
      }, 
      "peer_name": null
    }
  ], 
  "name": null, 
  "uri": "urn:ogf:network:ultralight.org:2013"
}
----------------------------------------------------------------------------------------------------
Request:
https://sense-o.es.net:8443/StackV-web/restapi//sense/discovery/edgepoints/urn:ogf:network:es.net:2013:
Response (code=500):
>>> Something Wrong <<<
----------------------------------------------------------------------------------------------------

[xi-yang]

2. Is this about topology connectivity or list of all the services originating from / sinking to this site?

3. We will add the support in SENSE-O NBI.

[juztas]

1 looks to be then orchestrator issue. Also 1 - I need to get all edgepoints, like call: https://sense-o.es.net:8443/StackV-web/restapi//sense/discovery/edgepoints should return all list of edge points.

2. Not only site - but yes, topology how things are connected. I know it is not available in N-RM - but would be great to have this. Not sure what it would take to implement.
3. Cool.

[xi-yang]

4-11 are supported now.

12-15 will be added to SENSE-O NBI.

For clarification, does get intent mean the JSON intent spec or the service instance? Intent is a JSON document that can be used by multiple service instances. Each service instance could also have multiple intents along its history. We may consider change the requirements to something like

• get latest intent (JSON doc) for a service instance (input: service instance UUID).
• get all versions of intent for a service instance
• reinstate a version of intent to a service instance
• get service instance log

[xi-yang]

2. Not only site - but yes, topology how things are connected. I know it is not available in N-RM - but would be great to have this. Not sure what it would take to implement.

"topology how things are connected" can be very broad. I could return the entire model but that is too much for the request. Alternatively we can use service negotiation call to query connections between two (or more) give endpoints with intents of different parameters.

[juztas]

let's say we have switch A and B and ports 1,2 on A connected to B 1,2:

1. give me a list of all ports, this gives A:1, A:2, B:1, B:2
2. give me to what A:1 is connected. It replies B:1
3. give me details of port A:1, it replies json dictionary: total capacity: 100G, available: 90G, supported_vlans: 3600-3619; empty_vlans: 3605-3619 ... and so on.

[juztas]

for get intent - we need both. and what was submitted and also what is provisioned with all details

[xi-yang]

Ref: https://github.com/esnet/StackV/issues/958 for some earlier query discussions.

[xi-yang]

@juztas

• 2 is still unclear to me. I am leaving it to future discussions.

• 3 is now tracked in Intent inquiry and operation - development #5

• 4-11 and 14 have examples in Service lifecycle operation examples #6

• 12 - 15 are now tracked in Query for details of a service instance #4

@R-Jimenez and I will work on the development for #4 and #5.

[R-Jimenez]

I've established a JSON schema system for both responses and resource endpoints that should help with ironing out a consistent API structure, as well as come up with a neat way of serving them through our existing deployments. These schemas can be used for validation, and will also make porting into swagger much easier as the response information can be some of the bulkiest parts of the doc. The initial StackV API 2.0 general response schema and an example data response schema can be found at the following:

• https://dev1.virnao.com:8443/StackV-web/docapi/meta/response.json
• https://dev1.virnao.com:8443/StackV-web/docapi/data/instances.json

Note again this is not replacing the swagger docs, but are more for development and automation, and will be used to bootstrap/guide both the swagger and general API upgrades.