diff --git a/code/API_definitions/edge-application-management.yaml b/code/API_definitions/edge-application-management.yaml index 4cb475f..e57d320 100644 --- a/code/API_definitions/edge-application-management.yaml +++ b/code/API_definitions/edge-application-management.yaml @@ -87,9 +87,11 @@ info: removing all associated instances. __Edge Cloud information__ - * __getEdgeCloudZones__ List of the operators Edge Cloud Zones and their - status, ordering the results by location and filtering by status - (active/inactive/unknown) + * __getEdgeCloudZones__ Paginated list of the operators Edge Cloud Zones, + including their status, geographical country code and, when applicable, + the Kubernetes clusters available within each zone. Results can be + filtered by country code, Edge Cloud Provider, Edge Cloud + Provider-specific region and status. @@ -201,8 +203,6 @@ tags: description: Application and Application Instance Lice Cycle Management - name: Edge Cloud description: Edge Cloud Zones Availability - - name: Cluster - description: Kubernetes Cluster information - name: App Instance CALLBACK Operation description: Operations for handling application instance callback notifications - name: App Deployment CALLBACK Operation @@ -942,106 +942,82 @@ paths: code: ABORTED message: "Update conflict" - /clusters: + /edge-cloud-zones: get: security: - openId: - - edge-application-management:clusters:read + - edge-application-management:edge-cloud-zones:read tags: - - Cluster - summary: | - Retrieve a list of the available clusters filtered by the optional - query parameters. + - Edge Cloud + summary: Retrieve a paginated list of the provider's Edge Cloud Zones description: | - List available cluster information - operationId: getClusters + List of the provider's Edge Cloud Zones, including their status and, + when applicable, the Kubernetes clusters available within each zone. + Results can be filtered by country code, Edge Cloud Provider, + Edge Cloud Provider-specific region and status, and are returned as + a paginated collection. + operationId: getEdgeCloudZones parameters: - $ref: "#/components/parameters/x-correlator" - - name: region + - $ref: "../common/CAMARA_common.yaml#/components/parameters/page" + - $ref: "../common/CAMARA_common.yaml#/components/parameters/perPage" + - name: countryCode description: | - Human readable name of the geographical Edge Cloud Region of - the Cluster. Defined by the Edge Cloud Provider. + ISO 3166-1 alpha-2 country code to filter Edge Cloud Zones by + their geographical location, independent of any Edge Cloud + Provider-specific region naming. in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudRegion" - - name: clusterRef + $ref: "#/components/schemas/CountryCode" + - name: edgeCloudProvider description: | - A globally unique identifier for the Cluster. + Human readable name of the Edge Cloud Provider to filter Edge + Cloud Zones by. in: query required: false schema: - $ref: "#/components/schemas/KubernetesClusterRef" - - name: edgeCloudZoneId - description: | - Edge Cloud Zone identifier. - in: query - required: false - schema: - $ref: "#/components/schemas/EdgeCloudZoneId" - responses: - "200": - description: | - Successful response, returning the cluster's information. - Returns an empty list if no clusters were found or none match - the specified query parameters. - headers: - x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/ClusterInfo" - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - /edge-cloud-zones: - get: - security: - - openId: - - edge-application-management:edge-cloud-zones:read - tags: - - Edge Cloud - summary: Retrieve a list of the provider's Edge Cloud Zones and their status - description: | - List of the provider's 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 + $ref: "#/components/schemas/EdgeCloudProvider" + - name: edgeCloudRegion description: | - Human readable name of the geographical Edge Cloud Region of - the Edge Cloud. Defined by the Edge Cloud Provider. + Edge Cloud Provider-specific geographical region name to filter + Edge Cloud Zones by. Since this value is not standardized across + Edge Cloud Providers, prefer filtering by countryCode when + provider-independent results are needed. in: query required: false schema: $ref: "#/components/schemas/EdgeCloudRegion" - name: status - description: Human readable status of the Edge Cloud Zone + description: | + Status of the Edge Cloud Zone to filter by. If omitted, Edge + Cloud Zones are returned regardless of their status. in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudZoneStatus" + type: string + enum: + - active + - inactive + - unknown responses: "200": description: | - Successful response, returning the - Available Edge Cloud Zones. + Successful response, returning a paginated list of the Edge + Cloud Zones matching the specified query parameters. headers: x-correlator: $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + x-total-count: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-count" + x-total-pages: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-pages" + link: + $ref: "../common/CAMARA_common.yaml#/components/headers/link" content: application/json: schema: - $ref: "#/components/schemas/EdgeCloudZones" + $ref: "#/components/schemas/EdgeCloudZoneList" "400": $ref: "#/components/responses/Generic400" "401": @@ -1116,7 +1092,7 @@ components: - PERMISSION_DENIED examples: GENERIC_403_PERMISSION_DENIED: - description: Permission denied. OAuth2 token access does not have the required scope + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED @@ -1735,26 +1711,24 @@ components: ClusterInfo: type: object - description: Kubernetes cluster information + description: | + Kubernetes cluster information. Returned nested within the Edge + Cloud Zone it belongs to, so identifiers already provided by the + enclosing Edge Cloud Zone (zone id, region) are not repeated here. required: - name - - provider + - edgeCloudProvider - clusterRef - - edgeCloudZoneId properties: name: type: string maxLength: 64 description: | - Name of the Cluster, scoped to the Provider - provider: - $ref: "#/components/schemas/AppProvider" + Name of the Cluster, scoped to the Edge Cloud Provider + edgeCloudProvider: + $ref: "#/components/schemas/EdgeCloudProvider" clusterRef: $ref: "#/components/schemas/KubernetesClusterRef" - edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" - edgeCloudRegion: - $ref: "#/components/schemas/EdgeCloudRegion" version: type: string maxLength: 64 @@ -1768,6 +1742,17 @@ components: $ref: "#/components/schemas/KubernetesNodePool" minItems: 1 + CountryCode: + type: string + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + description: | + ISO 3166-1 alpha-2 country code representing the geographical + location of the Edge Cloud Zone, independent of any Edge Cloud + Provider-specific region naming. + example: "GB" + EdgeCloudProvider: type: string maxLength: 64 @@ -1780,15 +1765,22 @@ components: 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 - maxItems: 100 + EdgeCloudZoneList: + type: object description: | - A collection of Edge Cloud Zones where the Application Provider can - instantiate an Application Instance. + A paginated collection of Edge Cloud Zones where the Application + Provider can instantiate an Application Instance. + required: + - edgeCloudZones + - pagination + properties: + edgeCloudZones: + type: array + maxItems: 100 + items: + $ref: "#/components/schemas/EdgeCloudZone" + pagination: + $ref: "../common/CAMARA_common.yaml#/components/schemas/Pagination" EdgeCloudZoneId: type: string @@ -1812,6 +1804,7 @@ components: - edgeCloudZoneId - edgeCloudZoneName - edgeCloudProvider + - countryCode properties: edgeCloudZoneId: $ref: "#/components/schemas/EdgeCloudZoneId" @@ -1823,6 +1816,17 @@ components: $ref: "#/components/schemas/EdgeCloudProvider" edgeCloudRegion: $ref: "#/components/schemas/EdgeCloudRegion" + countryCode: + $ref: "#/components/schemas/CountryCode" + clusters: + description: | + Kubernetes clusters available within this Edge Cloud Zone, when + applicable. Omitted or empty if the Edge Cloud Provider does not + offer Kubernetes clusters in this zone. + type: array + maxItems: 100 + items: + $ref: "#/components/schemas/ClusterInfo" EdgeCloudZoneName: type: string diff --git a/code/Test_definitions/edge-application-management-getClusters.feature b/code/Test_definitions/edge-application-management-getClusters.feature deleted file mode 100644 index d231de2..0000000 --- a/code/Test_definitions/edge-application-management-getClusters.feature +++ /dev/null @@ -1,83 +0,0 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getClusters - # Input to be provided by the implementation to the tester - # - # Implementation indications: - # * apiRoot: API root of the server URL - # - # Testing assets: - # * An available cluster to get information - # - # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml - Background: Common getClusters setup - Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/clusters" - And the header "Content-Type" is set to "application/json" - And the header "Authorization" is set to a valid access token - And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator" - # Success scenarios - #/clusters GET 200 - @eam_getClusters_01_generic_success_scenario - Scenario: Get information of existing clusters - Given There are at least one cluster available - When the request "getClusters" is sent - Then the response status code is 200 - And the response header "Content-Type" is "application/json" - And the response header "x-correlator" has same value as the request header "x-correlator" - And A list of clusters is returned - And the response body complies with the OAS schema at "/components/schemas/ClusterInfo" - #/clusters GET 200 filtered by region - @eam_getClusters_02_generic_success_scenario_filtered_by_region - Scenario: Get information of existing clusters with optional parameters ("region") - Given There are at least one cluster available - And the request query parameter "$.region" is set to a valid region - When the request "getClusters" is sent - Then the response status code is 200 - And the response header "Content-Type" is "application/json" - And the response header "x-correlator" has same value as the request header "x-correlator" - And information of clusters of "$.region" is returned - And the response body complies with the OAS schema at "/components/schemas/ClusterInfo" - #/clusters GET 200 filtered by edgeCloudZoneId - @eam_getClusters_03_generic_success_scenario_filtered_by_edgeCloudZone - Scenario: Get information of existing clusters with optional parameters ("edgeCloudZoneId") - Given There are at least one cluster available - And the request query parameter "$.edgeCloudZoneId" is set to a valid edgeCloudZoneId - When the request "getClusters" is sent - Then the response status code is 200 - And the response header "Content-Type" is "application/json" - And the response header "x-correlator" has same value as the request header "x-correlator" - And information of clusters of "$.edgeCloudZoneId" is returned - And the response body complies with the OAS schema at "/components/schemas/ClusterInfo" - #/clusters GET 200 filtered by clusterRef - @eam_getClusters_04_generic_success_scenario_filtered_by_clusterRef - Scenario: Get information of existing clusters with optional parameters ("clusterRef") - Given There are at least one cluster available - And the request query parameter "$.clusterRef" is set to a valid clusterRef - When the request "getClusters" is sent - Then the response status code is 200 - And the response header "Content-Type" is "application/json" - And the response header "x-correlator" has same value as the request header "x-correlator" - And information of clusters of "$.edgeCloudZoneId" is returned - And the response body complies with the OAS schema at "/components/schemas/ClusterInfo" - #Errors - # Error 401 - @eam_getClusters_401.1_missing_access_token - Scenario: Missing access token - Given the header "Authorization" is not included - When the request "getClusters" is sent - Then the response status code is 401 - And the response header "x-correlator" has same value as the request header "x-correlator" - And the response header "Content-Type" is "application/json" - And the response property "$.status" is 401 - And the response property "$.code" is "UNAUTHENTICATED" - And the response property "$.message" contains a user friendly text - # Errors 403 - @eam_getClusters_403.1_missing_access_token_scope - Scenario: Missing access token scope - Given the header "Authorization" is set to an access token that does not include the required scope - When the request "getClusters" is sent - Then the response status code is 403 - And the response header "x-correlator" has same value as the request header "x-correlator" - And the response header "Content-Type" is "application/json" - And the response property "$.status" is 403 - And the response property "$.code" is "PERMISSION_DENIED" - And the response property "$.message" contains a user friendly text diff --git a/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature b/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature index 6da9841..909689e 100644 --- a/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature +++ b/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature @@ -5,7 +5,8 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getEdgeCloudZo # * apiRoot: API root of the server URL # # Testing assets: - # * An available edge Cloud Zones to get information + # * An available edge Cloud Zones to get information, at least one of which + # has Kubernetes clusters available # # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getEdgeCloudZones setup @@ -17,28 +18,52 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getEdgeCloudZo # Success scenarios #/edge-cloud-zones GET 200 @eam_getEdgeCloudZones_01_generic_success_scenario - Scenario: Get information of existing edge cloud zones + Scenario: Get a paginated list of existing edge cloud zones Given There are at least one Edge Cloud Zones available When the request "getEdgeCloudZones" is sent Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And A list of Edge Cloud Zones is returned - And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZones" - #/edge-cloud-zones GET 200 filtered by region - @eam_getEdgeCloudZones_02_generic_success_scenario_filtered_by_region - Scenario: Get information of existing Edge Cloud Zones with optional parameters ("region") + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + And the response property "$.edgeCloudZones" is a list of Edge Cloud Zones + And the response property "$.pagination" is present and complies with the OAS schema at "/components/schemas/Pagination" + And any Edge Cloud Zone with Kubernetes clusters includes them in the "$.edgeCloudZones[].clusters" property + #/edge-cloud-zones GET 200 filtered by countryCode + @eam_getEdgeCloudZones_02_success_scenario_filtered_by_countryCode + Scenario: Get information of existing Edge Cloud Zones with optional parameter ("countryCode") Given There are at least one Edge Cloud Zones available - And the request query parameter "$.region" is set to a valid region + And the request query parameter "$.countryCode" is set to a valid ISO 3166-1 alpha-2 country code When the request "getEdgeCloudZones" is sent Then the response status code is 200 And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" - And information of Edge Cloud Zones of "$.region" is returned - And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZones" + And information of Edge Cloud Zones with "$.countryCode" is returned + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + #/edge-cloud-zones GET 200 filtered by edgeCloudProvider + @eam_getEdgeCloudZones_03_success_scenario_filtered_by_edgeCloudProvider + Scenario: Get information of existing Edge Cloud Zones with optional parameter ("edgeCloudProvider") + Given There are at least one Edge Cloud Zones available + And the request query parameter "$.edgeCloudProvider" is set to a valid Edge Cloud Provider name + When the request "getEdgeCloudZones" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And information of Edge Cloud Zones of "$.edgeCloudProvider" is returned + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + #/edge-cloud-zones GET 200 filtered by edgeCloudRegion + @eam_getEdgeCloudZones_04_success_scenario_filtered_by_edgeCloudRegion + Scenario: Get information of existing Edge Cloud Zones with optional parameter ("edgeCloudRegion") + Given There are at least one Edge Cloud Zones available + And the request query parameter "$.edgeCloudRegion" is set to a valid Edge Cloud Provider-specific region name + When the request "getEdgeCloudZones" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And information of Edge Cloud Zones of "$.edgeCloudRegion" is returned + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" #/edge-cloud-zones GET 200 filtered by status - @eam_getEdgeCloudZones_03_generic_success_scenario_filtered_by_status - Scenario: Get information of existing Edge Cloud Zones with optional parameters ("status") + @eam_getEdgeCloudZones_05_success_scenario_filtered_by_status + Scenario: Get information of existing Edge Cloud Zones with optional parameter ("status") Given There are at least one Edge Cloud Zones available And the request query parameter "$.status" is set to a valid status When the request "getEdgeCloudZones" is sent @@ -46,7 +71,41 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getEdgeCloudZo And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" And information of Edge Cloud Zones of "$.status" is returned - And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZones" + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + #/edge-cloud-zones GET 200 no status filter returns zones regardless of status + @eam_getEdgeCloudZones_06_success_scenario_no_status_filter + Scenario: Get existing Edge Cloud Zones without the optional parameter ("status") + Given there are Edge Cloud Zones available with different statuses + When the request "getEdgeCloudZones" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And Edge Cloud Zones with any status are returned + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + #/edge-cloud-zones GET 200 paginated by page and perPage + @eam_getEdgeCloudZones_07_success_scenario_paginated + Scenario: Get a specific page of existing Edge Cloud Zones with optional parameters ("page", "perPage") + Given there are more Edge Cloud Zones available than the requested "perPage" value + And the request query parameter "$.page" is set to a valid page number + And the request query parameter "$.perPage" is set to a valid perPage value + When the request "getEdgeCloudZones" is sent + Then the response status code is 200 + And the response header "Content-Type" is "application/json" + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response property "$.pagination.page" has the value provided for "$.page" + And the response property "$.pagination.perPage" has the value provided for "$.perPage" + And the response body complies with the OAS schema at "/components/schemas/EdgeCloudZoneList" + # Error 400 + @eam_getEdgeCloudZones_400.1_invalid_page + Scenario: Invalid pagination parameter ("page") + Given the request query parameter "$.page" is set to an invalid page number + When the request "getEdgeCloudZones" is sent + Then the response status code is 400 + And the response header "x-correlator" has same value as the request header "x-correlator" + And the response header "Content-Type" is "application/json" + And the response property "$.status" is 400 + And the response property "$.code" is "INVALID_ARGUMENT" + And the response property "$.message" contains a user friendly text # Error 401 @eam_getEdgeCloudZones_401.1_missing_access_token Scenario: Missing access token