docs/specs/multicloud-cloud-region-id.rst

..
 This work is licensed under a Creative Commons Attribution 4.0
 International License.

=====================================================
MultiCloud alignment to Consistent ID of Cloud Region
=====================================================

To support ONAP Functional Requirement: "Centralized Representation and Consistent Identification of Cloud Regions In ONAP", MultiCloud services have to upgrade their APIs to align to the consistent ID of a cloud region.
..
https://wiki.onap.org/display/DW/Centralized+Representation+and+Consistent+Identification+of+Cloud+Regions+In+ONAP

Problems Statement
==================

With ONAP Amsterdam and Beijing Releases, there are 2 problems with respect to
the ID of a cloud region.

``Problem 1``: {vim_id}={cloud-owner}_{cloud-region-id} imposed unnecessary constraint
on how {cloud-owner} can be populated: character underscore '_' cannot be used to
populate {cloud-owner}

``Problem 2``: multicloud plugins for OpenStack leverages {cloud-region-id} as the OpenStack
Region ID to interact with represented OpenStack Instance. This implies that {cloud-region-id}
can only be populated by the represented OpenStack Region ID. This constraint implies
that two OpenStack instances with the same Region ID can only be represented with different
{cloud-owner}, even though they belong to the same owner. This is a violation to the
sematics of {cloud-owner} . on the other hand, the sematics of {cloud-region-id} refers to the
geographic region, which is not necessarily the same as OpenStack Region ID. What's more, the
fact that VID and SDNC have been using the {cloud-region-id} alone to identify a cloud region makes
the problem being unacceptable.

Proposed Solutions
==================

I would like to present 2 proposals to workaround each of problems above respectively:

``Proposal 1: depreciate the {vim_id} for all multicloud services, use composed keys {cloud-owner},
{cloud-region-id}``

This will result in upgrading the multicloud APIs and code refactoring.

We'd better to have common terminologies to facilitate the description below. Take the identity token API
as example:

::

  http(s)://{service IP}:{service port}/api/multicloud/v0/{cloud-owner}_{cloud-region-id}/identity/v3/auth/tokens
  e.g. http://1.2.3.4:9001/api/multicloud/v0/OnaplabOwner_RegionOne/identity/v3/auth/tokens


This API consists of several parts referred as below terminologies:


 - **Terminology            | Description                                  | Example**
 - **service endpoint**     | http(s)://{service IP}:{service port}        | http://1.2.3.4:9001
 - **service namespace**    | api/{service-name}                           | api/multicloud
 - **service API version**  | v0, v1, etc.                                 | v0
 - **ID of a cloud region** | the ID to specify a cloud region             | OnaplabOwner_RegionOne
 - **proxied API catalog**  | identity,compute, network, image,volume,etc. | identity
 - **proxied API endpoint** | consists of all above                        | *http://1.2.3.4:9001/api/multicloud/v0/OnaplabOwner_RegionOne/identity*
 - **proxied API resource** | URI for an OpenStack resource                | v3/auth/tokens

Given the terminology above, the general rules to upgrade MultiCloud North Bound API are:
 - Upgrade "service API version" from "v0" to "v1"
 - Change "ID of cloud region" from "{cloud-owner}_{cloud-region-id}" to "{cloud-owner}/{cloud-region-id}"

The upgraded API for identity token API looks like:

::

  http(s)://{service IP}:{service port}/api/multicloud/v1/{cloud-owner}/{cloud-region-id}/identity/v3/auth/tokens
  e.g. http(s)://1.2.3.4:9001/api/multicloud/v1/OnaplabOwner/RegionOne/identity/v3/auth/tokens


``Proposal 2: decouple the cloud region's {cloud-region-id} from OpenStack's Region ID``

Instead of populating the AAI's cloud-region-id with OpenStack Region ID, decoupling of them by put OpenStack Region ID
into other property of a cloud region object would enable the flexibility of populating arbitrary string to AAI's
cloud-region-id. There are several options to implement that, with the intention of maintaining backward compatibility
and minimized impact on AAI's schema, the proposed design options are described as below.

Option 1: ONAP User inputs the OpenStack Region ID with ESR Portal

There is a property of cloud region object named "cloud-extra-info"
..
https://wiki.onap.org/display/DW/AAI+REST+API+Documentation+-+Beijing

::

   cloud-extra-info: string
     ESR inputs extra information about the VIM or Cloud which will be decoded by MultiVIM.

the intention of this property is to enable the extending of cloud region object without impact AAI's schema. How and when to use this property is up to each multicloud
plugin respectively. This property can be populated by ONAP users through ESR VIM registration GUI Portal (the input field label: "Cloud Extra Info"). The best practice to utilize this "cloud-extra-info" property is that ONAP users to input format json string, with
which extra configuration data can be serialized as {"key":"value"} into this json string. And the corresponding MultiCloud plugin decode and utilize the input key-value pairs.
..
https://wiki.onap.org/pages/viewpage.action?pageId=25431491


**This proposal changes and workflow With Option 1**:

1. Define a key "openstack-region-id" with value populated by OpenStack Region ID,
     e.g. "RegionOne", "RegionTwo", etc. which must align to the represented OpenStack instance.
2. ONAP user should put this key-value pair into "cloud-extra-info" property via ESR GUI Portal, the input string
    looks like: "{\"openstack-region-id\":\"RegionOne\"}"
3. the corresponding MultiCloud plugin should decode this string to extract this key-value pair "openstack-region-id" during cloud region on-boarding phase.
4. Update AAI schema to add one more property "openstack-region-id" to AAI "esr-system-info" object which is the child of AAI "cloud-region" object.
5. MultiCloud plugin for OpenStack should populate this property with the information acquired in step 3.
6. MultiCloud should use this property to determine what OpenStack Region ID is when interacting with represented OpenStack Instance
7. Given the workflow above, the AAI's "cloud-region-id" can be populated by arbitrary string.
8. In cases that either ONAP user doesn't input the key-value pair of "openstack-region-id" into "cloud-extra-info" or MultiCloud Plugin does not support the decoding/using key-value pair "openstack-region-id", the legacy constraint should be applied, that is: ONAP user should make sure AAI's "cloud-region-id" is populated by OpenStack Region ID.


Option 2: MultiCloud plugin discover the OpenStack Region ID with Rest API

The Identity API: "/v3/regions" can be used to list all regions. In case of no multi-region configuration for underlying OpenStack instance,
this API should return the only one OpenStack Region information. In case of multi-region configuration for underlying OpenStack instances,
The list of OpenStack Regions will be returned. In this case, I assume you either go with Option 1,
or go with another proposal "MultiCloud Multi-Region support" to on-board all cloud regions at one time.
..
https://developer.openstack.org/api-ref/identity/v3/index.html#regions

**This proposal changes and workflow With Option 2**:

1, MultiCloud plugin for OpenStack discover the OpenStack region ID with Rest API during cloud region on-boarding phase.
2, Update AAI schema to add one more property "openstack-region-id" to AAI "esr-system-info" object which is the child of AAI "cloud-region" object.
3, MultiCloud plugin for OpenStack should populate this property with informatin acquired during step 1.
4, MultiCloud should use this property to determine what OpenStack Region ID is when interacting with represented OpenStack Instance
5. Given the workflow above, the AAI's "cloud-region-id" can be populated by arbitrary string.