Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

TI API: Resource modification #296

Merged
merged 3 commits into from
Oct 9, 2024
Merged

TI API: Resource modification #296

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8bf3063
Resource modification
FabrizioMoggio Sep 12, 2024
13b7906
MegaLinter
FabrizioMoggio Sep 12, 2024
c7947dd
GENERIC_409: description updated
FabrizioMoggio Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 97 additions & 115 deletions code/API_definitions/Traffic_Influence.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,54 @@ info:
Application detects a location change, it can invoke the TI API again to
request a new routing optimization toward the new EAS instance.
## Quick Start
The TI API is consumed by an Application Function (AF) requesting for the
optimal routing, in term of latency, for the traffic flow from a Device
toward EAS instances in Edge Cloud Zones.\
When the Application (the EAS) is onboarded and deployed in the Edge Cloud
Zones, the Application is identified with a unique identifier ("appId").\
Using the application identifier ("appId") and specifying a Zone or a Region
the Telco Operator Platform, autonomously identifies the best instance of
the EAS toward which routing the traffic flow and configures the Mobile
Network accordingly to get the fastest routing.\
If just the application identifier is used, the Telco Operator Platform
identifies all the EAS Instances and activates the optimal routing on the
Mobile Network.\
If the optimal routing in term of latency should be available just for a set
of users, the TI API must be invoked for each user creating a new
TrafficInfluce resource for each one.
If the Application offers different services on different interfaces a
traffic filter based on IP, Port and Protocol can be used. I this way it is
also possible to redirect different users to different interfaces.
Here are some possible intents:
1) activate the optimal routing for the closest EAS instance: the TI API
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A question on 1) when we say "activate the optimal routing for the closest EAS instance".

Does it mean that if the TI API (step 1) is triggered by a UE application and after that it may need to wait for the TI resource state to become "active". Once the state is "active" the UE application can assume that the UE may been moved to the optimal UPF near to the given EAS serving that location which is the job of the TI API.
Now in this active state the UE application can find endpoint of the EAS instance (i.e. appId) by using the Application Endpoint discovery API (step 2) which I presume that will deliver the EAS instance which is optimal or closest to UE as the earlier call to TI API was successful and hence due to right UPF assignment the traffic will be automatically optimally routed to EAS.

The above explanation is in relation to ongoing discussion #293 and written to clarify following points,

  1. The UE can only send traffic to an EAS whose IP is available to it before starting any traffic towards the EAS
  2. Once a packet has been generated with a given destination IP, this packet can only be processed by the host or an application (EAS) on that host
  3. There may be multiple routes between a given set of source and destination address with different traits in terms of QoS

My understanding is that TI API is mainly concerned with point 3 where it can attempt or influence network to reselect a UPF for a UE which can optimally serve a given UE trying to access an EAS in its current location.
Any traffic from UE via this UPF to an EAS which is hosted to an edge cloud accessible via this UPF is assumed to be on "optimal routed".
Hence once the TI API is successful then the UE needs to determine the EAS IP via other ways to as explained above but it is not the TI API task to deliver the EAS endpoints to UE.

I may be repeating the statements but only objective is to understand what actions are to be done in my API client application and what is to be taken care in the TI API implementation.

If require I may prepare few slides to explain and get your views.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @gunjald @FabrizioMoggio , If you want, Deepak could prepare few slides and I can reserve some slot on our meeting and disscus about this topic. Maybe tomorrow is a lit bit hasty, next meeting on october first, could fit for you??

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to my understanding of the "story" described by @gunjald, his conclusion is correct.

  • The optimal routing is active only when the TI API invokes the callback to inform the API Consumer about the "active" status
  • From that moment the Service can instruct the App Client on which is the destination for the communication flow.
  • That destination must be the same used in the TI API invocation.
  • with: TI API: destination EAS IP address #294. The task for the Service will be easier
  • When the App Client generates a flow toward that destination the network had already setup the optimal routing.

@JoseMConde for sure we can discuss about this in the next Edge Cloud call

One note: is this discussion preventing to approve this PR? The text we are commenting was already in the YAML, just moved to improve readability. The actual value of this PR is in the new error introduced (GENERIC_409_DENIED_WAIT) that prevents the modification of a requested intent while it is still under implementation. I suggest to approve this PR and we can open a new issue related to this discussion if required.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @FabrizioMoggio,
You are totally right, we can approve this PR and open a new issue with this topic. I also agree with you about the conclusions of the Deepak's explanation, but maybe It makes sense to open this issue to see what the rest of the group thinks about it.
Could you do it for me??
Thanks. :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done: #309

must be invoked with the "appId". The Telco Operator Platform identifies
all the EAS instances and activates the optimal routing on the Mobile
Network so that the user is connect to the closest EAS insteance.
2) activate the optimal routing in a specific Region or Zone: the TI API
must be invoked with the "appId" and the Zones and Regions identifiers.
3) activate the optimal routing for a user Device: the TI API can be
invoked with a user Device identifier (“Device”). For each user Device,
a TI API invocation is required. The optimal routing is provided only for
the requested Devices.
## Authentication and Authorization
CAMARA guidelines defines a set of authorization flows which can grant API
clients access to the API functionality, as outlined in the document
[CAMARA-API-access-and-user-consent.md](https:\
//github.com/camaraproject/IdentityAndConsentManagement/blob/main/\
documentation/CAMARA-API-access-and-user-consent.md).
Which specific authorization flows are to be used will be determined during
onboarding process, happening between the API Client and the Telco Operator
exposing the API, taking into account the declared purpose for accessing the
API, while also being subject to the prevailing legal framework dictated by
local legislation.\
It is important to remark that in cases where personal user data is
processed by the API, and users can exercise their rights through mechanisms
such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
mandatory. This measure ensures that the API remains in strict compliance
with user privacy preferences and regulatory obligations, upholding the
principles of transparency and user-centric data control.
## API Documentation
## Details
The usage of the TI API is based on the management of a "TrafficInfluence"
resource, an object containing the intent requested invoking the TI API and
that is implemented by the platform configuring the Mobile Network for the
Expand All @@ -103,6 +151,10 @@ info:
information about the status of the requested resource.
For an Application (identified by "appId") many "TrafficInfluence" resources
can be created, e.g. to add multiple users, regions or zones.\
When an intent is expressed and a resource have been created, if the intent
must be modified, it is suggested to use the PATCH method
(/traffic-influeces/{trafficInfluenceID}). Anyway, any other new intent
(e.g. for the same device) will override the previous ones.\
\
Before starting to use the TI API, the developer needs to know about the
below specified details:\
Expand Down Expand Up @@ -202,120 +254,8 @@ info:
Developers can specify a callback URL on which notifications
regarding the requested intent can be received. For example to be notified
when the requested optimal routing is active.
## Authentication and Authorization
CAMARA guidelines defines a set of authorization flows which can grant API
clients access to the API functionality, as outlined in the document
[CAMARA-API-access-and-user-consent.md](https:\
//github.com/camaraproject/IdentityAndConsentManagement/blob/main/\
documentation/CAMARA-API-access-and-user-consent.md).
Which specific authorization flows are to be used will be determined during
onboarding process, happening between the API Client and the Telco Operator
exposing the API, taking into account the declared purpose for accessing the
API, while also being subject to the prevailing legal framework dictated by
local legislation.\
It is important to remark that in cases where personal user data is
processed by the API, and users can exercise their rights through mechanisms
such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
mandatory. This measure ensures that the API remains in strict compliance
with user privacy preferences and regulatory obligations, upholding the
principles of transparency and user-centric data control.
## API Documentation
The TI API is consumed by an Application Function (AF) requesting for the
optimal routing, in term of latency, for the traffic flow from a Device
toward EAS instances in Edge Cloud Zones.\
When the Application (the EAS) is onboarded and deployed in the Edge Cloud
Zones, the Application is identified with a unique identifier ("appId").\
Using the application identifier ("appId") and specifying a Zone or a Region
the Telco Operator Platform, autonomously identifies the best instance of
the EAS toward which routing the traffic flow and configures the Mobile
Network accordingly to get the fastest routing.\
If just the application identifier is used, the Telco Operator Platform
identifies all the EAS Instances and activates the optimal routing on the
Mobile Network.\
If the optimal routing in term of latency should be available just for a set
of users, the TI API must be invoked for each user creating a new
TrafficInfluce resource for each one.
If the Application offers different services on different interfaces a
traffic filter based on IP, Port and Protocol can be used. I this way it is
also possible to redirect different users to different interfaces.
Here are some possible intents:
1) activate the optimal routing for the closest EAS instance: the TI API
must be invoked with the "appId". The Telco Operator Platform identifies
all the EAS instances and activates the optimal routing on the Mobile
Network so that the user is connect to the closest EAS insteance.
2) activate the optimal routing in a specific Region or Zone: the TI API
must be invoked with the "appId" and the Zones and Regions identifiers.
3) activate the optimal routing for a user Device: the TI API can be
invoked with a user Device identifier (“Device”). For each user Device,
a TI API invocation is required. The optimal routing is provided only for
the requested Devices.
## Release Notes
The Traffic Influence API reduces the complexity of activating the optimal
routing toward an Application Instance and o provides the optimal routing
for an user moving among geographical areas maybe served by different
Application instances. In this release it is up to the API Consumer to
detect the user moving among geographical areas.\
\
**Enhancements with respect to the previous release V0.8.1:**
- These release also effects existing data sessions
- These release can be also used to optimize existing data sessions when a
Device moves among geographical areas.
- The ueId parameter is renamed into Device
- The parameter Device, that identifies the User, is now simplified to
guarantee the identification of an existing data session
- InstanceId added
- TrafficFilters description updated
- CAMEL type adopted
- FlowInfo deleted
- OpenAPI version updated to 3.0.3
- To let the Developer to just work on parameters actually editable, the PUT
method is changed into a PATCH method with a limitation on the
parameters usable and modifiable. A new resource is created,
PatchTrafficInfluence that contains only the editable parameters
The same approach is also adopted for the PUT method and a new resource
PostTrafficInfluence was created with just the editable parameters
- DELETE response code modified as 202. The Deletion request is accepted
(not yet completed, it must be carried on by the system)
- Added response code 400 (bad request) to POST
- General improvement in documentation
- applicationId changed into appId and instanceId changed into appInstanceId
- Alignement of parameters with EdgeCloud_LCM: applicationId changed into
appId and instanceId changed into appInstanceId
- Modified reference to CAMARA Authorization guidelines link
- Telco Edge Site changed in Edge Cloud Zone
- Added: info-contact
- Device: IPV4 and IPV6 changed to represent just one IP. Netmask is no more
valid
- Global tags definition
- Adopted lowerCamelCase for OperationId
- Added descriptions for Delete and Get (for specific resource) methods
- Added missing operationid
- Improvement of callback definition
- Added "description" to the TrafficInfluence resource
- Added "description" to the PatchTrafficInfluence resource
- Added "description" to TrafficInfluenceNotification
- Added "description" to NetworkAccessIdentifier
- Added "description" to ErrResponse
- Added "description" to message
- Added "description" to status
- Added "description" to ErrorInfo
- Removed unused error code SessionNotFound404
- Alignement of parameters with EdgeCloud_LCM: applicationId changed into
appId and instanceId changed into appInstanceId
- Adoption of OpenId authentication for Consent Management. Client
Credential is removed
- Intruduced xcorrelator
- General alignment with CAMARA on returned Errors
- Modified CAMARA URL to refer to the Edge Cloud Repository
- OAS version now includes "-wip" extension
- simplified "Servers" section and included "vwip" as version
- Updated documentation to better specify how to identify a Device
- Updated the Device parameter according to CAMARA_common.yaml
- change API name in YAML
- introduced sourceTrafficFilters and modified trafficFilters into
destinationTrafficFilters
- sourceTrafficFilters added
- Alignement with "Edge Application Management API"
# FAQ's
(FAQs will be added in a later version of the documentation)
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
Expand Down Expand Up @@ -495,7 +435,9 @@ paths:
summary: updates a specific TrafficInfluence resource, identified by the
trafficInfluenceID value.
description: The resource identified by the trafficInfluenceID value can
be modified.
be modified. Before the PATCH can be invoked the status (state) of the
resource must be "active". If not an errore code 409 (DENIED_WAIT) is
returned.
operationId: patchTrafficInfluence
parameters:
- $ref: '#/components/parameters/x-correlator'
Expand Down Expand Up @@ -1025,6 +967,46 @@ components:
code: CALL_FORWARDING.UNKNOWN_PHONE_NUMBER
message: Call forwarding check can't be done because the phone
number is unknown.
Generic409:
description: Conflict
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_409_ABORTED:
description: Concurreny of processes of the same nature/scope
value:
status: 409
code: ABORTED
message: Concurrency conflict.
GENERIC_409_ALREADY_EXISTS:
description: Trying to create an existing resource
value:
status: 409
code: ALREADY_EXISTS
message: The resource that a client tried to create already
exists.
GENERIC_409_CONFLICT:
description: Duplication of an existing resource
value:
status: 409
code: CONFLICT
message: A specified resource duplicate entry found.
GENERIC_409_DENIED_WAIT:
description: Patch denial if the previous intent is not yet
fulfilled.
value:
status: 409
code: DENIED_WAIT
message: It is not possibile to modify the Traffic Influence
resource because it is still under provisioning. The resource
can be modified when it is fully implemented and activated.
Please wait for the resource status (state) to be "active"
before trying to update it.
Generic500:
description: Server error
headers:
Expand Down