Connectivity service

Introduction

The Slices Connectivity service is responsible for creating and managing connectivity reservations between Slices sites.

Service maintains information about all the connections between sites, available VLAN ranges and bandwidth on particular links.

A new connectivity request must contain a pair of sites, reservation timeframe (start and end dates) and requested bandwidth. Service responds with allocated VLANs on both sides of the new connectivity either in signed JWT token or plain JSON format.

Service deployment

Currently the running service is available at https://slices-cs.apps.dcw1.paas.psnc.pl.

Swagger generated online API documentation and OpenAPI yaml specification are available at /api-docs and /api-spec, respectively.

Service authentication and authorization

For making a reservation user needs to be log in into Slices and have active Experiment with Leader role. User Token is also required to be added into request as shown below.

You can learn more about token in section Developers guide for slices tokens

Service API usage

Requesting a new connectivity reservation for an experiment

The endpoint address is POST /apis/v1alpha1/connectivity.

Example JSON request body:

{
    "site1" : "pl-poznan1",
    "site2" : "be-gent1",
    "bandwidth" : "100", // in Mbps
    "start_date" : "2024-10-02T10:00:00.630Z",
    "end_date" : "2024-10-13T10:00:00.630Z",
    "tokens" : ["eyJhbGci4OiJFUzI1AiIsInR5cCI8IkpXGKJIsImtpZCI6ImVjMSJ9.eyJpc3MiOiJodHRwczovL2FjY291bnQuaWxhYnQuaW1lYy..."]
}

In Headers user needs to add Experiment token. Every reservation must be assigned to an active Experiment. Also reservation duration can not exceed of experiment expired date.

You can also indicate which response type you want to get. Possible option is JSON, with result in body. Other option is JWT signed by Connectivity service. This option is set by header parameter Accept, for example : Accept: application/jwt.

User can also indicate that reservation should start from now. Use parameter start_now with value true and "start_date" : null in body. Example: POST /apis/v1alpha1/connectivity?start_now=true

The correct result of placing the reservation request is return with body:

{
    "site1": "pl-poznan1",
    "site2": "be-gent1",
    "bandwidth": 100,
    "start_date": "2024-10-02T10:00:00.63Z",
    "end_date": "2024-10-13T10:00:00.63Z",
    "id": "con_slices-cs.apps.dcw1.paas.psnc.pl_5YZNsQYpMw9FLLvHmNUC4ng6TH",
    "experiment_id": "exp_expauth.ilabt.imec.be_01j7x2jwagefevxgwv39rkv4pq",
    "created_at": "2024-10-01T12:20:28.255Z",
    "created_by": "user_account.ilabt.imec.be_2meafdbw143x9T6e97hs56asd",
    "site1_s_tag": 3505,
    "site1_c_tag": 0,
    "site2_s_tag": 2703,
    "site2_c_tag": 0
}

or for JWT:

{
    "iss": "https://slices-cs.apps.dcw1.paas.psnc.pl",
    "connectivity": {
        "site1": "pl-poznan1",
        "site2": "be-gent1",
        "bandwidth": 100,
        "start_date": "2024-10-02T10:00:00.63Z",
        "end_date": "2024-10-13T10:00:00.63Z",
        "id": "con_slices-cs.apps.dcw1.paas.psnc.pl_5YZNsQYpMw9FLLvHmNUC4ng6TH",
        "experiment_id": "exp_expauth.ilabt.imec.be_01j7x2jwagefevxgwv39rkv4pq",
        "created_at": "2024-10-01T12:20:28.255Z",
        "created_by": "user_account.ilabt.imec.be_2meafdbw143x9T6e97hs56asd",
        "site1_s_tag": 3505,
        "site1_c_tag": 0,
        "site2_s_tag": 2703,
        "site2_c_tag": 0
    }
    "exp": 1728488952,
    "iat": 1727876952,
    "sub": "con_slices-cs.apps.dcw1.paas.psnc.pl_5YZNsQYpMw9FLLvHmNUC4ng6TH"
}

Body contains sites names, requested bandwidth, duration and basic information as reservationId and experimentId.

s_tag - Service VLAN Tag is assigned by the Service for each site for connection between Slices nodes. c_tag - Client VLAN Tag is assigned by the Service for each site for connection between sites or services (used for QinQ connections).

Validation

If connectivity between sites or nodes can not be reserved, service will return list of errors in form :

{
    "detail": [
        {
            "loc": [
                "Bandwidth"
            ],
            "msg": "No available vlans between site1 <-> site2",
            "type": "NotValid"
        }
    ]
}

Possible request validation error types (loc field values):

  • Site - when either of the specified sites can not be found or site are not interconnected

  • Date - when either of the provided start or end date is incorrect (e.g. exceed experiment expiration date)

  • Bandwidth - when there is not enough free bandwidth to meet the request or no VLANs are available during the requested time period

Retrieve existing connectivity details

The endpoint address is GET /apis/v1alpha1/connectivity/{id}, where id is a reservationId.

User needs to be assigned VIEWER, LEAD or ADMIN role in given experiment to retrieve connectivity reservations details.

Response body is same as for reservation creation request.

Update reservation

The endpoint address is PUT /apis/v1alpha1/connectivity/{id}, where id is a reservationId.

User needs to be assigned LEAD or ADMIN role in given experiment to update connectivity reservations.

Delete reservation

The endpoint address is DELETE /apis/v1alpha1/connectivity/{id}, where id is a reservationId.

User needs to be assigned LEAD or ADMIN role in given experiment to delete connectivity reservations.

JWKs

In case a request is made with Accept: application/jwt header value, service generates, signs and returns a custom connectivity token.

Service exposes the public key used in the signature process in a JSON Web Key Set at /.well-known/jwks.json. It can be used by the client software to validate correct signature of the received connectivity token.

Data information

Available sites:

  • pl-poznan1

  • be-gent1

  • be-antwerp

  • hu-sztaki

  • gr-uth

  • se-kth

  • es-uc3m

  • es-upvehu

  • fr-sophia

  • fr-slices

  • fr-nantes

  • fr-lille