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: Rel 0.9.5 #249

Merged
merged 10 commits into from
Jun 11, 2024
Merged

TI API: Rel 0.9.5 #249

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b656ddc
Rel 0.9.
FabrizioMoggio Jun 3, 2024
f55e9d1
fix megalinter
FabrizioMoggio Jun 3, 2024
ae4d380
Delete code/Test_definitions/Traffic_Influence.yaml
FabrizioMoggio Jun 3, 2024
1d60a72
fix MegaLinter
FabrizioMoggio Jun 3, 2024
65625c7
fix MegaLinter
FabrizioMoggio Jun 3, 2024
fc7ae4e
fix MegaLinter
FabrizioMoggio Jun 3, 2024
c337cd9
fix MegaLinter
FabrizioMoggio Jun 3, 2024
936d5af
Fixed some error in the Documentation
FabrizioMoggio Jun 4, 2024
1e693f9
MegaLinter Fix
FabrizioMoggio Jun 4, 2024
bea2c54
MegaLinter Fix
FabrizioMoggio Jun 4, 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
225 changes: 160 additions & 65 deletions code/API_definitions/Traffic_Influence.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ openapi: 3.0.3
# API info #
############################################################################
info:
title: OPAG-CAMARA Traffic Influence API
version: 0.9.4-wip
title: Traffic Influence API
version: 0.9.5-wip
description: |
## Overview
The reference scenario foresees a Service, composed by one or more Service
Expand Down Expand Up @@ -90,30 +90,30 @@ info:
Before starting to use the TI API, the developer needs to know about the
below specified details:\
\
**Base-Url**
**Base-Url:**
The RESTful TI API endpoint, for example
[**https://tim-api.developer.tim.it/trafficinfluence**](https://tim-api.\
developer.tim.it/trafficinfluence)\
\
**TrafficInfluence**
**TrafficInfluence:**
This object represents the resource that carries the requirements from the
user to be implemented. The TI API is invoked for the life cycle management
of this resource (CRUD). The resource contains the intents from the TI API
Consumer. Managing this resource, the developer can specify in which
geographical location the routing must be applied, toward which application,
maybe for a specific set of users or for a limited period of time.\
\
**trafficInfluenceID**
**trafficInfluenceID:**
Identifier for the Traffic Influence resource. This parameter is returned
by the TI API and must be used to update it (e.g., adding a Device or
deleting it). A different Traffic Influence resource must be created for
any Device or Zone or Region. All these resources are related to an
Application identified by "appId".\
\
**apiConsumerId**
**apiConsumerId:**
Unique identifier for the TI API Consumer.\
\
**region**
**region:**
The developer can specify in which geographical area he requires the fastest
routing toward the nearest application instance. A "region" is a wide
geographical area and it contains one or more "zones". A "zone" is where the
Expand All @@ -125,7 +125,7 @@ info:
"trafficInfluenceID"). All the created resources are aggregated by the
Application (identified by "appId").\
\
**zone**
**zone:**
The developer can specify in which geographical area he requires the fastest
routing toward the nearest Application instance. A "zone" is a smaller
geographical area inside a "region". A "zone" is where the Edge Cloud Zone
Expand All @@ -135,32 +135,40 @@ info:
"trafficInfluenceID"). All the created resources are aggregated by the
Application (identified by "appId").\
\
**appId**
**appId:**
Copy link
Collaborator

Choose a reason for hiding this comment

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

I saw that some other parts could get this as well.
Something like sed 's/\([A-Za-z0-9]\)\*\*/\1\:\*\*/g should do the trick.

A globally unique identifier associated with the application. This
identifier is provided during the application onboarding process.
To influence the traffic toward a specific Application. It is the Operator
Platform that detects the appropriate Application instance in the selected
"region" or "zone".\
\
**appInstanceId**
**appInstanceId:**
A globally unique identifier generated by the Operator Platform to identify
a specific instance of the Application on a specific zone. To influence a
traffic toward a specific Application instance.\
\
**trafficFilters**
The Application can expose different service on different interfaces, with
this parameter it is possible to enable just some of those services maybe
for different sets of users.\
**sourceTrafficFilters:**
The traffic can be from a specific application port in the Device.\
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think we need to differentiate qualify between "application" in sourceTrafficFilters and one in destinationTrafficFilters description. While the application in sourceTrafficFilters seems to refer to device the destinationTrafficFilters could be referring to EAS. This is to avoid any confusion w.r.t terms we have defined so far

Copy link
Collaborator Author

@FabrizioMoggio FabrizioMoggio Jun 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

we have:

source private ip and port
source public ip and port
destination ip, port and protocol

in sourceTrafficFilter we have the source private port.

according to: #230 (reply in thread)

we need to better specify this.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'm wondering @babunkj how the UPF can be effected by the "source private ip"

Copy link
Collaborator

Choose a reason for hiding this comment

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

I'm wondering @babunkj how the UPF can be effected by the "source private ip"

The packet Detection Rules in the UPF can include the source device Ip address and port and the destination IP Address and port.

Copy link
Collaborator

Choose a reason for hiding this comment

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

We can use 'specific source port in the Device' or 'specific application client port in the Device' instead of 'specific application port in the Device'.

Copy link
Collaborator Author

@FabrizioMoggio FabrizioMoggio Jun 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

@babunkj sure, we will not use APPLICATION port in the description

Anyway, it is totally clear to me that the "source port" is required, my doubt is about "source PRIVATE port". The UPF is indeed effected by the "source PUBLIC port". The all discussion here is around:

  1. agreement on having the "source PUBLIC port"
  2. discussion on also having the "source PRIVATE port"

I'm still not sure, even after this: #249 (comment) if you are asking for the PUBLIC or PRIVATE or both :-). Sorry it is totally my fault not being an expert in this field.

Copy link
Collaborator

Choose a reason for hiding this comment

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

@FabrizioMoggio the UPF looks at source PRIVATE Port since the translation from PRIVATE to PUBLIC happens after UPF processing (in Uplink direction which is what we are concerned with for Traffic Influence).

Regarding what ports to include in the request, my comment is that both are required:
PUBLIC port is required to identify the device. It can be part of the Device identifier attribute.
PRIVATE port is required to identify the traffic. This can be part of sourceTrafficFilter attribute.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

dear @babunkj thank you so much, that is correct, in a traditional scenario, you are totally right. Now I got you.

My confusion is due to the discussion we are having in FWA (or tethering), that is what @gunjald was referring to, according to my understanding. In FWA we have a device with a "Private-1 IP/Port" connected to a FWA device. The FWA device translate it to "Private-2 IP/Port". This is what the UPF gets. Than we have CGAT and so "Public IP/Port"

Private-1 (in the LAN)
Private-2 (Core Network)
Public (Internet)

I was focusing on Private-1 forgetting about Private-2 :-).

So we currently we have:

Device: with Private-1-IP and and Public-IP and Public-Port

Where Private-1=Private-2 for a smartphone. In this scenario, the common one, we need to introduce, I agree with you, Private-1-Port. Because this is the Port the UPF uses.

This is not enough for FWA or tethering. In this scenario Private-1 is different from Private-2 and we also need Private-2-IP and Private-2-Port. In this scenario indeed the UPF works with Private-2-IP and Private-2-Port.

About Private-1-IP: it is provided by the client to the API Consumer that puts it into Device
About Public-IP: it is discovered by the API Consumer that puts it into Device
About Private-2-IP: it can be discovered by the Network, knowing Public-IP

What about Private-2-Port? how can we get it?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Right @FabrizioMoggio. That is an interesting scenario for FWA and mobile devices which act as hotspot.
I think the Private-2-IP and Private-2-Port you referred to may be derived from the Public IP and Public Port (Reverse mapping in NAT). However, these values are not visible to the Application server.

\
**Device**
A user Device can be provided as an input. To add more users the TI API must
be invoked (POST) of each user Device. New "TrafficInfluence" resources are
created (with different "trafficInfluenceID"). All the created resources are
aggregated by the Application (identified by "appId"). The routing toward
the selected Application instance is only applied for provided user
Devices.\
**destinationTrafficFilters:**
The Application can expose different service on different interfaces,
identified by port and protocol, with this parameter it is possible to
route the traffic just toward some of those services maybe for different
sets of users.\
\
**Notification URL and token**
**Device:**
An user Device can be provided as an input. The Device can be identified by
the phone number (phoneNumber), an external identifier
(networkAccessIdentifier) or by its IP Address (Ipv4Address, Ipv6Address)
also specifying a Port. For IP address both the private (as seen from inside
the Device) and the public (as seen over Internet by a server connected to
the Device) can be used. To add more users the TI API must be invoked (POST)
of each user Device. New "TrafficInfluence" resources are created (with
different "trafficInfluenceID"). All the created resources are aggregated by
the Application (identified by "appId"). The routing toward the selected
Application instance is only applied for provided user Devices.\
\
**Notification URL and token:**
Developers have a chance to specify call back URL on which notifications
(e.g. session termination) regarding the session can be received from the
service provider. This is also an optional parameter.
Expand Down Expand Up @@ -270,6 +278,11 @@ info:
- 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
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
Expand Down Expand Up @@ -641,28 +654,29 @@ components:
- 'error'
- 'deletion in progress'
- 'deleted'
trafficFilters:
type: array
items:
type: string
description: Indicates the packet filters of the IP flow. The source
IP is not required. It is retrived by the platoform according to
the TI API request. If no Traffic Influece resourse is created with
a specific Device, any IP will be routed to the Application. If a
Traffic Influece resource exists with a specific Device configured,
only the related IPs will be routed to the local instance of the
Application. The destination IP is not required,it is already known
by the platform thanks to the appId and appInstanceId parameters
that are used to retive the destination IP. The protocol must be
specified and it is identified by a string according to the column
“Keyword” as defined by IANA (https://www.iana.org/assignments/\
protocol-numbers/protocol-numbers.xhtml), e.g. UDP or TCP.
The destination port must be specified.
example: TCP 5060
minItems: 1
minItems: 1
description: Identifies IP packet filters. To be used when a the
Application needs a traffic flow towards a specific EAS interface
sourceTrafficFilters:
description: Ports used locally by the device for flows to which
the requested traffic influence should apply. If omitted, then the
traffic influence will apply to all flows between the device and the
specified application server address and ports.
type: object
properties:
sourcePort:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Shouldnt it have destinationProtocol too in sourceTrafficFilters?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I don't think so. the Protocol for the flow is the one defined in destinationTrafficFilter. It should be the same also for the source

Copy link
Collaborator

Choose a reason for hiding this comment

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

I agree. So then should we separate out port so that it is explicitly mentioned as a distinct field which associate with both source and destination filters commonly?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

We could have:

sourceTrafficPort
destinationTrafficPort
trafficProtocol

and we remove trafficFilters

Copy link
Collaborator

Choose a reason for hiding this comment

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

The only thing i feel is that if we should include the source or destination IP address or not? If we want to keep IP addresses then trafficFilters still seems fine. If we dont include IP addresses then the above proposal looks fine.

If we chose to keep IP addresses then it could be in similar lines sourceTrafficFilter, destinationTrafficfilter, trafficProtocol?

Copy link
Collaborator Author

@FabrizioMoggio FabrizioMoggio Jun 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

not sure to get the comment :-)

we already have:

  • device: with the source IP (public and private) and public Port

I'm proposing to add:

  • sourceTrafficPort: the source private Port
  • destinationTrafficPort: the destinatin public port
  • trafficProtocol: the protocol, that is the same for source and destination

removing the trafficFilters

Copy link
Collaborator

Choose a reason for hiding this comment

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

With minor change I agree with this,

  • Device refers to Source and Destination refers to EAS
  • device: represented by the source public IP and public Port (we may not need to use private IP in my opinion)
  • sourceTrafficPort: the source (device) public Port
  • destinationTrafficPort: the destination public port
  • trafficProtocol: the protocol, that is the same for source and destination

Please note that everything is expressed as public from external applications perspective.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

my understanding was that we had to also provide information about the device PRIVATE port. The source public port is already in Device.

this according to @babunkj , in this comment: #230 (reply in thread)

Copy link
Collaborator

Choose a reason for hiding this comment

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

we need then more information from @babunkj As in my opinion externally only the public IP and port are visible. Unless it is explicitly specified that the applications hosted in telco edge cloud zone can see both private and public IP:Port.

In general we do not have any visibility how the EAS will see the IP port in device traffic when hosted in edge cloud zone and if different operator will have different model to expose private or public IP of the device it will be difficult to say which one the EAS will see in which deployment. I think we need more feedback from the operator on the possibilities and how well we can address them.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Let me first try to (re)state the requirement before giving the comments:
a) The scenario is: A device has more than one traffic originating from it with the same source IP Address and different ports, but only a specific traffic (identified by a specific port) needs to be influenced and diverted to say an Edge cloud. This requirement needs the identification of the source traffic by its source IP Address and source port.
An example use case is: when an always-on low resolution video traffic from a device is analysed and a trigger is detected, switch the high resolution video traffic alone to the edge cloud.

b) In an extended case of the above one: based on traffic from say Port A, the traffic from a set of ports or all Ports are to be influenced and diverted to an Edge cloud.
An example use case is: when an always-on low resolution video traffic from a device is analysed and a trigger is detected, switch all high resolution video traffic or all video traffic from that device to the edge cloud.

The solution to the above becomes a challenge due to NATing. Giving my comments for IPv4 and IPv6 cases:

IPv4:

  • In the case of IPv4, even though the combination of External IP and External Port will identify the device uniquely, the source port is also required in order to identify the traffic. However, only External IP and External Port are directly visible externally in the case of IPv4.
  • Since it wouldn’t be possible to derive source port directly from the IP headers by the application server, suggesting the following:

a) If NAT element supports sharing of IP Address-Port mapping, the source port can be fetched by the operator platform (not available to application server)
b) When the source port(s) is known to the application server (indirectly), use that info in the source traffic filter.
c) When the source port is omitted, the traffic influence is to be applied to all traffic for the session from the device (as provided in the current version)

IPv6:
For IPv6, I suppose, the device port (source port) could be visible to the external server and can be used in the source traffic filter. Not sure how operator networks handle NAT for IPv6.

Another comment is that I feel it is better to keep the sourceTrafficFilters and destinationTrafficFilters attributes as defined in the version 0.9.5-wip. They indicate the purpose. The current structure is also more amenable for future enhancements.

We could discuss this over a call if that helps.

allOf:
- $ref: "#/components/schemas/PortsSpec"
destinationTrafficFilters:
description: Identifies the destination IP packet filters. To be
used when it is needed a traffic flow towards a specific EAS
interface identified by a protocol and a port. Also the Protocol
(e.g. TCP or UDP) can be specified.
type: object
properties:
Copy link
Collaborator

Choose a reason for hiding this comment

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

In general the port and IP address are used together for identification of specific traffic flow. Is there a need to include the IP address of device or EAS in source and destination traffic filters?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

the IP address for the source is already in Device. For the destination, we are currently just targeting application deplyed by the OP so, the destination IP is already known by the Transformation function as a consequence of AppId or AppInstanceId.

We are discussing in OPAG about this: "Support for External EAS". If we move forward with that requirement, the destination IP is required

Copy link
Collaborator

Choose a reason for hiding this comment

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

I think the observation is partly correct but then i see another point that if the application has multiple components then how would AppId or AppInstanceId.can be used to determine the right component if the components are having different IPs? Any suggestion or thought in such scenario?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

do you mean an Application that is exposing different IPs, Ports and maybe protocols, and the Service Provider wants to influence just some of them? Currently this is not supported. Anyway this can be a step toward the support for external EAS. even more, if we implement this, we also have the support for external EAS for free :-)

Copy link
Collaborator

Choose a reason for hiding this comment

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

I think we should document this part about the IP model used as it may lead to confusions. We need to ensure that an application is currently be accessible via a single IP only and may have different port associated to that IP. As this part is not explicit anywhere an app with multi component can have such traits that different components are accessible over different IPs then there could be issues.

So in my opinion we should need to capture this part explicitly but then in App LCM APIs we would need to discuss that this assumption is valid and will work correctly with TI API.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

sure, if you open a discussion in App LCM, can you please link it here?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Sure I will open a discussion in App LCM and link it here.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Following discussion has been opened, #264

destinationPort:
allOf:
- $ref: "#/components/schemas/PortsSpec"
destinationProtocol:
allOf:
- $ref: "#/components/schemas/Protocol"
notificationUri:
type: string
description: Defines the callback uri which should be notified in
Expand Down Expand Up @@ -719,42 +733,123 @@ components:
type: string
additionalProperties: false
Device:
description: |
End-user equipment able to connect to a mobile network. Examples of
devices include smartphones or IoT sensors/actuators.
The developer can choose to provide the below specified device
identifiers:
* `ipv4Address`
* `ipv6Address`
* `phoneNumber`
* `networkAccessIdentifier`
NOTE: the MNO might support only a subset of these options. The API
invoker can provide multiple identifiers to be compatible across
different MNOs. In this case the identifiers MUST belong to the same
device.
type: object
minProperties: 1
properties:
phoneNumber:
$ref: "#/components/schemas/PhoneNumber"
networkAccessIdentifier:
$ref: "#/components/schemas/NetworkAccessIdentifier"
ipv4Address:
$ref: "#/components/schemas/Ipv4Address"
$ref: "#/components/schemas/DeviceIpv4Addr"
ipv6Address:
$ref: "#/components/schemas/Ipv6Address"
description: Device identifier
$ref: "#/components/schemas/DeviceIpv6Address"
minProperties: 1
PhoneNumber:
description: A public identifier addressing a telephone subscription. In
mobile networks it corresponds to the MSISDN (Mobile Station
International Subscriber Directory Number). In order to be globally
unique it has to be formatted in international format, according to
E.164 standard, prefixed with '+'.
type: string
pattern: '^\+[1-9][0-9]{4,14}$'
example: "+123456789"
NetworkAccessIdentifier:
description: A public identifier addressing a subscription in a mobile
network. In 3GPP terminology, it corresponds to the GPSI formatted with
the External Identifier ({Local Identifier}@{Domain Identifier}).
Unlike the telephone number, the network access identifier is not
subjected to portability ruling in force, and is individually managed
by each operator.
type: string
example: "[email protected]"
description: identifier for the End User formatted as string, it cab be
the user's email address.
PhoneNumber:
type: string
pattern: '^\+?[0-9]{5,15}$'
example: "123456789"
description: Subscriber number in E.164 format (starting with country
code). Optionally prefixed with '+'.
Ipv4Address:
DeviceIpv4Addr:
type: object
description: |
The device should be identified by either the public (observed) IP
address and port as seen by the application server, or the private
(local) and any public (observed) IP addresses in use by the device
(this information can be obtained by various means, for example from
some DNS servers).
If the allocated and observed IP addresses are the same (i.e. NAT is not
in use) then the same address should be specified for both
publicAddress and privateAddress.
If NAT64 is in use, the device should be identified by its publicAddress
and publicPort, or separately by its allocated IPv6 address (field
ipv6Address of the Device object)
In all cases, publicAddress must be specified, along with at least one
of either privateAddress or publicPort, dependent upon which is known.
In general, mobile devices cannot be identified by their public IPv4
address alone.
properties:
publicAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
privateAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
publicPort:
$ref: "#/components/schemas/Port"
anyOf:
- required: [publicAddress, privateAddress]
- required: [publicAddress, publicPort]
example:
publicAddress: "84.125.93.10"
publicPort: 59765
SingleIpv4Addr:
description: A single IPv4 address with no subnet mask
type: string
format: ipv4
example: "192.168.0.1"
description: IP of the device. A single IPv4 address may be specified in
dotted-quad form 1.2.3.4. Only this exact IP number will match the flow
control rule.
Ipv6Address:
example: "84.125.93.10"
PortsSpec:
description: Specification of several TCP or UDP ports
type: object
minProperties: 1
properties:
ranges:
description: Range of TCP or UDP ports
type: array
minItems: 1
items:
type: object
required:
- from
- to
properties:
from:
$ref: "#/components/schemas/Port"
to:
$ref: "#/components/schemas/Port"
Port:
description: TCP or UDP port number
type: integer
minimum: 0
maximum: 65535
Protocol:
description: The protocol for the influeced flow. It can be specified and
it is identified by a string according to the column “Keyword” as defined
by IANA (https://www.iana.org/assignments/protocol-numbers/\
protocol-numbers.xhtml), e.g. UDP or TCP.
type: string
example: "TCP"
DeviceIpv6Address:
description: |
The device should be identified by the observed IPv6 address, or by any
single IPv6 address from within the subnet allocated to the device
(e.g. adding ::0 to the /64 prefix).
type: string
format: ipv6
example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
description: IP of the device. A single IPv6 address, following IETF 5952
format, may be specified like 2001:db8:85a3:8d3:1319:8a2e:370:7344
example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
AppInstanceId:
type: string
format: uuid
Expand Down