From 99cc87714b6f1a9b666bb8100ed655757cb44d36 Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Fri, 16 Feb 2024 11:18:31 +0100 Subject: [PATCH 1/8] Update EdgeCloud_LcM.yaml version 0.9.1 Adopted Edge Cloud Zone name. Adjusting errors detected in Linter for paths name for /app-instance and duplicated method which has been fixed including Delete method in /app-instance/{appId}. Method /app-instace/{appInstanceId} deleted. --- code/API_definitions/EdgeCloud_LcM.yaml | 78 +++++++++++++------------ 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/code/API_definitions/EdgeCloud_LcM.yaml b/code/API_definitions/EdgeCloud_LcM.yaml index fb879e4e..dc55aaa6 100644 --- a/code/API_definitions/EdgeCloud_LcM.yaml +++ b/code/API_definitions/EdgeCloud_LcM.yaml @@ -7,8 +7,8 @@ info: # Introduction APIs defined in this version of the specification can be categorized into the following areas: * __Application__ - The Application Provider submit application metadata to the Operator Platform. - * __Application Instance__ - An Operator Platform instantiate an Application on an Edge Cloud Node when the Application Provider resquest it. - * __Edge Cloud information__ - Retrieves all the Edge nodes available according to some defined parameters. + * __Application Instance__ - An Operator Platform instantiate an Application on an Edge Cloud Zone when the Application Provider resquest it. + * __Edge Cloud information__ - Retrieves all the Edge Cloud Zones available according to some defined parameters. # Relevant terms and definitions This section provides definitions of terminologies commonly referred to throughout the API descriptions. @@ -25,12 +25,12 @@ info: * __getApp__ - Retrieves the information of a given application. __Application Instance Management__ - * __appInstantiation__ Request the OP to instatiate an instance of an application in a given Edge Cloud Node, if this parameter is not set, the OP will instantiate the applications in all the Edge Cloud Nodes available. + * __appInstantiation__ Request the OP to instatiate an instance of an application in a given Edge Cloud Zone, if this parameter is not set, the OP will instantiate the applications in all the Edge Cloud Zones available. * __getAppInstance__ Retrieves the list with information of the instances related to a given application. - * __deleteAppInstance__ - Removes a given application instance from an Edge Cloud Node. + * __deleteAppInstance__ - Removes a given application instance from an Edge Cloud Zone. __Edge Cloud information__ - * __getEdgeCloudNodes__ List of the operator’s Edge Cloud Nodes and their status, ordering the results by location and filtering by status (active/inactive/unknown) + * __getEdgeCloudZones__ List of the operator’s Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown) # Further info and support (FAQs will be added in a later version of the documentation) @@ -40,7 +40,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.2.0 + version: 0.9.1 externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ @@ -65,15 +65,15 @@ tags: - name: Application Instance description: Application Instance Management - name: Edge Cloud - description: Edge Cloud Nodes Available + description: Edge Cloud Zones Available paths: - /appInstance: + /app-instance: post: tags: - Application Instance summary: Instantiation of an Application - description: Ask the OP to instantiate an application to one or several Edge Cloud Nodes with an Application as an input and an Application Instance as the output. + description: Ask the OP to instantiate an application to one or several Edge Cloud Zones with an Application as an input and an Application Instance as the output. operationId: appInstantiation requestBody: description: Details regarding where the application should be instantiated @@ -119,7 +119,7 @@ paths: $ref: '#/components/responses/501' '503': $ref: '#/components/responses/503' - /appInstance/{appId}: + /app-instance/{appId}: get: tags: - Application Instance @@ -139,14 +139,14 @@ paths: required: false schema: $ref: '#/components/schemas/AppInstanceId' - - name: edgeCloudName - description: Edge Cloud Node Name - an identifier for an edge cloud node in the operator domain + - name: EdgeCloudZone + description: An identifier name for an Edge Cloud Zone in the operator domain in: query required: false schema: - $ref: '#/components/schemas/EdgeCloudNodeName' + $ref: '#/components/schemas/EdgeCloudZone' - name: regionId - description: Human readable name of the geografical zone of the Edge Cloud Node. Defined by the OP. + description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. in: query required: false schema: @@ -176,17 +176,21 @@ paths: $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' - - /appInstance/{appInstanceId}: delete: tags: - Application Instance summary: Terminate an Application Instance - description: Terminate a running instance of an application within an Edge Cloud Node + description: Terminate a running instance of an application within an Edge Cloud Zone operationId: deleteAppInstance parameters: - - name: appInstanceId + - name: appId + description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. in: path + required: true + schema: + $ref: '#/components/schemas/AppId' + - name: appInstanceId + in: query description: Identificator of the specific application instance that will be terminated required: true schema: @@ -334,16 +338,16 @@ paths: '503': $ref: '#/components/responses/503' - /edge-cloud-nodes: + /edge-cloud-zones: get: tags: - Edge Cloud - summary: Retrieve a list of the operator’s Edge Clouds and their status - description: List of the operator’s Edge Clouds and their status, ordering the results by location and filtering by status (active/inactive/unknown) - operationId: getEdgeCloudNodes + summary: Retrieve a list of the operator’s Edge Cloud Zones and their status + description: List of the operator’s Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown) + operationId: getEdgeCloudZones parameters: - name: regionId - description: Human readable name of the geografical zone of the Edge Cloud. Defined by the OP. + description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. in: query required: false schema: @@ -355,13 +359,13 @@ paths: $ref: '#/components/schemas/Status' responses: '200': - description: Available Edge Cloud Nodes + description: Available Edge Cloud Zones content: application/json: schema: type: array items: - $ref: '#/components/schemas/EdgeCloudNodeDetails' + $ref: '#/components/schemas/EdgeCloudZoneDetails' minItems: 1 '401': $ref: '#/components/responses/401' @@ -399,8 +403,8 @@ components: properties: appId: $ref: '#/components/schemas/AppId' - edgeCloudNodeName: - $ref: '#/components/schemas/EdgeCloudNodeName' + EdgeCloudZone: + $ref: '#/components/schemas/EdgeCloudZone' regionId: $ref: '#/components/schemas/RegionId' required: @@ -516,8 +520,8 @@ components: properties: appInstanceId: $ref: '#/components/schemas/AppInstanceId' - edgeCloudNodeName: - $ref: '#/components/schemas/EdgeCloudNodeName' + EdgeCloudZone: + $ref: '#/components/schemas/EdgeCloudZone' status: description: Status of the application instance (default is 'unknown') type: string @@ -544,8 +548,8 @@ components: accessPoints: $ref: '#/components/schemas/AccessEndpoint' minItems: 1 - EdgeCloudNodeName: - description: Edge Cloud Node Name - an identifier for an edge cloud node in the operator domain + EdgeCloudZone: + description: An identifier name for an Edge Cloud Zone in the operator domain type: string AccessEndpoint: type: object @@ -608,13 +612,13 @@ components: - code - message - EdgeCloudNodeDetails: + EdgeCloudZoneDetails: type: object required: - geolocation properties: - edgeCloudNodeName: - $ref: '#/components/schemas/EdgeCloudNodeName' + EdgeCloudZone: + $ref: '#/components/schemas/EdgeCloudZone' status: $ref: '#/components/schemas/Status' region: @@ -660,10 +664,10 @@ components: RegionId: type: string - description: Human readable name of the geografical zone of the Edge Cloud Node. Defined by the OP. + description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. Status: - description: Status of the Edge Cloud Node (default is 'unknown') + description: Status of the Edge Cloud Zone (default is 'unknown') type: string enum: - active @@ -679,7 +683,7 @@ components: Uri: type: string example: https://charts.bitnami.com/bitnami/helm/example-chart:0.1.0 - description: A Uniform Resource Identifier (URI) as per RFC 3986, identifies the endpoint within an Edge Cloud Node where the user equipment may connect to the selected application instance + description: A Uniform Resource Identifier (URI) as per RFC 3986, identifies the endpoint within an Edge Cloud Zone where the user equipment may connect to the selected application instance responses: '400': From 09857fedbc8a34756e542aae28f4b8a0bacac8d6 Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Mon, 19 Feb 2024 13:06:53 +0100 Subject: [PATCH 2/8] Update EdgeCloud_LcM.yaml v0.9.1 Region and Edge Cloud Zone description updated. Parameters with UUID format have an Id at the end. Parameters with String format do not, that is why we decided to change RegionId to Region. --- code/API_definitions/EdgeCloud_LcM.yaml | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/EdgeCloud_LcM.yaml b/code/API_definitions/EdgeCloud_LcM.yaml index dc55aaa6..b127e716 100644 --- a/code/API_definitions/EdgeCloud_LcM.yaml +++ b/code/API_definitions/EdgeCloud_LcM.yaml @@ -15,9 +15,10 @@ info: * __Application Provider__ - The provider of the application that accesses an OP to deploy its application on the Edge Cloud. An Application Provider may be part of a larger organisation, like an enterprise, enterprise customer of an OP, or be an independent entity. * __Application__ - Contains the information about the application to be instantiated. Descriptor, binary image, charts or any other package assosiated with the application. The Application Provider request contains mandatory criteria (e.g. required CPU, memory, storage, bandwidth) defined in an Application. - * __OP__ - Operator Platform. An Operator Platform (facilitates access to the Edge Cloud and other capabilities of an Operator or federation of Operators and Partners. Defined by [GSMA in OPG.02](https://www.gsma.com/futurenetworks/wp-content/uploads/2023/07/OPG.02-v5.0-Operator-Platform-Requirements-and-Architecture.pdf) - * __Region__ - Human readable name of the geografical zone of the Edge Cloud. Defined by the OP. * __Edge Cloud__ - Cloud-like capabilities located at the network edge including, from the Application Provider's perspective, access to elastically allocated compute, data storage and network resources. + * __Edge Cloud Zone__ - An Edge Cloud Zone is the lowest level of abstraction exposed to an Application Provider who wants to deploy an Application on Edge Cloud. Zones exist within a Region. + * __OP__ - Operator Platform. An Operator Platform (facilitates access to the Edge Cloud and other capabilities of an Operator or federation of Operators and Partners. Defined by [GSMA in OPG.02](https://www.gsma.com/futurenetworks/wp-content/uploads/2023/07/OPG.02-v5.0-Operator-Platform-Requirements-and-Architecture.pdf) + * __Region__ - An OP Region is equivalent to a Region on a public cloud. The higher construct in the hierarchy exposed to an Application Provider who wishes to deploy an Application on the Edge Cloud and broadly represents a geography. A Region typically contains one or multiple Zones. A Region exists within an Edge Cloud. # API Functionality __Application Management__ * __submitApp__ - Submits an application details to an OP. Based on the details provided, OP shall do bookkeeping, resource validation and other pre-deployment operations. @@ -145,12 +146,12 @@ paths: required: false schema: $ref: '#/components/schemas/EdgeCloudZone' - - name: regionId + - name: region description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. in: query required: false schema: - $ref: '#/components/schemas/RegionId' + $ref: '#/components/schemas/Region' responses: '200': description: Information of Aplication Instances @@ -346,12 +347,12 @@ paths: description: List of the operator’s Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown) operationId: getEdgeCloudZones parameters: - - name: regionId + - name: region description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. in: query required: false schema: - $ref: '#/components/schemas/RegionId' + $ref: '#/components/schemas/Region' - name: status in: query required: false @@ -405,8 +406,8 @@ components: $ref: '#/components/schemas/AppId' EdgeCloudZone: $ref: '#/components/schemas/EdgeCloudZone' - regionId: - $ref: '#/components/schemas/RegionId' + region: + $ref: '#/components/schemas/Region' required: - appId @@ -549,7 +550,7 @@ components: $ref: '#/components/schemas/AccessEndpoint' minItems: 1 EdgeCloudZone: - description: An identifier name for an Edge Cloud Zone in the operator domain + description: Human readable name of the zone of the Edge Cloud. Defined by the OP. type: string AccessEndpoint: type: object @@ -622,7 +623,7 @@ components: status: $ref: '#/components/schemas/Status' region: - $ref: '#/components/schemas/RegionId' + $ref: '#/components/schemas/Region' minItems: 1 @@ -662,7 +663,7 @@ components: - OS_LICENSE_TYPE_ON_DEMAND - OTHER - RegionId: + Region: type: string description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. From 51d38cb504485038a16e7a26f56c180375a30c21 Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Tue, 20 Feb 2024 11:37:01 +0100 Subject: [PATCH 3/8] Update EdgeCloud_LcM.yaml Reorganization of the API structure to clean it up. --- code/API_definitions/EdgeCloud_LcM.yaml | 245 ++++++++++++------------ 1 file changed, 123 insertions(+), 122 deletions(-) diff --git a/code/API_definitions/EdgeCloud_LcM.yaml b/code/API_definitions/EdgeCloud_LcM.yaml index b127e716..d567bad5 100644 --- a/code/API_definitions/EdgeCloud_LcM.yaml +++ b/code/API_definitions/EdgeCloud_LcM.yaml @@ -6,9 +6,8 @@ info: Edge Cloud API for Life Cycle Management and discovery of an application. # Introduction APIs defined in this version of the specification can be categorized into the following areas: - * __Application__ - The Application Provider submit application metadata to the Operator Platform. - * __Application Instance__ - An Operator Platform instantiate an Application on an Edge Cloud Zone when the Application Provider resquest it. - * __Edge Cloud information__ - Retrieves all the Edge Cloud Zones available according to some defined parameters. + * __Application__ - The Application Provider submit application metadata to the Operator Platform. The OP generate an appId for that metadata that will be used to instantiate the application within the Edge Cloud Zone. + * __Edge Cloud information__ - Retrieves all the Edge Cloud Zones available according to some defined parameters where an application can be instantiated. # Relevant terms and definitions This section provides definitions of terminologies commonly referred to throughout the API descriptions. @@ -41,7 +40,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.9.1 + version: 0.9.2 externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ @@ -62,42 +61,38 @@ security: tags: - name: Application - description: Application Management - - name: Application Instance - description: Application Instance Management + description: Application and Application Instance Lice Cycle Management - name: Edge Cloud description: Edge Cloud Zones Available paths: - /app-instance: - post: - tags: - - Application Instance - summary: Instantiation of an Application - description: Ask the OP to instantiate an application to one or several Edge Cloud Zones with an Application as an input and an Application Instance as the output. - operationId: appInstantiation + /app: + post: + tags: + - Application + summary: Submit application metadata to the Operator Platform. + description: Contains the information about the application to be instantiated + operationId: submitApp requestBody: - description: Details regarding where the application should be instantiated + description: The Application Provider request contains mandatory criteria (e.g. required CPU, memory, storage, bandwidth) and optional parameters. content: application/json: schema: - $ref: '#/components/schemas/AppInstantiation' - required: true + $ref: '#/components/schemas/AppManifest' + required: true responses: - '202': - description: Application instantiation accepted + '201': + description: Application created successfully + headers: + Location: + description: Contains the URI of the newly created application. + required: true + schema: + type: string content: application/json: schema: - type: object - properties: - appId: - $ref: '#/components/schemas/AppId' - aplicationInstace: - type: array - items: - $ref: '#/components/schemas/AppInstanceInfo' - minItems: 1 + $ref: '#/components/schemas/SubmittedApp' '400': $ref: '#/components/responses/400' '401': @@ -113,20 +108,21 @@ paths: example: status: 409 code: CONFLICT - message: "Application already instantiated in the given Edge or Region" + message: "App duplicated" '500': $ref: '#/components/responses/500' '501': $ref: '#/components/responses/501' '503': - $ref: '#/components/responses/503' - /app-instance/{appId}: + $ref: '#/components/responses/503' + + /app/{appId}: get: tags: - - Application Instance - summary: Retrieve the information of Application Instances for a given App - description: Ask the OP the information of the instances for a given application - operationId: getAppInstance + - Application + summary: Retrieve the information of an Application + description: Ask the OP the information for a given application + operationId: getApp parameters: - name: appId description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. @@ -134,39 +130,16 @@ paths: required: true schema: $ref: '#/components/schemas/AppId' - - name: appInstanceId - description: A globally unique identifier associated with a running instance of an application. OP generates this identifier. - in: query - required: false - schema: - $ref: '#/components/schemas/AppInstanceId' - - name: EdgeCloudZone - description: An identifier name for an Edge Cloud Zone in the operator domain - in: query - required: false - schema: - $ref: '#/components/schemas/EdgeCloudZone' - - name: region - description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. - in: query - required: false - schema: - $ref: '#/components/schemas/Region' responses: '200': - description: Information of Aplication Instances + description: Information of Aplication content: application/json: schema: type: object properties: appId: - $ref: '#/components/schemas/AppId' - aplicationInstace: - type: array - items: - $ref: '#/components/schemas/AppInstanceInfo' - minItems: 1 + $ref: '#/components/schemas/AppManifest' '401': $ref: '#/components/responses/401' '403': @@ -179,28 +152,23 @@ paths: $ref: '#/components/responses/503' delete: tags: - - Application Instance - summary: Terminate an Application Instance - description: Terminate a running instance of an application within an Edge Cloud Zone - operationId: deleteAppInstance + - Application + summary: Delete an Application from an OP + description: Delete all the information and content related to an Application + operationId: deleteApp parameters: - name: appId - description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. in: path - required: true - schema: - $ref: '#/components/schemas/AppId' - - name: appInstanceId - in: query - description: Identificator of the specific application instance that will be terminated + description: Identificator of the application to be deleted provided by the OP NBI once the submission was successful required: true schema: - $ref: "#/components/schemas/AppInstanceId" + $ref: "#/components/schemas/AppId" + responses: '202': - description: Request accepted to be processed. It applies for async deletion process + description: Request accepted '204': - description: Application deleted + description: App deleted '400': $ref: '#/components/responses/400' '401': @@ -209,38 +177,57 @@ paths: $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 409 + code: CONFLICT + message: "App with a running application instance cannot be deleted" '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' - /app: - post: - tags: + /app/{appId}/instance: + post: + tags: - Application - summary: Submit application metadata to the Operator Platform. - description: Contains the information about the application to be instantiated - operationId: submitApp + summary: Instantiation of an Application + description: Ask the OP to instantiate an application to one or several Edge Cloud Zones with an Application as an input and an Application Instance as the output. + operationId: appInstantiation + parameters: + - name: appId + description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. + in: path + required: true + schema: + $ref: '#/components/schemas/AppId' requestBody: - description: The Application Provider request contains mandatory criteria (e.g. required CPU, memory, storage, bandwidth) and optional parameters. + description: Details regarding where the application should be instantiated content: application/json: schema: - $ref: '#/components/schemas/AppManifest' - required: true + $ref: '#/components/schemas/AppInstantiation' + required: true responses: - '201': - description: Application created successfully - headers: - Location: - description: Contains the URI of the newly created application. - required: true - schema: - type: string + '202': + description: Application instantiation accepted content: application/json: schema: - $ref: '#/components/schemas/SubmittedApp' + type: object + properties: + appId: + $ref: '#/components/schemas/AppId' + aplicationInstace: + type: array + items: + $ref: '#/components/schemas/AppInstanceInfo' + minItems: 1 '400': $ref: '#/components/responses/400' '401': @@ -256,20 +243,19 @@ paths: example: status: 409 code: CONFLICT - message: "App duplicated" + message: "Application already instantiated in the given Edge Zone or Region" '500': $ref: '#/components/responses/500' '501': $ref: '#/components/responses/501' '503': - $ref: '#/components/responses/503' - /app/{appId}: + $ref: '#/components/responses/503' get: tags: - Application - summary: Retrieve the information of an Application - description: Ask the OP the information for a given application - operationId: getApp + summary: Retrieve the information of Application Instances for a given App + description: Ask the OP the information of the instances for a given application + operationId: getAppInstance parameters: - name: appId description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. @@ -277,16 +263,39 @@ paths: required: true schema: $ref: '#/components/schemas/AppId' + - name: appInstanceId + description: A globally unique identifier associated with a running instance of an application. OP generates this identifier. + in: query + required: false + schema: + $ref: '#/components/schemas/AppInstanceId' + - name: EdgeCloudZone + description: An identifier name for an Edge Cloud Zone in the operator domain + in: query + required: false + schema: + $ref: '#/components/schemas/EdgeCloudZone' + - name: region + description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. + in: query + required: false + schema: + $ref: '#/components/schemas/Region' responses: '200': - description: Information of Aplication + description: Information of Aplication Instances content: application/json: schema: type: object properties: appId: - $ref: '#/components/schemas/AppManifest' + $ref: '#/components/schemas/AppId' + aplicationInstace: + type: array + items: + $ref: '#/components/schemas/AppInstanceInfo' + minItems: 1 '401': $ref: '#/components/responses/401' '403': @@ -300,22 +309,27 @@ paths: delete: tags: - Application - summary: Delete an Application from an OP - description: Delete all the information and content related to an Application - operationId: deleteApp + summary: Terminate an Application Instance + description: Terminate a running instance of an application within an Edge Cloud Zone + operationId: deleteAppInstance parameters: - name: appId + description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. in: path - description: Identificator of the application to be deleted provided by the OP NBI once the submission was successful required: true + schema: + $ref: '#/components/schemas/AppId' + - name: appInstanceId + in: query + description: Identificator of the specific application instance that will be terminated + required: false schema: - $ref: "#/components/schemas/AppId" - + $ref: "#/components/schemas/AppInstanceId" responses: '202': - description: Request accepted + description: Request accepted to be processed. It applies for async deletion process '204': - description: App deleted + description: Application deleted '400': $ref: '#/components/responses/400' '401': @@ -324,16 +338,6 @@ paths: $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' - '409': - description: Conflict - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 409 - code: CONFLICT - message: "App with a running application instance cannot be deleted" '500': $ref: '#/components/responses/500' '503': @@ -402,15 +406,12 @@ components: description: Attributes with information where to instantiate a given application type: object properties: - appId: - $ref: '#/components/schemas/AppId' EdgeCloudZone: $ref: '#/components/schemas/EdgeCloudZone' region: $ref: '#/components/schemas/Region' required: - - appId - + - region AppManifest: properties: name: From aeb5c65fcb33b2cf7d960d8b9e3cd6db9f00d24b Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Mon, 26 Feb 2024 17:35:31 +0100 Subject: [PATCH 4/8] Update EdgeCloud_LcM.yaml Added "Provider" parameter to edgeCloudZone and adapted related methods. Spelling and camelCase corrections. --- code/API_definitions/EdgeCloud_LcM.yaml | 31 +++++++++++++------------ 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/EdgeCloud_LcM.yaml b/code/API_definitions/EdgeCloud_LcM.yaml index d567bad5..88032984 100644 --- a/code/API_definitions/EdgeCloud_LcM.yaml +++ b/code/API_definitions/EdgeCloud_LcM.yaml @@ -264,19 +264,13 @@ paths: schema: $ref: '#/components/schemas/AppId' - name: appInstanceId - description: A globally unique identifier associated with a running instance of an application. OP generates this identifier. + description: A globally unique identifier associated with a running instance of an application within an specific Edge Cloud Zone. OP generates this identifier. in: query required: false schema: $ref: '#/components/schemas/AppInstanceId' - - name: EdgeCloudZone - description: An identifier name for an Edge Cloud Zone in the operator domain - in: query - required: false - schema: - $ref: '#/components/schemas/EdgeCloudZone' - name: region - description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. + description: Human readable name of the geographical region of the Edge Cloud. Defined by the OP. in: query required: false schema: @@ -352,7 +346,7 @@ paths: operationId: getEdgeCloudZones parameters: - name: region - description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. + description: Human readable name of the geographical region of the Edge Cloud. Defined by the OP. in: query required: false schema: @@ -406,7 +400,7 @@ components: description: Attributes with information where to instantiate a given application type: object properties: - EdgeCloudZone: + edgeCloudZone: $ref: '#/components/schemas/EdgeCloudZone' region: $ref: '#/components/schemas/Region' @@ -522,7 +516,7 @@ components: properties: appInstanceId: $ref: '#/components/schemas/AppInstanceId' - EdgeCloudZone: + edgeCloudZone: $ref: '#/components/schemas/EdgeCloudZone' status: description: Status of the application instance (default is 'unknown') @@ -550,9 +544,17 @@ components: accessPoints: $ref: '#/components/schemas/AccessEndpoint' minItems: 1 + EdgeCloudZone: - description: Human readable name of the zone of the Edge Cloud. Defined by the OP. - type: string + type: object + properties: + name: + type: string + description: Human readable name of the zone of the Edge Cloud. Defined by the OP. + provider: + type: string + description: Human readable name of the edge cloud provider company (e.g. telco operator, hyperscaler). + AccessEndpoint: type: object required: @@ -579,7 +581,6 @@ components: items: $ref: '#/components/schemas/Ipv6Addr' minItems: 1 - Ipv4Addr: type: string pattern: ^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$ @@ -666,7 +667,7 @@ components: Region: type: string - description: Human readable name of the geografical region of the Edge Cloud. Defined by the OP. + description: Human readable name of the geographical region of the Edge Cloud. Defined by the OP. Status: description: Status of the Edge Cloud Zone (default is 'unknown') From c52d99fc5dae390b9694d523aaca189827d33590 Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Thu, 7 Mar 2024 18:09:38 +0100 Subject: [PATCH 5/8] Edge Cloud LCM API documentation First version of the Edge Cloud LCM API documentation. --- .../EdgeCloud_LcM_Documentation.md | 473 ++++++++++++++++++ 1 file changed, 473 insertions(+) create mode 100644 documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md diff --git a/documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md b/documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md new file mode 100644 index 00000000..f96c1b33 --- /dev/null +++ b/documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md @@ -0,0 +1,473 @@ + + + +# Edge Cloud API +## Overview + +The reference scenario foresees a distributed Telco Edge Cloud where any Application Delevoper, known as an Application Provider, can host and deploy their application according to their specifications and operational criteria (e.g. within an specific geographical zone for data protection purposes, ensure a minimum QoS for the application clients, etc). Through Telco Edge Cloud services Developers around the globe can be benefit from the traditional Cloud strengths but expertise and advantages of the Mobile Network Operators offering to their users an evolved experience for XR, V2X, Holographic and other new services. + +## 1. Introduction +The Edge Cloud LcM API provides capabilities for lifecycle management of application instances and edge discovery. + +Lifecycle Management allows Application Provider to onboard their application details to the Operator Platform which do bookkeeping, resource validation and other pre-deployment operations. Application details can contain components network specification , package type (QCOW2, OVA, CONTAINER, HELM), operating system details and respository to download the image of the desired application. + +Once the application is available on the Operator Platform, the Application Provider can instantiate the application. OP helps AP to decide where to instantiate the applications allowing them to retrieve a list of Edge Zones that meets the provided criteria. This discovery can be filtered by an specific geographical region (e.g when data residency is need) and by status (active, inactive, unknown). + +Application Provider can ask the operator to instantiate the application to one or several Edge Zones that meet the criteria. Typically when more than one Edge Zone is required in the same geographic boundary, AP can define instead the entire Region. AP can retrieve the information of the instances for a given application, the information could be the Edge Zone where the instance is, status (ready, instantiating, failed, terminating, unknown) and endpoint (ip, port, fqdn). + +Application Provider can terminate an instance of an application (appInstanceId) or all the instances for a given appId. + +## 2. Quick Start + +The usage of the Edge Cloud LcM is based on several resources including GSMA Operator Platform, Public Cloud and SDOs, to define a first approach on the lifecycle management of application instances and edge discovery. + +Before starting to use the API, the developer needs to know about the below specified details. + +Two operations have been defined in Edge Cloud LcM API. + +**Application** - The Application Provider submit application metadata to the Operator Platform. The OP generate an appId for that metadata that will be used to instantiate the application within the Edge Cloud Zone. + +**Edge Cloud** - Retrieves all the Edge Cloud Zones available according to some defined parameters where an application can be instantiated. + + +# Introduction + +**Application** +The Application Provider submit application metadata to the Operator Platform. + +**Application Instance** +An Operator Platform instantiate an Application on an Edge Cloud Node when the Application Provider resquest it. + +**Edge Cloud information** +Retrieves all the Edge nodes available according to some defined parameters. + +# Relevant terms and definitions +This section provides definitions of terminologies commonly referred to throughout the API descriptions. + +**Application Provider** +The provider of the application that accesses an OP to deploy its application on the Edge Cloud. An Application Provider may be part of a larger organisation, like an enterprise, enterprise customer of an OP, or be an independent entity. + +**Application** +Contains the information about the application to be instantiated. Descriptor, binary image, charts or any other package assosiated with the application. The Application Provider request contains mandatory criteria (e.g. required CPU, memory,storage, bandwidth) defined in an Application. + +**Edge Cloud** +Cloud-like capabilities located at the network edge including, from the Application Provider's perspective, access to elastically allocated compute, data storage and network resources. + +**Edge Cloud Zone** +An Edge Cloud Zone is the lowest level of abstraction exposed to an Application Provider who wants to deploy an Application on Edge Cloud. Zones exist within a Region. + + +**OP** +Operator Platform. An Operator Platform (facilitates access to the Edge Cloud and other capabilities of an Operator or federation of Operators and Partners. ^[1] + +**Region** +An OP Region is equivalent to a Region on a public cloud. The higher construct in the hierarchy exposed to an Application Provider who wishes to deploy an Application on the Edge Cloud and broadly represents a geography. A Region typically contains one or multiple Zones. A Region exists within an Edge Cloud. + +### Application Management + +**submitApp** +Submits an application details to an OP. Based on the details provided, OP shall do bookkeeping, resource validation and other pre-deployment operations. + +**deleteApp** +Removes an application from an OP, if there is a running instance of the given application, the request cannot be done. + +**getApp** +Retrieves the information of a given application. + +### Application Instance Management + +**appInstantiation** +Request the OP to instatiate an instance of an application in a given Edge Cloud Zone, if this parameter is not set, the OP will instantiate the applications in all the Edge Cloud Zones available. + +**getAppInstance** +Retrieves the list with information of the instances related to a given application. + +**deleteAppInstance** +Removes a given application instance from an Edge Cloud Zone. + +### Edge Cloud information + +**getEdgeCloudZones** +List of the operator’s Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown). + +## Further info and support + +(FAQs will be added in a later version of the documentation) + +## 3. Authentication and Authorization +TBD + +## 4. API Documentation +## 4.1 API Version + +0.9.2 + + +**License:** [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) + +[Product documentation at Camara](https://github.com/camaraproject/) +### + +## 4.2 Details + +#### POST /app +##### Summary + +Submit application metadata to the Operator Platform. + +##### Description + +The Application Provider request contains in the body an Aplication Manifest see AppManifest in model section. + +##### Responses + +If the request is correct a 201 code will be obtained along with an appId to be used in other methods to obtain information or to generate app instances. + +| Code | Description | +| ---- | ----------- | +| 201 | Application created successfully | +| 400 | Bad request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 409 | Conflict | +| 500 | An unknow error has occurred | +| 501 | Not Implemented +| 503 | Service unavailable | + + +##### GET /app/{appId}/ +##### Summary + +Ask the OP the information for a given application. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| appId| path | A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI | yes | string | + +##### Responses + +If the request is correct a 200 code will be obtained along with an Aplication Manifest see AppManifest in model section. + +| Code | Description | +| ---- | ----------- | +| 200 | OK | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | The specified resource was not found | +| 500 | An unknow error has occurred | +| 503 | Service unavailable | + + +##### DELETE /app/{appId}/ +##### Summary + +Delete all the information and content related to an Application + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| appId | path | Identificator of the application to be deleted provided by the OP NBI once the submission was successful | yes | string | + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 202 | Request accepted | +| 204 | App deleted | +| 400 | Bad request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Not Found | +| 409 | Conflict | +| 500 | Internal Server Error | +| 503 | Service unavailable | + +##### POST /app/{appId}/instance +##### Summary + +Ask the OP to instantiate an application to one or several Edge Cloud Zones with an Application as an input and an Application Instance as the output. + +##### Description + +Details regarding where the application should be instantiated + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| appId | path | A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. | yes | string | + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 202 | Application instantiation accepted | +| 400 | Bad request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 409 | Conflict | +| 500 | An unknow error has occurred | +| 501 | Not Implemented +| 503 | Service unavailable | + + +##### GET /app/{appId}/instance +##### Summary + +Ask the OP the information of the instances for a given application. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| appId| path | A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI | yes | string | +| appInstanceId| query | A globally unique identifier associated with a running instance of an application. OP generates this identifier. | no | string | +| region| query | Human readable name of the geografical region of the Edge Cloud. Defined by the OP. | no | string | + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | Information of Aplication Instances | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | The specified resource was not found | +| 500 | An unknow error has occurred | +| 503 | Service unavailable | + + +##### DELETE /app/{appId}/instance +##### Summary + +Terminate a running instance of an application within an Edge Cloud Zone + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| appId | path | Identificator of the application to be deleted provided by the OP NBI once the submission was successful | yes | string | +| appInstanceId | query | Identificator of the specific application instance that will be terminated | no | string | + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 202 | Request accepted to be processed. It applies for async deletion process | +| 204 | App deleted | +| 400 | Bad request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Not Found | +| 500 | Internal Server Error | +| 503 | Service unavailable | + + + +#### GET /edge-cloud-zones +##### Summary + +Retrieve a list of the operator’s Edge Cloud Zones and their status + +##### Description +List of the operator’s Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown). + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| region | query | Human readable name of the geografical region of the Edge Cloud. Defined by the OP. | no | string | +| status | query | _Available values_ : active, inactive, unknown Default value : unknown | no | string | + + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | Available Edge Cloud Zones | +| 401 | Unauthorized | +| 403 | Unauthorized | +| 404 | Not Found | +| 500 | Internal Server Error | +| 503 | Service unavailable | + + +### Models + +#### AppId + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| appId | string | A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. | yes | + +#### AppInstanceId + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| appInstanceId | string | A globally unique identifier associated with a running instance of an application. OP generates this identifier. | Yes | + +#### AppInstantiation + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| appInstantiation | string | Attributes with information where to instantiate a given application | yes | +| edgeCloudZone | string | Human readable name of the zone of the Edge Cloud. Defined by the OP. | no | +| region | string | Human readable name of the geografical region of the Edge Cloud. Defined by the OP. | yes | + +#### EdgeCloudZone +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| name | string | Human readable name of the zone of the Edge Cloud. Defined by the OP. | no | +| provider | integer | Human readable name of the edge cloud provider company (e.g. telco operator, hyperscaler).| no | + + +#### AppManifest + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| name | string | Name of the application. | yes | +| version | integer | Application version information| no | +| packageType | string |[ QCOW2, OVA, CONTAINER, HELM ] | no | +| operatingSystem | string | more details in the specific table| no | +| appRepo | object |more details in the specific table | yes | +| componentSpec | array | Information defined in "appRepo" point to the application descriptor e.g. Helm chart, docker-compose yaml file etc. The descriptor may contain one or more containers and their associated meta-data. A component refers to additional details about these containers to expose the instances of the containers to external client applications. App provider can define one or more components (via the associated network port) in componentSpec corresponding to the containers in helm charts or docker-compose yaml file as part of app descriptors. | yes| +version | integer | Application version information | no | + +#### OperatingSystem + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| arquitecture | string | [ x86_64, x86 ]| yes | +| family | string | [ RHEL, UBUNTU, COREOS, WINDOWS, OTHER ]| yes | +| version | string | [OS_VERSION_UBUNTU_2204_LTS, OS_VERSION_RHEL_8, OS_MS_WINDOWS_2022, OTHER]| yes | +| license | string | [OS_LICENSE_TYPE_FREE, OS_LICENSE_TYPE_ON_DEMAND, OTHER ] | yes | + +#### AppRepo + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| type | string | Application repository and image URI information. PUBLICREPO is used of public urls like github, helm repo etc. PRIVATEREPO is used for private repo managed by the application developer. Private repo can be accessed by using the app developer provided userName and password. Password is recommended to be the personal access token created by developer e.g. in Github repo. [ PRIVATEREPO, PUBLICREPO ]. | yes | +| imagePath | string | example: https://charts.bitnami.com/bitnami/helm/example-chart:0.1.0 A Uniform Resource Identifier (URI) as per RFC 3986, identifies the endpoint within an Edge Cloud Zone where the user equipment may connect to the selected application instance| yes | +| userName | string | Username to acces the Helm chart, docker-compose file or VM image repository | no | +| credentials | string | maxLength: 128 Password or personal access token created by developer to acces the app repository. API users can generate a personal access token e.g. docker clients to use them as password | no | +| authType | string | The credentials can also be formatted as a Basic auth or Bearer auth in HTTP "Authorization" header.[ DOCKER, HTTP_BASIC, HTTP_BEARER, NONE ] | no | +| checksum | string |MD5 checksum for VM and file-based images, sha256 digest for containers | no | + +#### ComponentSpec + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| componentName | string | Component name must be unique with an application | yes | +| networkInterfaces | array | Each application component exposes some ports either for external users or for inter component communication. Application provider is required to specify which ports are to be exposed and the type of traffic that will flow through these ports.The underlying platform may assign a dynamic port against the "extPort" that the application clients will use to connect with edge application instance. | yes | + +#### networkInterfaces + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| interfaceId | string | Each application component exposes some ports either for external users or for inter component communication. Application provider is required to specify which ports are to be exposed and the type of traffic that will flow through these ports.The underlying platform may assign a dynamic port against the "extPort" that the application clients will use to connect with edge application instance. | yes | +| protocol | string | Defines the IP transport communication protocol i.e., TCP, UDP or ANY | yes | +| port | integer | Port number exposed by the component. OP may generate a dynamic port towards the component instance which forwards external traffic to the component port. | yes | +| visibilityType | string | Defines whether the interface is exposed to outer world or not i.e., external, or internal.If this is set to "external", then it is exposed to external applications otherwise it is exposed internally to edge application components within edge cloud. When exposed to external world, an external dynamic port is assigned for UC traffic and mapped to the extPort | yes | + + + +#### AppInstanceInfo +Information about the application instance. + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| appInstanceId | string | A globally unique identifier associated with a running instance of an application. OP generates this identifier. | no | +| edgeCloudZone | string |Human readable name of the zone of the Edge Cloud. Defined by the OP. | no | +| status | string |Status of the application instance (default is 'unknown')[ ready, instantiating, failed, terminating, unknown ]| no | +| componentEndpointInfo | object |Information about the IP and Port exposed by the OP. Application clients shall use these access points to reach this application instance | no | + +#### ComponentEndpointInfo + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| interfaceId | string |This is the interface Identifier that app provider defines when application is onboarded. | yes | +| accessPoints | object | object | | yes | + +#### AccessPoints + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| port | integer | Port number exposed by the component. OP may generate a dynamic port towards the component instance which forwards external traffic to the component port. | yes | +| fqdn | string | | yes | +| ipv4Addr | string | IPv4 address may be specified in form
as: - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. | | +| ipv6Addr | string | IPv6 address, following IETF 5952 format, may be specified in form
as: - address - The /128 subnet is optional for single addresses: - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 | | +| anyOf | string | | yes | + +#### ErrorInfo + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| status | integer | HTTP status code returned along with this error response | yes | +| code | string | Code given to this error | yes | +| message | string | Detailed error description | yes | + +#### EdgeCloudZoneDetails +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| edgeCloudZone | string | Human readable name of the zone of the Edge Cloud. Defined by the OP. | | +| status | string | Status of the Edge Cloud Zone (default is 'unknown')[ active, inactive, unknown ]| | +| region | string | Human readable name of the geografical region of the Edge Cloud. Defined by the OP. | | + +#### SubmittedApp +Information about the submitted app + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| appId | string | A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. | | + +#### Uri +example: https://charts.bitnami.com/bitnami/helm/example-chart:0.1.0 + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| uri | string | A Uniform Resource Identifier (URI) as per RFC 3986, identifies the endpoint within an Edge Cloud Zone where the user equipment may connect to the selected application instance | | + +### 4.3 Errors + +Since CAMARA Edge Cloud LCM API is based on REST design principles and blueprints, well defined HTTP status codes and families specified by community are followed [[2]](#2). + +Details of HTTP based error/exception codes for Edge Cloud LCM API are described in Section 4.2 of each API REST based method. +Following table provides an overview of common error names, codes, and messages applicable to Edge Cloud LCM API. + +| No | Error Name | Error Code | Error Message | +| --- | ---------- | ---------- | ------------- | +|1 |400 | INVALID_ARGUMENT | "Client specified an invalid argument, request body or query param" | +|2 |401 | UNAUTHORIZED | "Request not authorized due to missing, invalid, or expired credentials" | +|3 |403 | FORBIDDEN | "Client does not have sufficient permissions to perform this action" | +|4 |404 | NOT FOUND | "The specified resource was not found" | +|5 |409 | CONFLICT | "Conflict with an existing resource" | +|6 |500 | INTERNAL | "Internal Server Error" | +|7 |501 | NOT_IMPLEMENTED | "Service not implemented" | +|8 |503 | UNAVAILABLE | "Service unavailable" | +|9 |504 | TIMEOUT | "Request timeout exceeded. Try later." | + +### 4.4 Policies + +N/A + +### 4.5 Code Snippets + +N/A +### 4.6 FAQ's + +(FAQs will be added in a later version of the documentation) + +### 4.7 Terms + +N/A + +### 4.8 Release Notes + +TBD + +## References + +[1] [GSMA OPG Operator Platform Requirements](https://www.gsma.com/futurenetworks/wp-content/uploads/2023/07/OPG.02-v5.0-Operator-Platform-Requirements-and-Architecture.pdf) +[2] [HTTP Status codes spec](https://restfulapi.net/http-status-codes/) From a3056843677f44a865e78c2661f7fb68541024a9 Mon Sep 17 00:00:00 2001 From: Jhon Javier Loza Lluco <150795747+javierlozallu@users.noreply.github.com> Date: Mon, 25 Mar 2024 15:56:03 +0100 Subject: [PATCH 6/8] Edge Cloud LCM API User Story --- ...e.Cloud.Lifecycle.Management.User.Story.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md diff --git a/documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md b/documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md new file mode 100644 index 00000000..df17649a --- /dev/null +++ b/documentation/SupportingDocuments/API_Documentation/Edge.Cloud.Lifecycle.Management.User.Story.md @@ -0,0 +1,82 @@ + +Edge Cloud Lifecycle Management User Story +_This document is based on the [CAMARA Commonalities template for User Stories](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md)_ +_Roles are referenced from the ITU-T Cloud Refence Architecture._ + +## Summary +"As an Application Developer, I want to determine the Edge Cloud Zone more suitable for my application, being aware of all the options available their status and region of interest. +I want to be able to put my application available in the selected Edge Cloud Zone or Region in a simpler manner providing both artifacts and metadata for instantiating my application succesfully at the same time I want to be able to terminate +running instances of my application on a particular Edge Zone or Region and also to remove information of the whole application itself ". + +This story includes the whole journey from discovering Edge Cloud Zones available to run instances of the application and terminate them : + + +## Actors, Roles, and Scope +| Actor | Role | Scope | +|-------|------|-------| +|Application Provider (AP) |API Consumer | API requester | +|Operator Platform (OP)|Edge Cloud Provider | API Publisher | +|Edge Infrastructure Provider (EIP)|Edge Cloud Provider| + +Note the role of Edge Cloud Provider may be played by either the Operator or a Hyperscaler. + +## Pre-conditions +The AP has a resource usage agreement with the Operator Platform + +| Item | Description | Support Qualifier | +|----|----|----| +|Summary|Network operators offers a Multi-access Edge Computing platform in a given territory with several levels of abstraction being the Edge Cloud Zone the lowest one. Network operators offers a service through EdgeCloud APIs that permits application providers to deploy instances of an application in one or several Edge Cloud Zones, and to Applications Users the posibility to chose the most appropriate Edge Cloud Zone available at a given moment| M | +|Pre-conditions|The AP has a resource usage agreement with the Operator Platform| M | +|Begins when|The Application Provider (AP) invokes the EdgeCloud API to submit at application with references to obtain all needed data for their instantiation (container images or VM images and manifests describing required resources by an application)| M | +|Step 1|The OP authorizes the request (terminates with a notification to the AP if it is not valid)| M | +|Step 2|The OP validates the request (terminates with a notification to the AP if content is not valid)| M| +|Step 3|The OP stores the app information and returns an Id for reference (terminates with a notification to the AP if error)| M | +|Step 4|The OP request information of currently available Edge Cloud Zones and Regions and their status| M | +|Step 4|The AP invokes the EdgeCloud API to instantiate the application in a given Region, it can also include an specific Edge Cloud Zone referencing previously generated appId | M | +|Step 5|The OP validates the request and if AppId and parameters provided are valid, returns an object including references to one instance Id per Edge Cloud Zone with an instantiation status "instantiating" and starts deploying app instance in EdgeCloud Zones that meet the input criteria| M | +|Step 6|The AP may request updated information of existing app instances of a given app. Possible status for app instantiation includes "ready" also information for endpoint info is provided for the app instance| O | +|Step 7|App instance may provide service for end users | O | +|Step 8|The AP request termination of one app instance (optionally all app instances in a given region) | M | +|Step 8|The OP validates the request (terminates with a notification to the UE if content is not valid e.g. given appId does not exist)| M| +|Step 9|The OP response to the AP and starts the termination of the app instance, moving its status to terminating| M| +|Step 10|The UE connects to the provided EAS and start using the application| M| +|Ends when|The UE connects to the EAS| M | +|Post-conditions|The UE is connected to the most adequate EAS, it may request to reconnect (repeat Step 10) at any time if the perceived quality is not adequate| M | +|Exceptions|