Add design spec for API upgrading and ID alignment

This is to propose the changes for enabling
consistent ID of a cloud region

Change-Id: Ia25f60ba14d28d02559a9902972a3cff6ca814c2
Issue-ID: MULTICLOUD-280
Signed-off-by: Bin Yang <bin.yang@windriver.com>

1 files changed, 131 insertions, 0 deletions

diff --git a/docs/specs/multicloud-cloud-region-id.rst b/docs/specs/multicloud-cloud-region-id.rst
new file mode 100644
index 0000000..ea6d6a9
--- /dev/null
+++ b/docs/specs/multicloud-cloud-region-id.rst
@@ -0,0 +1,131 @@
+..
+ 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.