diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 00000000..1e99dfac Binary files /dev/null and b/.DS_Store differ diff --git a/README.md b/README.md index 6c577f8d..ca8331ce 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,28 @@ - - - - - - +# Edge Cloud -# EdgeCloud -Repository to describe, develop, document and test the EdgeCloud API family +Repository to describe, develop, document, and test the EdgeCloud API family ## Scope -* Service APIs for “Edge Cloud” (see APIBacklog.md) + +* Service APIs for “Edge Cloud” (see APIBacklog.md) * It provides the customer with the ability to: - * Provide and manage application images to be deployed on resources within the operator network - * Use reserved compute resources within the operator network for the deployment of applications on VMs or containers - * Influence the traffic routing from the user device toward the Edge instance of the Application + * Discover the closest edge cloud zone to a given device. + * Provide and manage application images to be deployed on resources within the operator network. + * Use reserved compute resources within the operator network for the deployment of applications on VMs or containers. + * Influence the traffic routing from the user device toward the Edge instance of the Application. * NOTE: The scope of this API family should be limited (at least at a first stage) to 4G and 5G. * Describe, develop, document and test the APIs (with 1-2 Telcos) * Started: 5th July 2022 -* Location: virtually -## Meetings -* Meetings are held virtually -* Schedule: Tuesdays 16h-17 CET, every two weeks. -* Meeting link: [LFX Zoom](https://zoom-lfx.platform.linuxfoundation.org/meeting/94237809115?password=05fb6d8a-a913-47d8-b003-db75ecdaa5d9) -## Results -* Sub Project is in progress +# Release Information + +# Contributing + +* Meetings + * [Registration](https://zoom-lfx.platform.linuxfoundation.org/meeting/94237809115?password=05fb6d8a-a913-47d8-b003-db75ecdaa5d9) + * Schedule: Tuesdays 1400-1500 UTC, every two weeks. + * Minutes: Access [meeting minutes](https://wiki.camaraproject.org/display/CAM/Edge+Cloud) -## Contributorship and mailing list -* To subscribe / unsubscribe to the mailing list of this Sub Project and thus be / resign as Contributor please visit . -* A message to all Contributors of this Sub Project can be sent using . -* CAMARA sp-edge-cloud: [Slack Channel](https://camara-project.slack.com/archives/C062PJNGW9F) +* Mailing list + * Subscribe / unsubscribe to the mailing list of this Sub Project [https://lists.camaraproject.org/g/sp-edc](https://lists.camaraproject.org/g/sp-edc). + * A message to the community of this Sub Project can be sent using [sp-edc@lists.camaraproject.org](sp-edc@lists.camaraproject.org). \ No newline at end of file diff --git a/code/.DS_Store b/code/.DS_Store index b1cf8685..b83402a8 100644 Binary files a/code/.DS_Store and b/code/.DS_Store differ diff --git a/code/API_definitions/.DS_Store b/code/API_definitions/.DS_Store new file mode 100644 index 00000000..0ee9b157 Binary files /dev/null and b/code/API_definitions/.DS_Store differ diff --git a/code/API_definitions/Discovery/simple_edge_discovery.yaml b/code/API_definitions/Discovery/simple_edge_discovery.yaml deleted file mode 100644 index c6537087..00000000 --- a/code/API_definitions/Discovery/simple_edge_discovery.yaml +++ /dev/null @@ -1,650 +0,0 @@ ---- -openapi: 3.0.3 -info: - title: Simple Edge Discovery API - version: 1.0.0 - description: | - # Find the closest Edge Cloud Zone - --- - # Summary - - The Simple Edge Discovery API returns the name of the closest operator Edge - Cloud Zone to a particular user device. - - # Purpose - Network operators may host multiple Edge Cloud Zones in a - given territory. Connecting your application to a server on the closest - Edge Cloud Zone means packets travel the shortest distance between - endpoints, typically resulting in the lowest round-trip latency. Note, the - physical (GPS) location of a user device is not a reliable way to determine - the closest Edge Cloud Zone, due to the way operator networks are routed - - so the operator will calculate the Edge Cloud Zone with the - _shortest network path_to the network-attached device identified in the API - request. - - Once you have the name of the closest Edge Cloud Zone to the user device, - you may: - - * connect the application client on the user device to your application - server instance on that Edge Cloud Zone. Note: the address of that server - instance is not part of the API response, but should be known in advance. - * or, if you have no instance on that Edge Cloud Zone, you may wish to - deploy one there. - - # Usage - - The API may be called either by an application client hosted on a device - attached to the operator network (i.e. phone, tablet), or by a server. - - There is a single API endpoint: `/edge-cloud-zones?filter=closest`. To call - this endpoint, the API consumer must first obtain a valid OAuth2 token from - the token endpoint, and pass it as an `Authorization` header in the API - request. - - The API returns the closest Edge Cloud Zone to a given device, so that - device needs to be identifiable by the network: - - * If you call the API from a server, you must explicitly pass one or - more device identifiers in the HTTP request header: - * `IP-Address`. This is the public IP address of the user device: this - can be obtained by an application hosted on that device calling a - public IP address API (e.g. GET https://api.ipify.org?format=json) - * `Phone-Number` . The international E.164 format (starting with country - code), e.g. +4407123123456 - * `Network-Access-Identifier` (where available from the API host operator) - - * If you call the API from a device attached to the operator network, then - you can attempt the request without passing device identifier(s) parameters - in the request header. If that request fails with a `404 Not Found` error - then retry the request but this time include a device identifier. - - The provider of the Edge Cloud Zone may be an operator, or a cloud provider. - - # Example requests: - - Examples for all API clients: - ``` - GET /edge-cloud-zones?filter=closest HTTP/1.1 - Host: example.com - Accept: application/json - Network-Access-Identifier: 4d596ac1-7822-4927-a3c5-d72e1f922c94@domain.com - - GET /edge-cloud-zones?filter=closest HTTP/1.1 - Host: example.com - Accept: application/json - IP-Address: 84.125.93.10 - - GET /edge-cloud-zones?filter=closest HTTP/1.1 - Host: example.com - Accept: application/json - Phone-Number: +441234567890 - ``` - - Example where API client is on a network-attached device: - - ``` - GET /edge-cloud-zones?filter=closest HTTP/1.1 - Host: example.com - Accept: application/json - ``` - - # Responses - - ## Success - - A JSON object is returned containing an array with a single member object. - This contains identifiers for the closest Edge Cloud Zone. The HTTP status - code will be`200 OK`. An example response: - - ``` - [ - { - "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66", - "edgeCloudZoneName": "example zone name", - "edgeCloudProvider": "example zone provider" - } - ] - ``` - * `edgeCloudZoneId` is a UUID for the Edge Cloud Zone. - * `edgeCloudZoneName` is the common name of the closest Edge Cloud Zone to - the user device. - * `edgeCloudProvider` is the name of the operator or cloud provider of - the Edge Cloud Zone. - - ## Errors - - If the authentication token is not valid, a `401 UNAUTHENTICATED` error is - returned. - - If the mobile subscription parameters contain a formatting error, a `400 - INVALID_ARGUMENT` error is returned. - - If the mobile subscription cannot be identified from the provided - parameters, a `404 NOT_FOUND` error is returned. - - Any more general service failures will result in an error in the `5xx`range - with an explanation. - - # Notes for Simple Edge Discovery API publishers - - If an `IP-Address` header parameter is provided then the operator should - assume the request is coming from a developer's server rather than a device - attached to the network. In which case the developer server is expected to - have been provided with the device public IP address (e.g. by the - application client on that device signalling it back to the server). - - If neither the `IP-Address parameter` nor any other device identifier is - provided in the API request header, then the operator should assume the - request is from a device attached to their network, and attempt to use the - public IP source address to determine which packet gateway issued it (and - hence the closest edge to that gateway). - - If no `IP-Address` header parameter is provided, but another device - identifier(s) is provided, then the operator should assume the request is - coming from a device attached to their network and should make use of one - or both of the public IP source address (from the IP packet header) and the - device identifier(s) provided in the HTTPS request header. - - # Authorization and authentication - - 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. - - # Further info and support - - --- - contact: - email: sp-edc@lists.camaraproject.org - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html -externalDocs: - description: Product documentation at CAMARA. - url: https://github.com/camaraproject/EdgeCloud - -servers: - - url: "{apiRoot}/{basePath}" - variables: - apiRoot: - default: https://localhost:443 - description: API root. - basePath: - default: simple-edge-discovery/v1 - description: Base path for the Simple Edge Discovery API. - -tags: - - name: Discovery - description: | - Find the closest Edge Cloud Zone to the user device. - -paths: - /edge-cloud-zones: - get: - security: - - openId: - - simple-edge-discovery:edge-cloud-zones:read - operationId: getEdgeCloudZones - parameters: - - name: filter - in: query - required: true - description: | - Filter the Edge Cloud Zones according to the parameter value. - For this API the only supported value is `closest`. - schema: - type: string - enum: - - closest - - - name: IPv4-Address - in: header - required: false - description: The public IPv4 address allocated to the device. - example: "84.125.93.10" - schema: - $ref: "#/components/schemas/SingleIpv4Addr" - - - name: IPv6-Address - in: header - required: false - description: The public IPv6 address allocated to the device. - example: "2001:db8:85a3:8d3:1319:8a2e:370:7348" - schema: - $ref: "#/components/schemas/DeviceIpv6Address" - - - name: Network-Access-Identifier - in: header - description: | - 3GPP network access identifier for the subscription - being used by the device. - example: "4d596ac1-7822-4927-a3c5-d72e1f922c94@domain.com" - required: false - schema: - $ref: "#/components/schemas/NetworkAccessIdentifier" - - - name: Phone-Number - in: header - example: "+441234567890" - required: false - description: | - MSISDN in E.164 format (starting with country code) of - the mobile subscription being used by the device. Optionally - prefixed with '+'. - schema: - $ref: "#/components/schemas/PhoneNumber" - - - name: X-Correlator - in: header - required: false - description: | - When the API Consumer includes the "X-Correlator" header in the - request, the API provider must include it in the response with - the same value that was used in the request. Otherwise, it is - optional to include the "X-Correlator" header in the response with - any valid value. Recommendation is to use UUID for values. - schema: - type: string - format: uuid - - responses: - "200": - description: | - Successful response, returning the closest Edge Cloud - Zone to the user device identified in the request header. - content: - application/json: - schema: - $ref: "#/components/schemas/EdgeCloudZones" - "400": - $ref: "#/components/responses/400BadRequest" - "401": - $ref: "#/components/responses/401Unauthorized" - "403": - $ref: "#/components/responses/403Forbidden" - "404": - $ref: "#/components/responses/404NotFound" - "405": - $ref: "#/components/responses/405MethodNotAllowed" - "406": - $ref: "#/components/responses/406Unacceptable" - "429": - $ref: "#/components/responses/429TooManyRequests" - "500": - $ref: "#/components/responses/500InternalServerError" - "502": - $ref: "#/components/responses/502BadGateway" - "503": - $ref: "#/components/responses/503ServiceUnavailable" - "504": - $ref: "#/components/responses/504GatewayTimeout" - tags: - - Discovery - summary: | - Returns the name of the Edge Cloud Zone closest to user device - identified in the request. - description: | - On receiving this request, the network will return the name - of the Edge Cloud Zone with the shortest network path to the end user - device identified in the request. - -components: - securitySchemes: - openId: - description: OpenID Provider Configuration Information. - type: openIdConnect - openIdConnectUrl: .well-known/openid-configuration - - headers: - X-Correlator: - description: | - When the API Consumer includes the "X-Correlator" header in the request, - the API provider must include it in the response with the same value t - hat was used in the request. Otherwise, it is optional to include the - "X-Correlator" header in the response with any valid value. - Recommendation is to use UUID for values. - required: false - schema: - type: string - format: uuid - - schemas: - EdgeCloudZones: - type: array - items: - $ref: "#/components/schemas/EdgeCloudZone" - minItems: 1 - description: | - A collection of Edge Cloud Zones. For this Simple Edge - Discovery API the collection will have at most one member (the closest - Edge Cloud Zone to the user device indicated in the request). - additionalProperties: false - - EdgeCloudZone: - type: object - description: | - An Edge Cloud Zone, uniquely identified by a combination - of the value of the Edge Resource Name object and the value of the - Provider object (the name of the cloud provider or operator hosting that - edge cloud zone). - properties: - edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" - edgeCloudZoneName: - $ref: "#/components/schemas/EdgeCloudZoneName" - edgeCloudProvider: - $ref: "#/components/schemas/EdgeCloudProvider" - - EdgeCloudZoneId: - description: | - Operator-issued UUID for the Edge Cloud Zone. - type: string - format: uuid - additionalProperties: false - - EdgeCloudZoneName: - description: | - Edge Cloud Zone Name - the common name for the Edge Cloud Zone. - type: string - additionalProperties: false - - EdgeCloudProvider: - description: | - The company name of the Edge Cloud Zone provider. - type: string - - ErrorResponse: - description: Error code and human-readable description. - type: object - properties: - code: - type: string - description: A short, human-readable summary of the problem type. - status: - type: integer - description: The HTTP status code. - message: - type: string - description: | - This parameter appears when there is an error. - A human readable explanation specific to this occurrence of the - problem. - - 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: "123456789@domain.com" - - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" - - 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 - - -################################### -# RESPONSES -#################################### - responses: - 400BadRequest: - description: Bad Request - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - InsufficientParameters: - description: | - Sufficient parameters must be specified to allow the - target UE to be identified. - value: - { - "code": "INVALID_ARGUMENT", - "status": 400, - "message": "Insufficient parameters: At least one of - Network-Access-Identifier, Phone-Number or IP-Address must be - specified, or, the API must be called by a client on a - network-attached device (hence passing the source IP in the - request header)." - } - InvalidExternalId: - value: - { - "code": "INVALID_ARGUMENT", - "status": 400, - "message": "Invalid Header Format: Network-Access-Identifier" - } - InvalidMSISDN: - value: - { - "code": "INVALID_ARGUMENT", - "status": 400, - "message": "Invalid Header Format: Phone-Number" - } - InvalidIP: - description: | - This error will be returned if the IP address does - not have a valid format, or if the IP address is a private IPv4 - address. - value: - { - "code": "INVALID_ARGUMENT", - "status": 400, - "message": "Invalid Header Format: IP-Address" - } - 401Unauthorized: - description: Unauthorized - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - InvalidCredentials: - value: - { - "code": "UNAUTHENTICATED", - "status": 401, - "message": "Request not authenticated due to missing, - invalid, or expired credentials" - } - - 403Forbidden: - description: Forbidden - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - InsufficientPermissions: - value: - { - "code": "PERMISSION_DENIED", - "status": 403, - "message": "Client does not have sufficient permissions - to perform this action" - } - - 404NotFound: - description: Subscriber Not Found - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - SubscriberNotFound: - description: | - No device found for the specified parameters, - meaning the closest Edge Cloud Zone cannot be determined. - value: - { - "code": "NOT_FOUND", - "status": 404, - "message": "No device found for the specified parameters" - } - - 405MethodNotAllowed: - description: Method Not Allowed - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - MethodNotAllowed: - description: | - An HTTP verb other than GET has been used to try - and access the resource. - value: - { - "code": "METHOD_NOT_ALLOWED", - "status": 405, - "message": "The request method is not supported by this - resource" - } - - 406Unacceptable: - description: Not Acceptable - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - NotAcceptable: - description: A response format other than JSON has been requested - value: - { - "code": "NOT_ACCEPTABLE", - "status": 406, - "message": "The server cannot produce a response matching the - content requested by the client through Accept-* headers" - } - - 429TooManyRequests: - description: Too Many Requests - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - TooManyRequests: - description: | - Access to the API has been temporarily blocked due - to quota or spike arrest limits being reached. - value: - { - "code": "TOO_MANY_REQUESTS", - "status": 429, - "message": "Either out of resource quota or reaching rate - limiting" - } - - 500InternalServerError: - description: Internal Server Error - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - { - "code": "INTERNAL", - "status": 500, - "message": "The service is currently not available" - } - - 502BadGateway: - description: Bad Gateway - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - { - "code": "BAD_GATEWAY", - "status": 502, - "message": "The service is currently not available" - } - - 503ServiceUnavailable: - description: Service Unavailable - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - { - "code": "UNAVAILABLE", - "status": 503, - "message": "The service is currently not available" - } - - 504GatewayTimeout: - description: Gateway Time-Out - headers: - X-Correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - { - "code": "TIMEOUT", - "status": 504, - "message": "The service is currently not available" - } - - diff --git a/code/API_definitions/README.MD b/code/API_definitions/README.MD deleted file mode 100644 index 80c37844..00000000 --- a/code/API_definitions/README.MD +++ /dev/null @@ -1,20 +0,0 @@ -These APIs are contributed by 5GFF: - -# MEC Experience Management and Exposure API -This API allows a developer to: -- discover available MEC platforms, ranked by proximity to a UE. -- read the state (availability and capabilities) of an operator's various MEC platforms. -- register a service profile (a description of the developer's edge service) with the MEC operator -- register the deployed service endpoints with the MEC operator, which allows the closest service endpoint to be discovered at runtime - -The API will also support the following capabilities: -- events(such as change of status of a MEC platform or another event which could affect their service) -- subscription to notification of events. - -Since events and subscription notifications can apply to many CAMARA APIs, that part will be defined in the Commonalities working group to ensure consistency. - -# Simple Discovery API -This API allows a client application to discover the closest MEC platform to the UE hosting the client application. 'Closest' means 'shorteset network path' as that will give the shortest propogation distance, which is a major factor in latency. - -# Traffic Influence API -The Traffic Influence API hides the complexity of the network providing the developer with the possibility to modify the connection policies of UEs and EAS in terms of how the traffic flows. For a 5G network, the UPF connected to the target Data Network can be updated with new traffic steering rules, for a set of users and for a specific time period. Furthermore, in a UE mobility scenario, the PDU Session Anchor, may be relocated to a different UPF considering the requirements provided by the AF. diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml similarity index 100% rename from code/API_definitions/Traffic Influence/Traffic_Influence.yaml rename to code/API_definitions/Traffic_Influence.yaml diff --git a/code/API_definitions/simple_edge_discovery.md b/code/API_definitions/simple_edge_discovery.md new file mode 100644 index 00000000..b2937bed --- /dev/null +++ b/code/API_definitions/simple_edge_discovery.md @@ -0,0 +1 @@ +Simple Edge Discovery code has now moved to its own repository: [Simple Edge Discovery](https://github.com/camaraproject/SimpleEdgeDiscovery) diff --git a/documentation/.DS_Store b/documentation/.DS_Store index cfda8ce8..f8e02251 100644 Binary files a/documentation/.DS_Store and b/documentation/.DS_Store differ diff --git a/documentation/MeetingMinutes/README.MD b/documentation/MeetingMinutes/README.MD index 37aa0ff4..0c4ec9bd 100644 --- a/documentation/MeetingMinutes/README.MD +++ b/documentation/MeetingMinutes/README.MD @@ -1 +1,3 @@ -This README.MD can be deleted when the first file is added to this directory. +# Minutes archive + +This folder contains the minutes archive for meetings held before the use of the LF Wiki to store minutes. Please refer to [https://wiki.camaraproject.org/display/CAM/Edge+Cloud](https://wiki.camaraproject.org/display/CAM/Edge+Cloud) for current and recent minutes. diff --git a/documentation/SupportingDocuments/.DS_Store b/documentation/SupportingDocuments/.DS_Store index 1e2e0581..27f95241 100644 Binary files a/documentation/SupportingDocuments/.DS_Store and b/documentation/SupportingDocuments/.DS_Store differ diff --git a/documentation/SupportingDocuments/API proposals/.DS_Store b/documentation/SupportingDocuments/API proposals/.DS_Store new file mode 100644 index 00000000..7db5b198 Binary files /dev/null and b/documentation/SupportingDocuments/API proposals/.DS_Store differ diff --git a/documentation/SupportingDocuments/DeveloperJourney-Proposal.md b/documentation/SupportingDocuments/API proposals/DeveloperJourney-Proposal.md similarity index 100% rename from documentation/SupportingDocuments/DeveloperJourney-Proposal.md rename to documentation/SupportingDocuments/API proposals/DeveloperJourney-Proposal.md diff --git a/documentation/SupportingDocuments/API proposals/Discovery/.DS_Store b/documentation/SupportingDocuments/API proposals/Discovery/.DS_Store new file mode 100644 index 00000000..46cc0509 Binary files /dev/null and b/documentation/SupportingDocuments/API proposals/Discovery/.DS_Store differ diff --git a/code/API_definitions/Discovery/MEC exposure and experience management.yaml b/documentation/SupportingDocuments/API proposals/Discovery/MEC exposure and experience management.yaml similarity index 100% rename from code/API_definitions/Discovery/MEC exposure and experience management.yaml rename to documentation/SupportingDocuments/API proposals/Discovery/MEC exposure and experience management.yaml diff --git a/code/API_definitions/Discovery/README.md b/documentation/SupportingDocuments/API proposals/Discovery/README.md similarity index 100% rename from code/API_definitions/Discovery/README.md rename to documentation/SupportingDocuments/API proposals/Discovery/README.md diff --git a/code/API_definitions/Resource Management/EdgeCloudApi_v0.0.5.yaml b/documentation/SupportingDocuments/API proposals/Resource Management/EdgeCloudApi_v0.0.5.yaml similarity index 100% rename from code/API_definitions/Resource Management/EdgeCloudApi_v0.0.5.yaml rename to documentation/SupportingDocuments/API proposals/Resource Management/EdgeCloudApi_v0.0.5.yaml diff --git a/code/API_definitions/Resource Management/README.MD b/documentation/SupportingDocuments/API proposals/Resource Management/README.MD similarity index 100% rename from code/API_definitions/Resource Management/README.MD rename to documentation/SupportingDocuments/API proposals/Resource Management/README.MD diff --git a/documentation/SupportingDocuments/API proposals/Traffic Influence/.DS_Store b/documentation/SupportingDocuments/API proposals/Traffic Influence/.DS_Store new file mode 100644 index 00000000..5008ddfc Binary files /dev/null and b/documentation/SupportingDocuments/API proposals/Traffic Influence/.DS_Store differ diff --git a/documentation/SupportingDocuments/Traffic Influence/APIproposal_Traffic Influence_TIM.md b/documentation/SupportingDocuments/API proposals/Traffic Influence/APIproposal_Traffic Influence_TIM.md similarity index 100% rename from documentation/SupportingDocuments/Traffic Influence/APIproposal_Traffic Influence_TIM.md rename to documentation/SupportingDocuments/API proposals/Traffic Influence/APIproposal_Traffic Influence_TIM.md diff --git a/documentation/SupportingDocuments/Traffic Influence/CAMARA Traffic Influence API.pdf b/documentation/SupportingDocuments/API proposals/Traffic Influence/CAMARA Traffic Influence API.pdf similarity index 100% rename from documentation/SupportingDocuments/Traffic Influence/CAMARA Traffic Influence API.pdf rename to documentation/SupportingDocuments/API proposals/Traffic Influence/CAMARA Traffic Influence API.pdf diff --git a/code/API_definitions/Traffic Influence/README.md b/documentation/SupportingDocuments/API proposals/Traffic Influence/README.md similarity index 100% rename from code/API_definitions/Traffic Influence/README.md rename to documentation/SupportingDocuments/API proposals/Traffic Influence/README.md diff --git a/documentation/SupportingDocuments/Traffic Influence/Traffic Influence first release delivery.pdf b/documentation/SupportingDocuments/API proposals/Traffic Influence/Traffic Influence first release delivery.pdf similarity index 100% rename from documentation/SupportingDocuments/Traffic Influence/Traffic Influence first release delivery.pdf rename to documentation/SupportingDocuments/API proposals/Traffic Influence/Traffic Influence first release delivery.pdf diff --git a/documentation/SupportingDocuments/CAMARA EdgeCloud Use Case MVP Proposal.pptx b/documentation/SupportingDocuments/API proposals/Use Case MVP proposal/CAMARA EdgeCloud Use Case MVP Proposal.pptx similarity index 100% rename from documentation/SupportingDocuments/CAMARA EdgeCloud Use Case MVP Proposal.pptx rename to documentation/SupportingDocuments/API proposals/Use Case MVP proposal/CAMARA EdgeCloud Use Case MVP Proposal.pptx diff --git a/code/API_definitions/Workload Orchestration/App.yaml b/documentation/SupportingDocuments/API proposals/Workload Orchestration/App.yaml similarity index 100% rename from code/API_definitions/Workload Orchestration/App.yaml rename to documentation/SupportingDocuments/API proposals/Workload Orchestration/App.yaml diff --git a/code/API_definitions/Workload Orchestration/README.md b/documentation/SupportingDocuments/API proposals/Workload Orchestration/README.md similarity index 100% rename from code/API_definitions/Workload Orchestration/README.md rename to documentation/SupportingDocuments/API proposals/Workload Orchestration/README.md diff --git a/code/API_definitions/Workload Orchestration/app-client.yaml b/documentation/SupportingDocuments/API proposals/Workload Orchestration/app-client.yaml similarity index 100% rename from code/API_definitions/Workload Orchestration/app-client.yaml rename to documentation/SupportingDocuments/API proposals/Workload Orchestration/app-client.yaml diff --git a/code/API_definitions/Workload Orchestration/edgexr-nb-openapi.yaml b/documentation/SupportingDocuments/API proposals/Workload Orchestration/edgexr-nb-openapi.yaml similarity index 100% rename from code/API_definitions/Workload Orchestration/edgexr-nb-openapi.yaml rename to documentation/SupportingDocuments/API proposals/Workload Orchestration/edgexr-nb-openapi.yaml diff --git a/code/API_definitions/Workload Orchestration/session.yaml b/documentation/SupportingDocuments/API proposals/Workload Orchestration/session.yaml similarity index 100% rename from code/API_definitions/Workload Orchestration/session.yaml rename to documentation/SupportingDocuments/API proposals/Workload Orchestration/session.yaml diff --git a/documentation/SupportingDocuments/API_Documentation/.DS_Store b/documentation/SupportingDocuments/API_Documentation/.DS_Store new file mode 100644 index 00000000..a4265044 Binary files /dev/null and b/documentation/SupportingDocuments/API_Documentation/.DS_Store differ diff --git a/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery.md b/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery.md deleted file mode 100644 index 307767ad..00000000 --- a/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery.md +++ /dev/null @@ -1,86 +0,0 @@ -# Overview -The Simple Edge Discovery API returns the name of the MEC platform ('operator edge site') closest to device from where the query was made. It requires the device to be connected to edge operator's network. - -# Introduction -This API provides a simple way to know which MEC platform is closest to the customer's device. Typically this MEC platform will support the best network performance between client and server, since propgation delay is minimised. Knowing which is the closest MEC platform allows: -1. an application client to proceed to connect to any application server hosted on that MEC platform, for which the IP address was provided when the instance was spun up using the cloud provider tools, -2. an application developer to spin up an instance of their application server on that MEC platform, using their cloud provider tools. - -Note that the Simple Edge Discovery API offers an advantage over geolocation. Instead it calculates the shortest network path between the device and the MEC platform, which is more accurate and takes into account internal operator network topology (which can vary greatly between networks). - -# Quick Start -1. Make a GET request to the API's /mecplatforms/ resource. -2. Query the JSON response with `$.MECPlatforms[0].ern` to return the cloud provider's name for the closest MEC platform -3. You can also check the status of the MEC platform using `$.MECPlatforms[0].status` - -_note, MECPlatforms is an array because the Simple Edge Discovery API is a subset of a more complex CAMARA API, 'MEC Exposure and Experiencve Management'. That API can return an array of MEC Platforms ranked according to proximity, compute resources, and load status. But the Simple Edge API will just return the closest. - -# Authentication and/or Authorization -Please follow the registration process of the operator implementing the API to acquire an authentication key, and bearer token. -'Closest MEC platform' is network information and not considered personally identifiable information (PII) - it is not expected that this API will require user consent. - - -# Endpoint definitions -- Endpoint: `/mecplatforms/` -- Method accepted: GET -- Parameters: none* -- HTTP codes: `200 OK` -- HTTP Response body: application/json - -## Constraints -The endpoint must be called by an HTTP client hosted by a device that is attached to the operator's network. If the operator only provides a cellular (mobile) edge platform, then the device must be attached to the operator's mobile network with a valid SIM. - -# Errors -`HTTP 401 Unauthorized` - ensure you have a valid API key and/or bearer token (see operator documentation) -`HTTP 404 Not Found` - check the URI for any syntax error - -# Code snippets - -`HTTP GET /MECPlatforms` - -`HTTP 200 OK application/json` - -```javascript -{ - "MECPlatforms": [ - { - "ern": "example London MEC name from cloud provider", - "zone": "geographic location of MEC Platform, e.g. London", - "region": "geographic region of MEC Platform, UK South", - "status": "active | inactive | unknown", - "properties": [ - { - "type": "string" - } - ] - } - ], - "links": [ - { - "link": { - "rel": "ListMECPlatforms", - "method": "get", - "href": "/mecplatforms" - } - } - ] -} - -``` - -Response processing: -`$.MECPlatforms[0].ern` -> "example London MEC name from cloud provider" -`$.MECPlatforms[0].status` -> one of `active`, `inactive`, `unknown` - -# FAQs -_Can I use the device GPS to locate the closest MEC?_ -_Can I ping the various MEC platforms and calculate the closest from that?_ -The answer to both of these is 'not reliably': -- Each device has an IP 'anchor point' in the operator mobile network which may be a significant distance from the location of the device itself. It is this path - IP anchor to MEC PLatform - that decides the shortest network path and hence shortest propagation delay. -- ping (both ICMP and TCP) fistly requires having deployed endpoints to ping - which may not be the case if the application server has not been deployed on more than on MEC platform. Secondly, mobile networks are volatile, and ping results will not give an accurate picture of the static network topology. - -# Release Notes -v1.1.2 minor bug fixes with error types - -# API Spec -YAML available at: https://github.com/camaraproject/EdgeCloud/blob/main/code/API_definitions/simple_edge_discovery.yaml diff --git a/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery_Documentation.md b/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery_Documentation.md new file mode 100644 index 00000000..f6239518 --- /dev/null +++ b/documentation/SupportingDocuments/API_Documentation/Simple_Edge_Discovery_Documentation.md @@ -0,0 +1,80 @@ +# Overview +The Simple Edge Discovery API returns the name, provider and UUID of the Edge Cloud Zone closest to a given device. The API call can be made either directly from the device, or from an Internet server. In either case, the device must be currently attached (connected) to the operator network. + +# Introduction +This API provides a simple way to know which Edge Cloud Zone is closest to the customer's device. Typically this Edge Cloud Zone will support the best network performance between client and server, since propgation delay is minimised. Knowing which is the closest Edge Cloud Zone allows: +1. an application client to proceed to connect to any application server hosted on that , for which the IP address was provided when the instance was spun up using the cloud provider tools, +2. an application developer to spin up an instance of their application server on that Edge Cloud Zone, using their cloud provider tools. + +Note that the Simple Edge Discovery API offers an advantage over geolocation. Instead it calculates the shortest network path between the device and the Edge Cloud Zone, which is more accurate and takes into account internal operator network topology (which can vary greatly between networks). + +# Quick Start +1. Make a GET request to `/edge-cloud-zones?filter=closest` +2. Query the JSON response with: +* `$.[0].edgeCloudZoneId` to return the UUID for the closest Edge Cloud Zone +* `$.[0].edgeCloudZoneName` to return the cloud provider's name for the closest Edge Cloud Zone +* `$.[0].edgeCloudProvider` to return the name of the cloud provider for the closest Edge Cloud Zone + +# Authentication and/or 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. + + +# Endpoint definitions +- Endpoint: `/edge-cloud-zones` +- Method accepted: GET +- Parameters: ?filter=closest* +- HTTP codes: `200 OK` +- HTTP Response body: application/json + +## Constraints +The device identified in the API request must be attached to the operator netwotk, otherwise the shortest network path from that device to each edge cloud zone cannot be calculated. + +# Errors +If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned. + +If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned. + +If the API call requires consent and permission hasnot been obtained , a `403 PERMISSION_DENIED` error is returned. + +If the mobile subscription cannot be identified from the provided parameters, a `404 NOT_FOUND` error is returned. + +Any more general service failures will result in an error in the `5xx` range with an explanation. + +Please see the YAML documentation (link below) for a full list of errors + +# Code snippets + +`HTTP GET /edge-cloud-zones?filter=closest` + +`HTTP 200 OK application/json` + +```javascript +[ + { + "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66", + "edgeCloudZoneName": "example zone name", + "edgeCloudProvider": "example zone provider" + } +] + +``` + +Response processing: +`$.[0].edgeCloudZoneId` -> "4gt555-6457-7890-d4he-1dc79f44gb66" +`$.[0].edgeCloudZoneName` -> example name" +`$.[0].edgeCloudProvider` -> "example zone provider" + +# FAQs +_Can I use the device GPS to locate the closest MEC?_ +_Can I ping the various Edge Cloud Zones and calculate the closest from that?_ +The answer to both of these is 'not reliably': +- Each device has an IP 'anchor point' in the operator mobile network which may be a significant distance from the location of the device itself. It is this path - IP anchor to Edge Cloud Zone - that decides the shortest network path and hence shortest propagation delay. +- ping (both ICMP and TCP) fistly requires having deployed endpoints to ping - which may not be the case if the application server has not been deployed on more than on Edge Cloud Zone. Secondly, mobile networks are volatile, and ping results will not give an accurate picture of the static network topology. + +# Release Notes +v1.0.0 to align with 1.0.0 YAML spec, May 1st 2024 + +# API Spec +YAML available at: https://github.com/camaraproject/EdgeCloud/blob/main/code/API_definitions/simple_edge_discovery.yaml diff --git a/documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md b/documentation/SupportingDocuments/API_Documentation/User Stories/Edge.Cloud.Lifecycle.Management.User.Story.md similarity index 100% rename from documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md rename to documentation/SupportingDocuments/API_Documentation/User Stories/Edge.Cloud.Lifecycle.Management.User.Story.md diff --git a/documentation/SupportingDocuments/User Stories/Simple Edge Discovery User Story.md b/documentation/SupportingDocuments/API_Documentation/User Stories/Simple Edge Discovery User Story.md similarity index 100% rename from documentation/SupportingDocuments/User Stories/Simple Edge Discovery User Story.md rename to documentation/SupportingDocuments/API_Documentation/User Stories/Simple Edge Discovery User Story.md diff --git a/documentation/SupportingDocuments/Traffic Influence/Userstory_Traffic Influence_TIM.md b/documentation/SupportingDocuments/API_Documentation/User Stories/Userstory_Traffic Influence_TIM.md similarity index 100% rename from documentation/SupportingDocuments/Traffic Influence/Userstory_Traffic Influence_TIM.md rename to documentation/SupportingDocuments/API_Documentation/User Stories/Userstory_Traffic Influence_TIM.md diff --git a/documentation/SupportingDocuments/About the Edge Cloud Group/.DS_Store b/documentation/SupportingDocuments/About the Edge Cloud Group/.DS_Store new file mode 100644 index 00000000..5564c49f Binary files /dev/null and b/documentation/SupportingDocuments/About the Edge Cloud Group/.DS_Store differ diff --git a/documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/.DS_Store b/documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/.DS_Store new file mode 100644 index 00000000..509ac172 Binary files /dev/null and b/documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/.DS_Store differ diff --git a/documentation/Minutes/MoM - Edge Selection sug-group 20230425.md b/documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/Minutes/MoM - Edge Selection sug-group 20230425.md similarity index 100% rename from documentation/Minutes/MoM - Edge Selection sug-group 20230425.md rename to documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/Minutes/MoM - Edge Selection sug-group 20230425.md diff --git a/documentation/SupportingDocuments/ProjectCharter_EdgeSelection_ApplicationLifecycle_Subgroup.md b/documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/ProjectCharter_EdgeSelection_ApplicationLifecycle_Subgroup.md similarity index 100% rename from documentation/SupportingDocuments/ProjectCharter_EdgeSelection_ApplicationLifecycle_Subgroup.md rename to documentation/SupportingDocuments/About the Edge Cloud Group/Edge Selection and lifecycle subgroup charter/ProjectCharter_EdgeSelection_ApplicationLifecycle_Subgroup.md diff --git a/documentation/SupportingDocuments/edge_terminology.md b/documentation/SupportingDocuments/Edge terminology/edge_terminology.md similarity index 100% rename from documentation/SupportingDocuments/edge_terminology.md rename to documentation/SupportingDocuments/Edge terminology/edge_terminology.md diff --git a/documentation/SupportingDocuments/CAMARA_EdgeCloud_Harmonising_APIs_First_intents_review.pdf b/documentation/SupportingDocuments/Harmonisation of APIs/CAMARA_EdgeCloud_Harmonising_APIs_First_intents_review.pdf similarity index 100% rename from documentation/SupportingDocuments/CAMARA_EdgeCloud_Harmonising_APIs_First_intents_review.pdf rename to documentation/SupportingDocuments/Harmonisation of APIs/CAMARA_EdgeCloud_Harmonising_APIs_First_intents_review.pdf