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 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 interconnectedDate
- 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