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

   1 ..
   2  This work is licensed under a Creative Commons Attribution 4.0
   3  International License.
   4
   5 =====================================================
   6 MultiCloud alignment to Consistent ID of Cloud Region
   7 =====================================================
   8
   9 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.
  10 ..
  11 https://wiki.onap.org/display/DW/Centralized+Representation+and+Consistent+Identification+of+Cloud+Regions+In+ONAP
  12
  13 Problems Statement
  14 ==================
  15
  16 With ONAP Amsterdam and Beijing Releases, there are 2 problems with respect to
  17 the ID of a cloud region.
  18
  19 ``Problem 1``: {vim_id}={cloud-owner}_{cloud-region-id} imposed unnecessary constraint
  20 on how {cloud-owner} can be populated: character underscore '_' cannot be used to
  21 populate {cloud-owner}
  22
  23 ``Problem 2``: multicloud plugins for OpenStack leverages {cloud-region-id} as the OpenStack
  24 Region ID to interact with represented OpenStack Instance. This implies that {cloud-region-id}
  25 can only be populated by the represented OpenStack Region ID. This constraint implies
  26 that two OpenStack instances with the same Region ID can only be represented with different
  27 {cloud-owner}, even though they belong to the same owner. This is a violation to the
  28 sematics of {cloud-owner} . on the other hand, the sematics of {cloud-region-id} refers to the
  29 geographic region, which is not necessarily the same as OpenStack Region ID. What's more, the
  30 fact that VID and SDNC have been using the {cloud-region-id} alone to identify a cloud region makes
  31 the problem being unacceptable.
  32
  33 Proposed Solutions
  34 ==================
  35
  36 I would like to present 2 proposals to workaround each of problems above respectively:
  37
  38 ``Proposal 1: depreciate the {vim_id} for all multicloud services, use composed keys {cloud-owner},
  39 {cloud-region-id}``
  40
  41 This will result in upgrading the multicloud APIs and code refactoring.
  42
  43 We'd better to have common terminologies to facilitate the description below. Take the identity token API
  44 as example:
  45
  46 ::
  47
  48   http(s)://{service IP}:{service port}/api/multicloud/v0/{cloud-owner}_{cloud-region-id}/identity/v3/auth/tokens
  49   e.g. http://1.2.3.4:9001/api/multicloud/v0/OnaplabOwner_RegionOne/identity/v3/auth/tokens
  50
  51
  52 This API consists of several parts referred as below terminologies:
  53
  54
  55  - **Terminology         | Description                   | Example**
  56  - **service endpoint**    | http(s)://{service IP}:{service port}| http://1.2.3.4:9001
  57  - **service namespace**   | api/{service-name}            | api/multicloud
  58  - **service API version** | v0, v1, etc.                  | v0
  59  - **ID of a cloud region**| the ID to specify a cloud region| OnaplabOwner_RegionOne
  60  - **proxied API catalog** | identity,compute, network, image,volume,etc.| identity
  61  - **proxied API endpoint**| consists of all above| *http://1.2.3.4:9001/api/multicloud/v0/OnaplabOwner_RegionOne/identity*
  62  - **proxied API resource**| URI for an OpenStack resource | v3/auth/tokens
  63
  64 Given the terminology above, the general rules to upgrade MultiCloud North Bound API are:
  65  - Upgrade "service API version" from "v0" to "v1"
  66  - Change "ID of cloud region" from "{cloud-owner}_{cloud-region-id}" to "{cloud-owner}/{cloud-region-id}"
  67
  68 The upgraded API for identity token API looks like:
  69
  70 ::
  71
  72   http(s)://{service IP}:{service port}/api/multicloud/v1/{cloud-owner}/{cloud-region-id}/identity/v3/auth/tokens
  73   e.g. http(s)://1.2.3.4:9001/api/multicloud/v1/OnaplabOwner/RegionOne/identity/v3/auth/tokens
  74
  75
  76 ``Proposal 2: decouple the cloud region's {cloud-region-id} from OpenStack's Region ID``
  77
  78 Instead of populating the AAI's cloud-region-id with OpenStack Region ID, decoupling of them by put OpenStack Region ID
  79 into other property of a cloud region object would enable the flexibility of populating arbitrary string to AAI's
  80 cloud-region-id. There are several options to implement that, with the intention of maintaining backward compatibility
  81 and minimized impact on AAI's schema, the proposed design options are described as below.
  82
  83 Option 1: ONAP User inputs the OpenStack Region ID with ESR Portal
  84
  85 There is a property of cloud region object named "cloud-extra-info"
  86 ..
  87 https://wiki.onap.org/display/DW/AAI+REST+API+Documentation+-+Beijing
  88
  89 ::
  90
  91    cloud-extra-info: string
  92      ESR inputs extra information about the VIM or Cloud which will be decoded by MultiVIM.
  93
  94 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
  95 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
  96 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.
  97 ..
  98 https://wiki.onap.org/pages/viewpage.action?pageId=25431491
  99
 100
 101 **This proposal changes and workflow With Option 1**:
 102
 103 1. Define a key "openstack-region-id" with value populated by OpenStack Region ID,
 104      e.g. "RegionOne", "RegionTwo", etc. which must align to the represented OpenStack instance.
 105 2. ONAP user should put this key-value pair into "cloud-extra-info" property via ESR GUI Portal, the input string
 106     looks like: "{\"openstack-region-id\":\"RegionOne\"}"
 107 3. the corresponding MultiCloud plugin should decode this string to extract this key-value pair "openstack-region-id" during cloud region on-boarding phase.
 108 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.
 109 5, MultiCloud plugin for OpenStack should populate this property with the information acquired in step 3.
 110 6, MultiCloud should use this property to determine what OpenStack Region ID is when interacting with represented OpenStack Instance
 111 7. Given the workflow above, the AAI's "cloud-region-id" can be populated by arbitrary string.
 112 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.
 113
 114
 115 Option 2: MultiCloud plugin discover the OpenStack Region ID with Rest API
 116
 117 The Identity API: "/v3/regions" can be used to list all regions. In case of no multi-region configuration for underlying OpenStack instance,
 118 this API should return the only one OpenStack Region information. In case of multi-region configuration for underlying OpenStack instances,
 119 The list of OpenStack Regions will be returned. In this case, I assume you either go with Option 1,
 120 or go with another proposal "MultiCloud Multi-Region support" to on-board all cloud regions at one time.
 121
 122 ..
 123 https://developer.openstack.org/api-ref/identity/v3/index.html#regions
 124
 125 **This proposal changes and workflow With Option 2**:
 126
 127 1, MultiCloud plugin for OpenStack discover the OpenStack region ID with Rest API during cloud region on-boarding phase.
 128 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.
 129 3, MultiCloud plugin for OpenStack should populate this property with informatin acquired during step 1.
 130 4, MultiCloud should use this property to determine what OpenStack Region ID is when interacting with represented OpenStack Instance
 131 5. Given the workflow above, the AAI's "cloud-region-id" can be populated by arbitrary string.