diff --git a/code/API_definitions/EdgeCloud_LcM.yaml b/code/API_definitions/Edge-Application-Management.yaml similarity index 54% rename from code/API_definitions/EdgeCloud_LcM.yaml rename to code/API_definitions/Edge-Application-Management.yaml index 31c095ef..fc4d6843 100644 --- a/code/API_definitions/EdgeCloud_LcM.yaml +++ b/code/API_definitions/Edge-Application-Management.yaml @@ -1,58 +1,74 @@ --- openapi: 3.0.3 info: - title: Edge Cloud API - version: 0.9.2 - description: | - Edge Cloud API for Life Cycle Management and discovery of an application. + title: Edge Application Management API + version: 0.9.3-wip + description: | + Edge Application Management API allows API consumers to manage the + Life Cycle of an Application and to Discover Edge Cloud Zones. + # 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. + # 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. 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. - * __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 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. - * __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 exists 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. - # API Functionality + The Edge Application Management API provides capabilities for lifecycle + management of application, instances and edge cloud zone discovery. + Lifecycle Management allows Application Provider to onboard + their application to the Edge Cloud 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 Edge Cloud + Platform, the Application Provider can instantiate the application. + Edge Cloud Provider helps Application Provider to decide where to + instantiate the applications allowing them to retrieve a list of + Edge Cloud 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 Edge Cloud Platform to instantiate the + application to one or several Edge Cloud Zones that meet the criteria. + Typically when more than one Edge Cloud Zone is required in the same + geographic boundary, Application Provider can define instead + the entire Edge Cloud Region. + + Application Provider can retrieve the information of the instances + for a given application, the information could be the Edge Cloud 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. + + # Quick Start + The usage of this API is based on several resources including GSMA + Edge Platform, Public Cloud and SDOs, to define a first approach on the + lifecycle management of application instances and edge cloud zones discovery + + Before starting to use the API, the developer needs to know about + the below specified details. + __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. + * __submitApp__ - Submits application details to an Edge Cloud Provider. + Based on the details provided, Edge Cloud Provider shall do bookkeeping, + resource validation and other pre-deployment operations. + * __deleteApp__ - Removes an application from an Edge Cloud Provider, + 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__ - * __createAppInstance__ 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. + * __createAppInstance__ Request the Edge Cloud Provider to instatiate + an instance of an application in a given Edge Cloud Zone, + if this parameter is not set, the Edge Cloud Provider will instantiate + the applications in all the Edge Cloud Zones. * __getAppInstance__ Retrieves the list with information of the instances related to a given application. * __deleteAppInstance__ - Removes a given application instance from an Edge @@ -62,10 +78,71 @@ info: * __getEdgeCloudZones__ List of the operators 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) + + # Authentication and Authorization + CAMARA guidelines defines a set of authorization flows which can grant API + clients access to the API functionality, as outlined in the document + [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject\ + /IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access\ + -and-user-consent.md). + Which specific authorization flows are to be used will be determined during + onboarding process, happening between the API Client and the Telco Edge + exposing the API, taking into account the declared purpose for accessing the + API, while also being subject to the prevailing legal framework dictated by + local legislation. + + It is important to remark that in cases where personal user data is + processed by the API, and users can exercise their rights through mechanisms + such as opt-in and/or opt-out, the use of 3-legged access tokens becomes + mandatory. This measure ensures that the API remains in strict compliance + with user privacy preferences and regulatory obligations, upholding the + principles of transparency and user-centric data control. + # API documentation + Two operations have been defined in Edge Application Management API. + + *__Application__* - The Application Provider submit application metadata to + the Edge Cloud Platform. The Edge Cloud Platform generates 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. + + Definitions of terminologies commonly referred + to throughout the API descriptions. + * __Application Provider__ - The provider of the application that accesses + an Edge Cloud Provider 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 Edge Cloud Provider, + 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. The Edge Cloud Platform generates a unique ID + for an Application that is ready to be instantiated. + * __Application Instance__ - Is an instance (VM or Container based) running + in an Edge Cloud Zone. The Edge Cloud Platform generates a unique ID + for each instance. + * __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, + this access is provided through the Edge Cloud Platform. + * __Edge Cloud Provider__ - Company name of the provider offering the + Edge Services through the Edge Cloud Platform. + Could be an Operator or a Cloud Provider. + * __Edge Cloud Region__ - An Edge Cloud 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. An Edge CloudRegion typically contains one or + multiple Edge Cloud Zones. + An Edge Cloud Region exists within an Edge Cloud. + * __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. + Edge Cloud Zones exists within a Edge Cloud Region. --- - termsOfService: http://swagger.io/terms/ contact: email: sp-edc@lists.camaraproject.org license: @@ -82,30 +159,33 @@ servers: default: http://localhost:443 description: API root basePath: - default: edge-cloud/v1 - description: Base path for the Edge Cloud API - -security: - - oAuth2ClientCredentials: - - nbi-mgmt + default: edge-application-management/vwip + description: Base path for the Edge Application Management API tags: - name: Application description: Application and Application Instance Lice Cycle Management - name: Edge Cloud - description: Edge Cloud Zones Available + description: Edge Cloud Zones Availability paths: /apps: post: - tags: + security: + - openId: + - edge-application-management:apps:write + tags: - Application - summary: Submit application metadata to the Operator Platform. - description: Contains the information about the application to be + summary: Submit application metadata to the Edge Cloud Provider. + description: | + Contains the information about the application to be instantiated in the Edge Cloud operationId: submitApp + parameters: + - $ref: '#/components/parameters/x-correlator' requestBody: - description: The Application Provider request contains mandatory + description: | + The Application Provider request contains mandatory criteria (e.g. required CPU, memory, storage, bandwidth) and optional parameters. content: @@ -117,11 +197,8 @@ paths: '201': description: Application created successfully headers: - Location: - description: Contains the URI of the newly created application. - required: true - schema: - type: string + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -147,34 +224,44 @@ paths: '501': $ref: '#/components/responses/501' '503': - $ref: '#/components/responses/503' + $ref: '#/components/responses/503' /apps/{appId}: get: + security: + - openId: + - edge-application-management:apps:read tags: - Application summary: Retrieve the information of an Application - description: Ask the OP the information for a given application + description: | + Ask the Edge Cloud Provider the information for a given application operationId: getApp parameters: + - $ref: '#/components/parameters/x-correlator' - name: appId - description: A globally unique identifier associated with the - application. OP generates this identifier when the application - is submitted over NBI. + description: | + A globally unique identifier associated with the + application. + Edge Cloud Provider generates this identifier when the application + is submitted. in: path required: true - schema: - $ref: '#/components/schemas/AppId' + schema: + $ref: '#/components/schemas/AppId' responses: '200': description: Information of Application - content: + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: application/json: schema: type: object properties: appManifest: - $ref: '#/components/schemas/AppManifest' + $ref: '#/components/schemas/AppManifest' '401': $ref: '#/components/responses/401' '403': @@ -186,23 +273,33 @@ paths: '503': $ref: '#/components/responses/503' delete: + security: + - openId: + - edge-application-management:apps:delete tags: - Application - summary: Delete an Application from an OP + summary: | + Delete an Application from an Edge Cloud Provider description: Delete all the information and content related to an Application operationId: deleteApp parameters: + - $ref: '#/components/parameters/x-correlator' - name: appId in: path - description: Identificator of the application to be - deleted provided by the OP NBI once the submission was successful + description: | + Identificator of the application to be + deleted provided by the Edge Cloud Provider + once the submission was successful required: true schema: $ref: "#/components/schemas/AppId" responses: '202': description: Request accepted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" '204': description: App deleted '400': @@ -230,23 +327,29 @@ paths: $ref: '#/components/responses/503' /apps/{appId}/instances: - post: + post: + security: + - openId: + - edge-application-management:instances:write tags: - Application summary: Instantiation of an Application - description: Ask the Edge Platform to instantiate an application to one + description: | + Ask the Edge Cloud Platform 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: createAppInstance parameters: + - $ref: '#/components/parameters/x-correlator' - name: appId - description: A globally unique identifier associated with the - application. Edge Platform generates this identifier when - the application is submitted over NBI. + description: | + A globally unique identifier associated with the + application. Edge Cloud Provider generates this identifier when + the application is submitted. in: path required: true schema: - $ref: '#/components/schemas/AppId' + $ref: '#/components/schemas/AppId' requestBody: description: Array of Edge Cloud Zone content: @@ -257,6 +360,14 @@ paths: responses: '202': description: Application instantiation accepted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + Location: + description: Contains the URI of the newly created application. + required: true + schema: + type: string content: application/json: schema: @@ -265,7 +376,7 @@ paths: appInstaces: type: array items: - $ref: '#/components/schemas/AppInstanceInfo' + $ref: '#/components/schemas/AppInstanceInfo' minItems: 1 '400': $ref: '#/components/responses/400' @@ -283,7 +394,7 @@ paths: status: 409 code: CONFLICT message: "Application already instantiated in the given - Edge Zone or Region" + Edge Cloud Zone or Edge Cloud Region" '500': $ref: '#/components/responses/500' '501': @@ -291,39 +402,51 @@ paths: '503': $ref: '#/components/responses/503' get: + security: + - openId: + - edge-application-management:instances:read tags: - Application summary: Retrieve the information of Application Instances for a given App - description: Ask the OP the information of the instances for a + description: | + Ask the Edge Cloud Provider the information of the instances for a given application operationId: getAppInstance parameters: + - $ref: '#/components/parameters/x-correlator' - name: appId - description: A globally unique identifier associated with - the application. OP generates this identifier when the - application is submitted over NBI. + description: | + A globally unique identifier associated with + the application. + Edge Cloud Provider generates this identifier when the + application is submitted. in: path required: true schema: - $ref: '#/components/schemas/AppId' + $ref: '#/components/schemas/AppId' - name: appInstanceId - description: A globally unique identifier associated with a running + description: | + A globally unique identifier associated with a running instance of an application within an specific Edge Cloud Zone. - OP generates this identifier. + Edge Cloud Provider generates this identifier. in: query required: false schema: - $ref: '#/components/schemas/AppInstanceId' + $ref: '#/components/schemas/AppInstanceId' - name: region - description: Human readable name of the geographical region of - the Edge Cloud. Defined by the OP. + description: | + Human readable name of the geographical Edge Cloud Region of + the Edge Cloud. Defined by the Edge Cloud Provider. in: query required: false schema: - $ref: '#/components/schemas/EdgeCloudRegion' + $ref: '#/components/schemas/EdgeCloudRegion' responses: '200': description: Information of Application Instances + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -346,32 +469,43 @@ paths: $ref: '#/components/responses/503' /apps/{appId}/instances/{appInstanceId}: delete: + security: + - openId: + - edge-application-management:instances:delete tags: - Application summary: Terminate an Application Instance - description: Terminate a running instance of an application within + description: | + Terminate a running instance of an application within an Edge Cloud Zone operationId: deleteAppInstance parameters: + - $ref: '#/components/parameters/x-correlator' - name: appId - description: A globally unique identifier associated with the - application. OP generates this identifier when the application - is submitted over NBI. + description: | + A globally unique identifier associated with the + application. Edge Cloud Provider generates this identifier + when the application is submitted. in: path required: true - schema: - $ref: '#/components/schemas/AppId' + schema: + $ref: '#/components/schemas/AppId' - name: appInstanceId in: path - description: Identificator of the specific application instance + description: | + Identificator of the specific application instance that will be terminated required: true schema: $ref: "#/components/schemas/AppInstanceId" responses: '202': - description: Request accepted to be processed. It applies for async + description: | + Request accepted to be processed. It applies for async deletion process + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" '204': description: Application Instance Deleted '400': @@ -388,35 +522,46 @@ paths: $ref: '#/components/responses/503' /edge-cloud-zones: get: + security: + - openId: + - edge-application-management:edge-cloud-zones:read tags: - Edge Cloud summary: Retrieve a list of the operators Edge Cloud Zones and their status - description: List of the operators Edge Cloud Zones and their + description: | + List of the operators Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown) operationId: getEdgeCloudZones parameters: + - $ref: '#/components/parameters/x-correlator' - name: region - description: Human readable name of the geographical region of - the Edge Cloud. Defined by the OP. + description: | + Human readable name of the geographical Edge Cloud Region of + the Edge Cloud. Defined by the Edge Cloud Provider. in: query required: false schema: - $ref: '#/components/schemas/EdgeCloudRegion' + $ref: '#/components/schemas/EdgeCloudRegion' - name: status + description: Human readable status of the Edge Cloud Zone in: query required: false schema: - $ref: '#/components/schemas/EdgeCloudZoneStatus' + $ref: '#/components/schemas/EdgeCloudZoneStatus' responses: '200': - description: Successful response, returning the + description: | + Successful response, returning the Available Edge Cloud Zones. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: '#/components/schemas/EdgeCloudZones' + $ref: '#/components/schemas/EdgeCloudZones' '401': $ref: '#/components/responses/401' '403': @@ -429,16 +574,33 @@ paths: $ref: '#/components/responses/503' components: securitySchemes: - oAuth2ClientCredentials: - type: oauth2 - flows: - clientCredentials: - tokenUrl: '/oauth2/token' - scopes: - nbi-mgmt: Access to the APIs + openId: + description: OpenID Provider Configuration Information. + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + x-correlator: + name: x-correlator + in: header + description: | + Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: | + Correlation id for the different services + required: false + schema: + type: string + format: uuid + schemas: AccessEndpoint: type: object + description: | + Application Endpoint for an especific instance that is + running in an specific Edge Cloud Zone. required: - port anyOf: @@ -454,11 +616,13 @@ components: fqdn: $ref: '#/components/schemas/Fqdn' ipv4Addresses: + description: IP version 4 of an application instance type: array items: $ref: '#/components/schemas/Ipv4Addr' minItems: 1 ipv6Addresses: + description: IP version 6 of an application instance. type: array items: $ref: '#/components/schemas/Ipv6Addr' @@ -467,14 +631,19 @@ components: AppId: type: string format: uuid - description: A globally unique identifier associated with the application. - OP generates this identifier when the application is submitted over NBI. + description: | + A globally unique identifier associated with the application. + Edge Cloud Platform generates this identifier when the + Application is submitted. AppInstanceId: type: string format: uuid - 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. + Edge Cloud Platform generates this identifier when the + instantiation in the Edge Cloud Zone is successful. AppInstanceInfo: description: Information about the application instance. @@ -486,15 +655,17 @@ components: description: Status of the application instance (default is 'unknown') type: string enum: - - ready - - instantiating - - failed - - terminating - - unknown - default: unknown + - ready + - instantiating + - failed + - terminating + - unknown + default: unknown componentEndpointInfo: - description: Information about the IP and Port exposed by the OP. - Application clients shall use these access points to reach this + description: | + Information about the IP and Port exposed by the + Edge Cloud Platform. + Application Client shall use these access points to reach this application instance type: array items: @@ -506,8 +677,9 @@ components: interfaceId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_]{6,30}[A-Za-z0-9]$ - description: This is the interface Identifier that app provider - defines when application is onboarded. + description: | + This is the interface Identifier that Application Provider + defines when application is being submitted. accessPoints: $ref: '#/components/schemas/AccessEndpoint' minItems: 1 @@ -515,7 +687,8 @@ components: $ref: '#/components/schemas/EdgeCloudZone' AppZones: - description: Collection of Edge Cloud Zones where the AP wants to + description: | + Collection of Edge Cloud Zones where the Application Provider wants to instantiate the application. type: array items: @@ -524,54 +697,63 @@ components: additionalProperties: false AppManifest: + description: | + Application information and requirements provided by the + Application Provider properties: name: type: string pattern: ^[A-Za-z][A-Za-z0-9_]{1,63}$ - description: Name of the application. + description: Name of the application. version: type: integer description: Application version information packageType: + description: Format of the application image package type: string enum: - QCOW2 - OVA - CONTAINER - - HELM + - HELM operatingSystem: $ref: '#/components/schemas/OperatingSystem' appRepo: + description: | + Repository where Application Provider stores the application image type: object required: - type - imagePath properties: - type: + type: type: string enum: - PRIVATEREPO - PUBLICREPO - description: Application repository and image URI information. + description: | + 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 + developer provided userName and password. Password is recommended to be the personal access token created by developer - e.g. in Github repo. + e.g. in Github repo. imagePath: $ref: '#/components/schemas/Uri' userName: type: string - description: Username to acces the Helm chart, docker-compose + description: | + Username to acces the Helm chart, docker-compose file or VM image repository credentials: type: string maxLength: 128 - description: Password or personal access token created by + description: | + 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. + password. authType: type: string enum: @@ -579,17 +761,20 @@ components: - HTTP_BASIC - HTTP_BEARER - NONE - description: The credentials can also be formatted as a Basic + description: | + The credentials can also be formatted as a Basic auth or Bearer auth in HTTP "Authorization" header. checksum: type: string - description: MD5 checksum for VM and file-based images, sha256 + description: | + MD5 checksum for VM and file-based images, sha256 digest for containers requiredResources: $ref: '#/components/schemas/RequiredResources' componentSpec: - description: Information defined in "appRepo" point to the application + description: | + 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 @@ -605,20 +790,21 @@ components: - componentName - networkInterfaces properties: - componentName: + componentName: type: string description: Component name must be unique with an application networkInterfaces: - description: Each application component exposes some ports + description: | + Each application component exposes some ports either for external users or for inter component communication. - Application provider is required to specify which ports are + 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. type: array - items: + items: type: object required: - interfaceId @@ -629,29 +815,33 @@ components: interfaceId: type: string pattern: ^[A-Za-z][A-Za-z0-9_]{3,31}$ - description: Each Port and corresponding traffic protocol - exposed by the component is identified by a name. + description: | + Each Port and corresponding traffic protocol + exposed by the component is identified by a name. Application client on user device requires this to - uniquley idenify the interface. + uniquley idenify the interface. protocol: type: string enum: - TCP - UDP - ANY - description: Defines the IP transport communication + description: | + Defines the IP transport communication protocol i.e., TCP, UDP or ANY port: type: integer format: int32 minimum: 1 maximum: 65535 - description: Port number exposed by the component. - OP may generate a dynamic port towards the - component instance which forwards external traffic - to the component port. + description: | + Port number exposed by the component. + Edge Cloud Provider may generate a dynamic port + towards the component instance which forwards + external traffic to the component port. visibilityType: - description: Defines whether the interface is exposed + description: | + 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 @@ -663,7 +853,7 @@ components: enum: - VISIBILITY_EXTERNAL - VISIBILITY_INTERNAL - minItems: 1 + minItems: 1 required: - name - version @@ -674,35 +864,41 @@ components: EdgeCloudProvider: type: string - description: Human readable name of the Edge Service Provider. - + description: Human readable name of the Edge Cloud Provider. + EdgeCloudRegion: type: string - description: Human readable name of the geographical region of - the Edge Cloud. Defined by the Edge Provider. - + description: | + Human readable name of the geographical Edge Cloud Region of + the Edge Cloud. Defined by the Edge Cloud Provider. + EdgeCloudZones: type: array items: $ref: '#/components/schemas/EdgeCloudZone' minItems: 1 - description: A collection of Edge Cloud Zones where the AP can + description: | + A collection of Edge Cloud Zones where the Application Provider can instantiate an Application Instance. additionalProperties: false EdgeCloudZoneId: type: string format: uuid - description: Identificator created by the Edge Platform. + description: | + Unique identifier created by the Edge Cloud Platform to identify an + Edge Cloud Zone within an Edge Cloud. EdgeCloudZone: type: object - description: An Edge Cloud Zone, uniquely identified by a + description: | + An Edge Cloud Zone, uniquely identified by a combination of the value of the Edge Cloud Zone Id object and the value of the Edge Cloud Provider - object. + object. This value is used to identify an Edge Cloud zone + between Edge Clouds from different Edge Cloud Providers. properties: - edgeCloudZoneId: + edgeCloudZoneId: $ref: '#/components/schemas/EdgeCloudZoneId' edgeCloudZoneName: $ref: '#/components/schemas/EdgeCloudZoneName' @@ -711,25 +907,27 @@ components: edgeCloudProvider: $ref: '#/components/schemas/EdgeCloudProvider' edgeCloudRegion: - $ref: '#/components/schemas/EdgeCloudRegion' + $ref: '#/components/schemas/EdgeCloudRegion' minItems: 1 - + EdgeCloudZoneName: type: string - description: Human readable name of the geographical zone of - the Edge Cloud. Defined by the Edge Provider. - + description: | + Human readable name of the geographical zone of + the Edge Cloud. Defined by the Edge Cloud Provider. + EdgeCloudZoneStatus: description: Status of the Edge Cloud Zone (default is 'unknown') type: string enum: - active - inactive - - unknown - default: unknown + - unknown + default: unknown ErrorInfo: type: object + description: Information about the error properties: status: type: integer @@ -747,8 +945,11 @@ components: Fqdn: type: string + description: | + Full qualified domain name of an application instance GpuInfo: type: object + description: Information about the supported GPUs required: - gpuMemory - numGPU @@ -759,25 +960,27 @@ components: numGPU: type: integer description: Number of GPUs - + 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])$ - example: 198.51.100.1 + format: ipv4 + example: "192.168.0.1" + description: | + IP of the device. A single IPv4 address may be specified in + dotted-quad form 1.2.3.4. Only this exact IP number will match the flow + control rule. Ipv6Addr: type: string - allOf: - - pattern: | - ^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0? - |([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))$ - - pattern: | - ^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))$ - example: 2001:db8:85a3::8a2e:370:7334 - + format: ipv6 + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: | + IP of the device. A single IPv6 address, following IETF 5952 + format, may be specified like 2001:db8:85a3:8d3:1319:8a2e:370:7344 + OperatingSystem: + description: | + Information about the Operating System of the application image type: object required: - architecture @@ -785,13 +988,15 @@ components: - version - license properties: - architecture: + architecture: + description: Type of the OS Architecture type: string enum: - x86_64 - x86 - example: x86_64 + example: x86_64 family: + description: Family to which OS belongs type: string enum: - RHEL @@ -800,6 +1005,7 @@ components: - WINDOWS - OTHER version: + description: Version of the OS type: string enum: - OS_VERSION_UBUNTU_2204_LTS @@ -807,6 +1013,7 @@ components: - OS_MS_WINDOWS_2022 - OTHER license: + description: License needed to activate the OS type: string enum: - OS_LICENSE_TYPE_FREE @@ -815,48 +1022,57 @@ components: Port: type: integer + description: Port to stablish the connection minimum: 0 RequiredResources: + description: | + Fundamental hardware requirements to be provisioned by the + Application Provider. type: object required: - numCPU - memory - storage properties: - numCPU: + numCPU: type: integer description: Number of virtual CPUs - example: 1 - memory: + example: 1 + memory: type: integer example: 10 description: Memory in giga bytes - storage: + storage: type: integer example: 60 description: Storage in giga bytes gpu: type: array + description: Number of GPUs items: $ref: '#/components/schemas/GpuInfo' - + SubmittedApp: description: Information about the submitted app type: object properties: appId: - $ref: '#/components/schemas/AppId' + $ref: '#/components/schemas/AppId' 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, + 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': description: Bad request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -864,9 +1080,12 @@ components: example: status: 400 code: INVALID_ARGUMENT - message: "Schema validation failed at ..." + message: "Schema validation failed at ..." '401': description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -877,6 +1096,9 @@ components: message: "Authorization failed: ..." '403': description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -887,6 +1109,9 @@ components: message: "Operation not allowed: ..." '404': description: Not Found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -897,6 +1122,9 @@ components: message: "Resource does not exist" '500': description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -907,6 +1135,9 @@ components: message: "Internal server error: ..." '501': description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -917,6 +1148,9 @@ components: message: "Service not implemented" '503': description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: diff --git a/documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md b/documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation_Obsolete.md similarity index 100% rename from documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation.md rename to documentation/SupportingDocuments/API_Documentation/EdgeCloud_LcM_Documentation_Obsolete.md