Edge Cloud Zone definition: how to harmonise in the YAML file definitions?

[Kevsy]

Edge Cloud LCM and Simple Edge Discovery define the Edge Cloud zone differently (in the schema and human-readable docs). @Kevsy will investigate how to incorporate the LCM definitions into Simple Edge Discovery.

Tagging @sergiofranciscoortiz

[Kevsy]

@sergiofranciscoortiz I've looked at the definitions in LCM, and how they can be re-used in Simple Edge Discovery.

Documentation section

LCM Text:
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.

Analysis:
Region is not used in Simple Edge Discovery, so removed here. But otherwise OK to reuse the text

Schema section

LCM JSON for EdgeCloudZone:
[ { "EdgeCloudZone": "string", "status": "unknown", "region": "string" } ]

Current Simple Edge Discovery schema
{ "edgeCloudZone": [ { "edgeCloudProvider": "string", "edgeResourceName": "string" } ] }

Proposal:

Change LCM to:

[ { "edgeCloudZone": "string", "edgeCloudProvider": "string", "status": "unknown", "region": "string" } ]

Change Simple Edge Discovery to

[ { "edgeCloudZone": "string", "edgeCloudProvider": "string" } ]

[sergiofranciscoortiz]

We have been reviewing this first part of the proposal in Telefonica, and we could go for the option of:

[ { "edgeCloudProvider": "string","edgeCloudZone": "string", "status": "unknown", "region": "string" } ]

Which it would allow to:

1. Follow current approach of multicloud environments ( indicate first provider and then either region, zone or both)
2. At the same time keep some flexibility when "filtering/selecting" the actual provider,region or zone desired during app instantiation (allowing to include just of them), rather than making defining EdgeCloudZone as an object ( with edgeResourceName and edgeCloudProvider parameters).

It seems that it would be feasible to change it also in Simple Edge Discovery even if concept of status and region do not exist for the moment there.

We would prefer to maintain the indication of "Zones exist within a Region.", in edgeCloudZone definition at least in LCM.

[Kevsy]

adding @javierlozallu :

In PR #208 we discussed the identifier for an individual edgeCloudZone resource:

" We would need unique identifiers, to avoid conflict with other edge cloud providers, e.g. urn:vf:abc123. That identifier would need to be added to the EdgeCloudZoneDetails and returned in the GET \edgeCloudZones array response.

So, GET /edgeCloudZones/urn:vf:abc123 would return the details of an individual Edge Cloud Zone."

We can incorporate the Identifier URN in the EdgeCloudZone object schema definition:

YAML defintion:

    EdgeCloudZone:
      type: object
      description:  An Edge Cloud Zone, uniquely identified by the `id`
      properties:
        edgeCloudZone: 
          description: An Edge Cloud Zone, uniquely identified by the `id`
          type: object
          properties:
            id:
              $ref:"/components/schemas/EdgeCloudZoneId"
            edgeCloudProvider:
              $ref: "#/components/schemas/EdgeCloudProvider"
            edgeResourceName:
              $ref: "#/components/schemas/EdgeResource"

(TODO add the schema for the edgeCloudZoneId , e.g. urn:{mnc}:{mcc}:string )

JSON result:

{
  "edgeCloudZone": [
    {
      "id":"urn:123:456:abc789"
      "edgeCloudProvider": "AWS",
      "edgeResourceName": "eu-west-2-wl1-man-wlz-1"
    }
  ]
}

WDYT? And should the array of Edge Cloud Zones include multiple individual edgeCloudZone objects or simply and array of results not 'wrapped' in edgeCloudZone objects?

[sergiofranciscoortiz]

About the proposal of defining EdgeCloudZone as an object including id, edgeCloudProvider and EdgeResourceName, we need some clarifications as we think is not compatible with the approach of Change LCM to:

[ { "edgeCloudZone": "string", "edgeCloudProvider": "string", "status": "unknown", "region": "string" } ]

In current get edge-cloud-zones method in LCM, we offer an array response including all data of EdgeCloudZones that meet the criteria in the request ( currently Region or status) but it could be extended to other filters like edgeCloudProvider. It should not be needed to response with an object if an edgecloudZone could be uniquely identified by the combination of region,EdgeCloudProvider,edgeCloudZone.

To return details of specific EdgeCloudZone via the GET method proposed we would like to have also feedback from others, @gunjald, @nicolacdnll , @gainsley , could you have a look?

[gainsley]

These are all very good discussions. There's a few different things here being discussed here, so let me comment on them below.

1. Regarding a string ID of type "urn:mcc:mnc:xyz": I would strongly discourage trying to stuff multiple fields into a single string. This becomes a custom design of how to parse the string based on a special field delimiter that may or may not conflict with underlying software's allowed characters and usage of the string. We do not want to redesign string parsing/generation, that's better left to standard formats like JSON. If we need multiple fields, just make them explicit fields. Otherwise leave the ID as a simple string. As an aside, we would also prefer that MNC/MCC are not required fields for EdgeCloudZones, as it may not always be operators that host EdgeCloudZones.

2. URL to uniquely identify on object either via (a) an opaque ID generated by server (typically UUID), or (b) given-name/combination of given-names provided by user (i.e. { "edgeCloudZone": "sanfrancisco", "edgeCloudProvider": "edgexr", "region": "us" }). I.e. shall the GET/DELETE/PUT URL be /edgecloudzones/{UUID}, or /providers/{provider}/regions/{region}/edgecloudzones/{edgecloudzone}?

   • First, I believe there is an intent to allow scoping of given-names, i.e. we want to allow two different operator-providers to be able to create two distinct EdgeCloudZones both named "sanfrancisco", and we want to allow two different developer-providers to be able to create two distinct Apps both named "myapp". We agree with this approach to avoid conflicts between different users. In that case, if using given-names in the URL, we need the scoped given-names to uniquely identify the resource, i.e. /providers/{provider}/regions/{region}/edgecloudzones/{edgecloudzone}, or perhaps just /providers/{provider}/edgecloudzones/{edgecloudzone} depending on the scoping rules.
   • In general, uniquely identifying required fields should be part of the URL path, not part of query parameters. Query parameters are typically optional.
   • It seems most APIs tend towards using given names in their APIs, i.e. Kubernetes, Vault. Note this does not preclude the implementation from actually using a generated ID to internally track objects.
   • If there is scoping of given-names, it is really easy for a user to understand the scoping from the URL /providers/{provider}/edgecloudzones/{edgecloudzone}
   • For users directly using REST or a CLI, using UUIDs can be burdensome, as typically the user will do a GET (list) first and search for the given name to find the UUID for it, then issue DELETE/PUT on the UUID. Similarly, if the given-names have deep scoping, it may also burdensome to type out all the scoped names. But if using a GUI interface, these issues go away since mostly everything is point and click.

   I don't think there's any right or wrong way here. Our preference is to use given-names in URLs, rather than server-generated IDs. If we are using given-name URLs, then there's no need to expose any server-generated IDs to the user. If we are using server-generated IDs as part of API URLs, then that ID does need to be part of the EdgeCloudZone component returned via GET API calls.

3. Most REST APIs will have two GET APIs per resource, a singleton GET, i.e. /edgecloudzones/{uniqueid or name-path}, and a list GET, i.e. /edgecloudzones. The list API can have query params for any valid field of the EdgeCloudZone component to filter the results. The singleton does not have any query params. The singleton returns an EdgeCloudZone component and the list returns an array of EdgeCloudZone compenents. The singleton is not actually necessary, it's just a convenience to the client, because it will return 404 (Not Found) if the resource is not present, whereas the "list" GET with query params that uniquely identify a single object will return 200 with an empty list. I would suggest we follow this pattern, possibly omitting the singleton GET for now.

[gunjald]

I think the given structure to use [ { "edgeCloudZone": "string", "edgeCloudProvider": "string", "status": "unknown", "region": "string" } ] seems fine and may be we can use edgeCloudZoneId for edgeCloudZone. Also, @gainsley proposal for "/providers/{provider}/edgecloudzones/{edgecloudzone}" and the reasoning looks fair. The assignment of the UUID or URN based structure is something we need to agree but my inclination is towards the UUID as parsing and management of such fields if is not difficult but may create management issue at developer. Also in future we need to always work to ensure the given logical interpretation doesnt change which can create difficulties for evolution as it is not an opaque object.

The one issue is that as developer I can aggregate information from multiple APIs to represent what a UUID points to in terms of edge cloud zone, location and any other meta information but when there could be many operators in same region (which is also not standard" ) a developer may still need to manage different names, IDs to represents presence of different edge cloud zones in seemingly same location from different providers. But this in my opinion doesnt have a straight solution for now and something that should be handled in future versions of the API.

[nicolacdnll]

I'm also more inclined towards using UUIDs. Plus, I would suggest to include a field region on both API and to document that it needs to be with format: iso-3166-alpha-2 Country Code or similar.

This way, the region can be easily consumed as parameter for the Application to configure itself. This can be required by those applications whose content and behavior might change based on the country where the services is offered (e.g., due to whatever legislation or distribution rights). I don't think this can be done with the Device Location API because its needs consent of the device owner.

[javierlozallu]

Regarding region, it needs to be an open name due to the integration with hyperscalers or any other edge cloud provider than can use their own naming rules. Also a region could refer to something more extend/small than a country (us-west, spain-south, europe-north, etc) and we shouldn't limit that option.

To cover the data residency use case, we may introduce country parameter in next releases of the API once the MVP is released.

[javierlozallu]

Great discussion @Kevsy, @nicolacdnll, @gainsley, @gunjald and as a result we believe that the following changes can meet the criteria for the MVP scope and your insights above.

First Option:

The method GET /EdgeCloudZone retrieves the object EdgeCloudZone that contains; id, name and provider parameters as in the figure:

Second Option:
The method GET /EdgeCloudZone retrieves an array of the following parameters as in the figure:

EdgeCloudZoneId will be reused in the POST /app/{appId}/Instance, so developers can instantiate in one or more Zones, depending on the items in the array. (This covers the intent of the MVP API as in figure).

Provider and region parameters may be included in next releases to add extended capabilities and maybe we have to create new methods as suggested by @gainsley (Something like /providers/{provider}/regions/{regionId}/edgecloudzones/{edgecloudzoneId} ) .

WDYT?

[gainsley]

I think the structure looks great. Regarding the API path, it sounds like @gunjald and @nicolacdnll prefer to use the server-generated ID, rather than the given names, which I'm ok with. So the api path would instead be /edge-cloud-zones/{edgeCloudZoneId}.

[Kevsy]

Thanks all for the excellent feedback! Let me try to summarise the proposed change to Simple Edge Discovery.

PR #194 already has edge-cloud-zones as the collection path. The response to GET /edge-cloud-zones?filter=closest is an array (with a single member) of Edge Cloud Zones.

@javierlozallu , you have proposed two options for the structure (I've changed these to lower camel case per API guidelines and added the UUID constraint). I prefer the second, which does not 'wrap' the information in an `edgeCloudZone' object. So for Simple Edge Discovery the response structure would be:

[
  {
      "edgeCloudZoneId: "string UUID"
      "edgeCloudProvider": "string",
      "edgeResourceName": "string"
  }
]

...and the LCM API can add status (Simple Edge Discovery does not include this) and region (because we need to decide what that means, and Simple Edge Discovery does not require it).

Regarding the UUID: as long as the tuple of edgeCloudProvider and edgeCloudZoneId is unique, then we have achieved a UUID. I agree that is easier to parse than a URN. But we could add mnc and mcc to indicate the operator, because that may be helpful to the developer?

[javierlozallu]

Great, so I'm going to update PR #208 so in the response to GET /edge-cloud-zones we'll have this:

[
  {
    "edgeCloudZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "edgeCloudZoneName": "BCN-1A",
    "edgeCloudProvider": "TEF",
    "edgeCloudRegion": "SPAIN-EAST"
    "edgeCloudStatus": "unknown",
  }
]

@Kevsy.
Maybe we could add mnc and mcc in a next release as optional parameters when the edgeCloudProvider is a MNO, for our MVP API I think we could keep these parameters to cover the basic intents and functionalities.

[Kevsy]

Thanks @javierlozallu , and I made a mistake in my previous example, it should be as you have written above (but without region or status for Simple Edge Discovery). So an example Simple Edge Discovery response would be:

[
  {
    "edgeCloudZoneId": "4gt555-6457-7890-d4he-1dc79f44gb66",
    "edgeCloudZoneName": "eu-west-2-wl1-man-wlz-1",
    "edgeCloudProvider": "AWS"
  }
]

I will update PR #194 with the new response.

Regarding MNC/MCC - yes, we should add that in the next release, which helps identify the operator where the edge cloud zone is provided by a cloud partner (such as the Vodafone example I gave above)

[javierlozallu]

@Kevsy as mentioned at the meeting, please clarify the right schema to use for EdgeCloudZone.

Current schema in LCM #208

EdgeCloudZones [ 
       EdgeCloudZone { "edgeCloudId": "string uuid", "edgeCloudProvider": "string", "edgeCloudZoneName": "string"... } 
] 

EdgecloudZones is an array that contains one of several EdgeCloudZone (with their propierties; Id, Provider, Name,...). I understood that this would be more easy to manage but correct me If I'm wrong so I change the schema in LCM API.

Current Schema in SED #194

EdgeCloudZones [ 
       EdgeCloudZone { 
               edgeCloudZone { "edgeCloudId": "string uuid", "edgeCloudProvider": "string", "edgeCloudZoneName": "string" } 
       }
] 

In this aproach, EdgeCloudZones in an array that contains one EdgeCloudZone that has one property (edgeCloudZone) that contains the Id, Provider, Name.

[Kevsy]

@javierlozallu my proposal is to remove the edgeCloudZones and edgeCloudZone 'wrapper' objects to reduce and simplify the response.

Model:

  schemas:
    EdgeCloudZones:
      type: array
      items:
        $ref: "#/components/schemas/EdgeCloudZone"
      minItems: 1
      description: |
        A collection of Edge Cloud Zones. For this Simple Edge
        Discovery API the collection will have at most one member (the closest
        Edge Cloud Zone to the user device indicated in the request).
      additionalProperties: false

    EdgeCloudZone:
      type: object
      description:  |
        An Edge Cloud Zone, uniquely identified by a combination
        of the value of the Edge Resource Name object and the value of the
        Provider object (the name of the cloud provider or operator hosting that
        edge cloud zone).
      properties:
        edgeCloudZoneId:
          $ref: "#/components/schemas/EdgeCloudZoneId"
        edgeCloudZoneName:
          $ref: "#/components/schemas/EdgeCloudZoneName"
        edgeCloudProvider:
          $ref: "#/components/schemas/EdgeCloudProvider" 

JSON example response to GET /edge-cloud-zones?filter=closest

[
  {
    "edgeCloudZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "edgeCloudZoneName": "string",
    "edgeCloudProvider": "string"
  }
]

[javierlozallu]

Perfect @Kevsy!

I'm going to update the PR #208 with the schema. I think that's all for this discussion so we can close it. (I will be waiting for feedback in #208 so we can merge it).