docs/Chapter8.rst

   1 **8. Appendix**
   2 ===============
   3
   4 a. Data Record Formats
   5 ======================
   6
   7 **Appendix A – Chef JSON Key Value Description**
   8
   9 The following provides the key value pairs that must be contained in the
  10 JSON file supporting Chef action.
  11
  12 Table A1. Chef JSON File key value description
  13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  14
  15 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  16 | **Field Name**    | **Description**                                                                                                                                                                                                                                                                                   | **Type**    | **Comment**                                                                                                                             |
  17 +===================+===================================================================================================================================================================================================================================================================================================+=============+=========================================================================================================================================+
  18 | Environment       | A JSON dictionary representing a Chef Environment object. If the VNF action requires loading or modifying Chef environment attributes associated with the VNF, all the relevant information must be provided in this JSON dictionary in a structure that conforms to a Chef Environment Object.   | Optional    | Depends on VNF action.                                                                                                                  |
  19 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  20 | Node              | A JSON dictionary representing a Chef Node Object.                                                                                                                                                                                                                                                | Mandatory   |                                                                                                                                         |
  21 |                   |                                                                                                                                                                                                                                                                                                   |             |                                                                                                                                         |
  22 |                   | The Node JSON dictionary must include the run list to be triggered for the desired VNF action by the push job. It should also include any attributes that need to be configured on the Node Object as part of the VNF action.                                                                     |             |                                                                                                                                         |
  23 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  24 | NodeList          | Array of FQDNs that correspond to the endpoints (VMs) of a VNF registered with the Chef Server that need to trigger a chef-client run as part of the desired VNF action.                                                                                                                          | Mandatory   |                                                                                                                                         |
  25 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  26 | PushJobFlag       | This field indicates whether the VNF action requires a push Job. Push job object will be created by ONAP if required.                                                                                                                                                                             | Mandatory   | If set to “True”, ONAP will request a push job. Ignored otherwise.                                                                      |
  27 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  28 | CallbackCapable   | This field indicates if the chef-client run invoked by push job corresponding to the VNF action is capable of posting results on a callback URL.                                                                                                                                                  | Optional    | If Chef cookbook is callback capable, VNF owner is required to set it to “True”. Ignored otherwise.                                     |
  29 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  30 | GetOutputFlag     | Flag which indicates whether ONAP should retrieve output generated in a chef-client run from Node object attribute node[‘PushJobOutput’] for this VNF action (e.g., in Audit).                                                                                                                    | Mandatory   | ONAP will retrieve output from NodeObject attributes [‘PushJobOutput’] for all nodes in NodeList if set to “True”. Ignored otherwise.   |
  31 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------+
  32
  33 Chef Template example:
  34
  35 “Environment”:{
  36
  37       "name": "HAR",
  38
  39       "description": "VNF Chef environment for HAR",
  40
  41       "json\_class": "Chef::Environment",
  42
  43       "chef\_type": "environment",
  44
  45       "default\_attributes": { },
  46
  47       "override\_attributes": {
  48
  49             “Retry\_Time”:”50”,
  50
  51             “MemCache”: “1024”,
  52
  53             “Database\_IP”:”10.10.1.5”
  54
  55       },
  56
  57 }
  58
  59 }
  60
  61 “Node”: {
  62
  63       “name” : “signal.network.com “
  64
  65       "chef\_type": "node",
  66
  67       "json\_class": "Chef::Node",
  68
  69       "attributes": {
  70
  71             “IPAddress1”: “192.168.1.2”,
  72
  73             “IPAddress2”:”135.16.162.5”,
  74
  75             “MyRole”:”BE”
  76
  77       },
  78
  79       "override": {},
  80
  81       "default": {},
  82
  83       “normal”:{},
  84
  85       “automatic”:{},
  86
  87       “chef\_environment” : “\_default”
  88
  89       "run\_list": [ "configure\_signal" ]
  90
  91       },
  92
  93       “NodeList”:[“node1.vnf\_a.onap.com”, “node2.vnf\_a.onap.com”],
  94
  95       “PushJobFlag”: “True”
  96
  97       “CallbackCapable”:True
  98
  99       “GetOutputFlag” : “False”
 100
 101 }
 102
 103 The example JSON file provided by the vendor for each VNF action will be
 104 turned into a template by ONAP, that can be updated with instance
 105 specific values at run-time.
 106
 107 Some points worth noting regarding the JSON fields:
 108
 109 a. The JSON file must be created for each action for each VNF.
 110
 111 b. If a VNF action involves multiple endpoints (VMs) of a VNF, ONAP will
 112    replicate the “Node” JSON dictionary in the template and post it to
 113    each FQDN (i.e., endpoint) in the NodeList after setting the “name”
 114    field in the Node object to be the respective FQDN [10]_. Hence, it
 115    is required that all end points (VMs) of a VNF involved in a VNF
 116    action support the same set of Node Object attributes.
 117
 118 The following table describes the JSON dictionary to post in Callback.
 119
 120 Table A2. JSON Dictionary to Post in Callback
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 124 | **Key**         | **Description**                                                                                                                                                                                           | **Type**    | **Comment**                                                 |
 125 +=================+===========================================================================================================================================================================================================+=============+=============================================================+
 126 | RequestId       | A unique string associated with the original request by ONAP. This key-value pair will be provided by ONAP in the environment of the push job request and must be returned as part of the POST message.   | Mandatory   |                                                             |
 127 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 128 | StatusCode      | An integer that must be set to                                                                                                                                                                            | Mandatory   |                                                             |
 129 |                 |                                                                                                                                                                                                           |             |                                                             |
 130 |                 | 200 if chef-client run on the node finished successfully                                                                                                                                                  |             |                                                             |
 131 |                 |                                                                                                                                                                                                           |             |                                                             |
 132 |                 | 500 otherwise.                                                                                                                                                                                            |             |                                                             |
 133 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 134 | StatusMessage   | A string which must be set to                                                                                                                                                                             | Mandatory   |                                                             |
 135 |                 |                                                                                                                                                                                                           |             |                                                             |
 136 |                 | ‘SUCCESS’ if StatusCode was 200                                                                                                                                                                           |             |                                                             |
 137 |                 |                                                                                                                                                                                                           |             |                                                             |
 138 |                 | Appropriate error message otherwise.                                                                                                                                                                      |             |                                                             |
 139 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 140 | Name            | A string which corresponds to the name of the node where push job is run. It is required that the value be retrieved from the node object attributes (where it is always defined).                        | Mandatory   |                                                             |
 141 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 142 | PushJobOutput   | Any output from the chef-client run that needs to be returned to ONAP.                                                                                                                                    | Optional    | Depends on VNF action. If empty, it must not be included.   |
 143 +-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------+
 144
 145
 146 **Appendix B – Ansible JSON Key Value Description**
 147
 148 The following provides the key value pairs that must be contained in the
 149 JSON file supporting Ansible action.
 150
 151 Table B1. Ansible JSON File key value description
 152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 155 | **Field Name**   | **Description**                                                                                                                                                                                                                                                                            | **Type**    | **Comment**                                                         |
 156 +==================+============================================================================================================================================================================================================================================================================================+=============+=====================================================================+
 157 | PlaybookName     | VNF Vendor must list name of the playbook used to execute the VNF action.                                                                                                                                                                                                                  | Mandatory   |                                                                     |
 158 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 159 | Action           | Name of VNF action.                                                                                                                                                                                                                                                                        | Optional    |                                                                     |
 160 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 161 | EnvParameters    | A JSON dictionary which should list key value pairs to be passed to the Ansible playbook. These values would correspond to instance specific parameters that a playbook may need to execute an action.                                                                                     | Optional    | Depends on the VNF action.                                          |
 162 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 163 | NodeList         | A JSON array of FQDNs that the playbook must be executed on.                                                                                                                                                                                                                               | Optional    | If not provided, playbook will be executed on the Ansible Server.   |
 164 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 165 | FileParameters   | A JSON dictionary where keys are filenames and values are contents of files. The Ansible Server will utilize this feature to generate files with keys as filenames and values as content. This attribute can be used to generate files that a playbook may require as part of execution.   | Optional    | Depends on the VNF action and playbook design.                      |
 166 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 167 | Timeout          | Time (in seconds) that a playbook is expected to take to finish execution for the VNF. If playbook execution time exceeds this value, Ansible Server will terminate the playbook process.                                                                                                  | Optional    |                                                                     |
 168 +------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------------------------------------------------------------------+
 169
 170 Ansible JSON file example:
 171
 172 {
 173
 174       “Action”:”Configure”,
 175
 176       "PlaybookName": "Ansible\_configure.yml",
 177
 178       "NodeList": ["test1.vnf\_b.onap.com", “test2.vnf\_b.onap.com”],
 179
 180       "Timeout": 60,
 181
 182       "EnvParameters": {"Retry": 3, "Wait": 5, “ConfigFile”:”config.txt”},
 183
 184       “FileParameters”:{“config.txt”:”db\_ip=10.1.1.1, sip\_timer=10000”}
 185
 186 }
 187
 188 In the above example, the Ansible Server will:
 189
 190 a. Process the “FileParameters” dictionary and generate a file named
 191    ‘config.txt’ with contents set to the value of the ‘config.txt’ key.
 192
 193 b. Execute the playbook named ‘Ansible\_configure.yml’ on nodes with
 194    FQDNs test1.vnf\_b.onap.com and test2.vnf\_b.onap.com respectively
 195    while providing the following key value pairs to the playbook:
 196    Retry=3, Wait=5, ConfigFile=config.txt
 197
 198 c. If execution time of the playbook exceeds 60 secs (across all hosts),
 199    it will be terminated.
 200
 201 **Appendix C – VNF License Information Guidelines**
 202
 203 This Appendix describes the metadata to be supplied for VNF licenses.
 204
 205 1. General Information
 206
 207 Table C1 defines the required and optional fields for licenses.
 208
 209 Table C1. Required Fields for General Information
 210 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 211
 212 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 213 | **Field Name**                 | **Description**                                                                                                                                                                                                                                                                                           | **Data Type**     | **Type**    |
 214 +================================+===========================================================================================================================================================================================================================================================================================================+===================+=============+
 215 | Vendor Name                    | The name of the vendor.                                                                                                                                                                                                                                                                                   | String            | Mandatory   |
 216 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 217 | Vendor Product                 | The name of the product to which this agreement applies.                                                                                                                                                                                                                                                  | String            | Mandatory   |
 218 |                                |                                                                                                                                                                                                                                                                                                           |                   |             |
 219 |                                | Note: a contract/agreement may apply to more than one vendor product. In that case, provide the metadata for each product separately.                                                                                                                                                                     |                   |             |
 220 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 221 | Vendor Product Description     | A general description of vendor software product.                                                                                                                                                                                                                                                         | String            | Optional    |
 222 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 223 | Export Control                 | ECCNs are 5-character alpha-numeric designations used on the Commerce Control List (CCL) to identify dual-use items for export control purposes. An ECCN categorizes items based on the nature of the product, i.e. type of commodity, software, or technology and its respective technical parameters.   | String            | Mandatory   |
 224 |                                |                                                                                                                                                                                                                                                                                                           |                   |             |
 225 | Classification Number (ECCN)   |                                                                                                                                                                                                                                                                                                           |                   |             |
 226 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 227 | Reporting Requirements         | A list of any reporting requirements on the usage of the software product.                                                                                                                                                                                                                                | List of strings   | Optional    |
 228 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+-------------+
 229
 230 1. Entitlements
 231
 232 Entitlements describe software license use rights. The use rights may be
 233 quantified by various metrics: # users, # software instances, # units.
 234 The use rights may be limited by various criteria: location (physical or
 235 logical), type of customer, type of device, time, etc.
 236
 237 One or more entitlements can be defined; each one consists of the
 238 following fields:
 239
 240 Table C2. Required Fields for Entitlements
 241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 242
 243 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 244 | **Field Name**                                      | **Description**                                                                                                                                                                       | **Data Type**     | **Type**      |
 245 +=====================================================+=======================================================================================================================================================================================+===================+===============+
 246 | Vendor Part Number / Manufacture Reference Number   | Identifier for the entitlement as described by the vendor in their price list / catalog / contract.                                                                                   | String            | Mandatory     |
 247 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 248 | Description                                         | Verbiage that describes the entitlement.                                                                                                                                              | String            | Optional      |
 249 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 250 | Entitlement Identifier                              | Each entitlement defined must be identified by a unique value (e.g., numbered 1, 2, 3….)                                                                                              | String            | Mandatory     |
 251 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 252 | Minimum Order Requirement                           | The minimum number of entitlements that need to be purchased. For example, the entitlements must be purchased in a block of 100. If no minimum is required, the value will be zero.   | Number            | Mandatory     |
 253 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 254 | Unique Reporting Requirements                       | A list of any reporting requirements on the usage of the software product. (e.g.: quarterly usage reports are required)                                                               | List of Strings   | Optional      |
 255 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 256 | License Type                                        | Type of license applicable to the software product. (e.g.: fixed-term, perpetual, trial, subscription.)                                                                               | String            | Mandatory     |
 257 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 258 | License Duration                                    | Valid values:                                                                                                                                                                         | String            | Conditional   |
 259 |                                                     |                                                                                                                                                                                       |                   |               |
 260 |                                                     | **year**, **quarter**, **month**, **day**.                                                                                                                                            |                   |               |
 261 |                                                     |                                                                                                                                                                                       |                   |               |
 262 |                                                     | Not applicable when license type is Perpetual.                                                                                                                                        |                   |               |
 263 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 264 | License Duration Quantification                     | Number of years, quarters, months, or days for which the license is valid.                                                                                                            | Number            | Conditional   |
 265 |                                                     |                                                                                                                                                                                       |                   |               |
 266 |                                                     | Not applicable when license type is Perpetual.                                                                                                                                        |                   |               |
 267 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 268 | Limits                                              | see section C.4 for possible values                                                                                                                                                   | List              | Optional      |
 269 +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------+---------------+
 270
 271 1. License Keys
 272
 273 This section defines information on any License Keys associated with the
 274 Software Product. A license key is a data string (or a file) providing a
 275 means to authorize the use of software. License key does not provide
 276 entitlement information.
 277
 278 License Keys are not required. Optionally, one or more license keys can
 279 be defined; each one consists of the following fields:
 280
 281 Table C3. Required Fields for License Keys
 282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 283
 284 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 285 | **Field Name**           | **Description**                                                                                               | **Data Type**   | **Type**    |
 286 +==========================+===============================================================================================================+=================+=============+
 287 | Description              | Verbiage that describes the license key                                                                       | String          | Mandatory   |
 288 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 289 | License Key Identifier   | Each license key defined must be identified by a unique value (e.g., numbered 1, 2, 3….)                      | String          | Mandatory   |
 290 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 291 | Key Function             | Lifecycle stage (e.g., Instantiation or Activation) at which the license key is applied to the software.      | String          | Optional    |
 292 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 293 | License Key Type         | Valid values:                                                                                                 | String          | Mandatory   |
 294 |                          |                                                                                                               |                 |             |
 295 |                          | **Universal, Unique**                                                                                         |                 |             |
 296 |                          |                                                                                                               |                 |             |
 297 |                          | **Universal** - a single license key value that may be used with any number of instances of the software.     |                 |             |
 298 |                          |                                                                                                               |                 |             |
 299 |                          | **Unique**- a unique license key value is required for each instance of the software.                         |                 |             |
 300 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 301 | Limits                   | see section C.4 for possible values                                                                           | List            | Optional    |
 302 +--------------------------+---------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 303
 304 1. Entitlement and License Key Limits
 305
 306 Limitations on the use of software entitlements and license keys may be
 307 based on factors such as: features enabled in the product, the allowed
 308 capacity of the product, number of installations, etc... The limits may
 309 generally be categorized as:
 310
 311 -  where (location)
 312
 313 -  when (time)
 314
 315 -  how (usages)
 316
 317 -  who/what (entity)
 318
 319 -  amount (how much)
 320
 321 Multiple limits may be applicable for an entitlement or license key.
 322 Each limit may further be described by limit behavior, duration,
 323 quantification, aggregation, aggregation interval, start date, end date,
 324 and threshold.
 325
 326 When the limit is associated with a quantity, the quantity is relative
 327 to an instance of the entitlement or license key. For example:
 328
 329 -  Each entitlement grants the right to 50 concurrent users. If 10
 330    entitlements are purchased, the total number of concurrent users
 331    permitted would be 500. In this example, the limit category is
 332    **amount**, the limit type is **users**, and the limit
 333    **quantification** is **50.**
 334
 335    Each license key may be installed on 3 devices. If 5 license keys are
 336    acquired, the total number of devices allowed would be 15. In this
 337    example, the limit category is **usages**, the limit type is
 338    **device**, and the limit **quantification** is **3.**
 339
 340 1. Location
 341
 342 Locations may be logical or physical location (e.g., site, country). For
 343 example:
 344
 345 -  use is allowed in Canada
 346
 347 Table C4. Required Fields for Location
 348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 349
 350 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 351 | **Field Name**         | **Description**                                                                                                     | **Data Type**    | **Type**    |
 352 +========================+=====================================================================================================================+==================+=============+
 353 | Limit Identifier       | Each limit defined for an entitlement or license key must be identified by a unique value (e.g., numbered 1,2,3…)   | String           | Mandatory   |
 354 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 355 | Limit Description      | Verbiage describing the limit.                                                                                      | String           | Mandatory   |
 356 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 357 | Limit Behavior         | Description of the actions taken when the limit boundaries are reached.                                             | String           | Mandatory   |
 358 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 359 | Limit Category         | Valid value: **location**                                                                                           | String           | Mandatory   |
 360 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 361 | Limit Type             | Valid values: **city, county, state, country, region, MSA, BTA, CLLI**                                              | String           | Mandatory   |
 362 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 363 | Limit List             | List of locations where the Vendor Product can be used or needs to be restricted from use                           | List of String   | Mandatory   |
 364 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 365 | Limit Set Type         | Indicates if the list is an inclusion or exclusion.                                                                 | String           | Mandatory   |
 366 |                        |                                                                                                                     |                  |             |
 367 |                        | Valid Values:                                                                                                       |                  |             |
 368 |                        |                                                                                                                     |                  |             |
 369 |                        | **Allowed**                                                                                                         |                  |             |
 370 |                        |                                                                                                                     |                  |             |
 371 |                        | **Not allowed**                                                                                                     |                  |             |
 372 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 373 | Limit Quantification   | The quantity (amount) the limit expresses.                                                                          | Number           | Optional    |
 374 +------------------------+---------------------------------------------------------------------------------------------------------------------+------------------+-------------+
 375
 376 1. Time
 377
 378 Limit on the length of time the software may be used. For example:
 379
 380 -  license key valid for 1 year from activation
 381
 382 -  entitlement valid from 15 May 2018 thru 30 June 2020
 383
 384 Table C5. Required Fields for Time
 385 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 386
 387 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 388 | **Field Name**         | **Description**                                                                                                               | **Data Type**    | **Type**      |
 389 +========================+===============================================================================================================================+==================+===============+
 390 | Limit Identifier       | Each limit defined for an entitlement or license key must be identified by a unique value (e.g., numbered)                    | String           | Mandatory     |
 391 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 392 | Limit Description      | Verbiage describing the limit.                                                                                                | String           | Mandatory     |
 393 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 394 | Limit Behavior         | Description of the actions taken when the limit boundaries are reached.                                                       | String           | Mandatory     |
 395 |                        |                                                                                                                               |                  |               |
 396 |                        | The limit behavior may also describe when a time limit takes effect. (e.g., key is valid for 1 year from date of purchase).   |                  |               |
 397 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 398 | Limit Category         | Valid value: **time**                                                                                                         | String           | Mandatory     |
 399 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 400 | Limit Type             | Valid values: **duration, date**                                                                                              | String           | Mandatory     |
 401 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 402 | Limit List             | List of times for which the Vendor Product can be used or needs to be restricted from use                                     | List of String   | Mandatory     |
 403 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 404 | Duration Units         | Required when limit type is duration. Valid values: **perpetual, year, quarter, month, day, minute, second, millisecond**     | String           | Conditional   |
 405 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 406 | Limit Quantification   | The quantity (amount) the limit expresses.                                                                                    | Number           | Optional      |
 407 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 408 | Start Date             | Required when limit type is date.                                                                                             | Date             | Optional      |
 409 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 410 | End Date               | May be used when limit type is date.                                                                                          | Date             | Optional      |
 411 +------------------------+-------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
 412
 413 1. Usage
 414
 415 Limits based on how the software is used. For example:
 416
 417 -  use is limited to a specific sub-set of the features/capabilities the
 418    software supports
 419
 420 -  use is limited to a certain environment (e.g., test, development,
 421    production…)
 422
 423 -  use is limited by processor (vm, cpu, core)
 424
 425 -  use is limited by software release
 426
 427 Table C6. Required Fields for Usage
 428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 429
 430 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 431 | **Field Name**         | **Description**                                                                                              | **Data Type**    | **Type**    |
 432 +========================+==============================================================================================================+==================+=============+
 433 | Limit Identifier       | Each limit defined for an entitlement or license key must be identified by a unique value (e.g., numbered)   | String           | Mandatory   |
 434 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 435 | Limit Description      | Verbiage describing the limit.                                                                               | String           | Mandatory   |
 436 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 437 | Limit Behavior         | Description of the actions taken when the limit boundaries are reached.                                      | String           | Mandatory   |
 438 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 439 | Limit Category         | Valid value: **usages**                                                                                      | String           | Mandatory   |
 440 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 441 | Limit Type             | Valid values: **feature, environment, processor, version**                                                   | String           | Mandatory   |
 442 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 443 | Limit List             | List of usage limits (e.g., test, development, vm, core, R1.2.1, R1.3.5…)                                    | List of String   | Mandatory   |
 444 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 445 | Limit Set Type         | Indicates if the list is an inclusion or exclusion.                                                          | String           | Mandatory   |
 446 |                        |                                                                                                              |                  |             |
 447 |                        | Valid Values:                                                                                                |                  |             |
 448 |                        |                                                                                                              |                  |             |
 449 |                        | **Allowed**                                                                                                  |                  |             |
 450 |                        |                                                                                                              |                  |             |
 451 |                        | **Not allowed**                                                                                              |                  |             |
 452 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 453 | Limit Quantification   | The quantity (amount) the limit expresses.                                                                   | Number           | Optional    |
 454 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 455
 456 1. Entity
 457
 458 Limit on the entity (product line, organization, customer) allowed to
 459 make use of the software. For example:
 460
 461 -  allowed to be used in support of wireless products
 462
 463 -  allowed to be used only for government entities
 464
 465 Table C7. Required Fields for Entity
 466 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 467
 468 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 469 | **Field Name**         | **Description**                                                                                              | **Data Type**    | **Type**    |
 470 +========================+==============================================================================================================+==================+=============+
 471 | Limit Identifier       | Each limit defined for an entitlement or license key must be identified by a unique value (e.g., numbered)   | String           | Mandatory   |
 472 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 473 | Limit Description      | Verbiage describing the limit.                                                                               | String           | Mandatory   |
 474 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 475 | Limit Behavior         | Description of the actions taken when the limit boundaries are reached.                                      | String           | Mandatory   |
 476 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 477 | Limit Category         | Valid value: **entity**                                                                                      | String           | Mandatory   |
 478 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 479 | Limit Type             | Valid values: **product line, organization, internal customer, external customer**                           | String           | Mandatory   |
 480 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 481 | Limit List             | List of entities for which the Vendor Product can be used or needs to be restricted from use                 | List of String   | Mandatory   |
 482 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 483 | Limit Set Type         | Indicates if the list is an inclusion or exclusion.                                                          | String           | Mandatory   |
 484 |                        |                                                                                                              |                  |             |
 485 |                        | Valid Values:                                                                                                |                  |             |
 486 |                        |                                                                                                              |                  |             |
 487 |                        | **Allowed**                                                                                                  |                  |             |
 488 |                        |                                                                                                              |                  |             |
 489 |                        | **Not allowed**                                                                                              |                  |             |
 490 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 491 | Limit Quantification   | The quantity (amount) the limit expresses.                                                                   | Number           | Optional    |
 492 +------------------------+--------------------------------------------------------------------------------------------------------------+------------------+-------------+
 493
 494 1. Amount
 495
 496 These limits describe terms relative to utilization of the functions of
 497 the software (for example, number of named users permitted, throughput,
 498 or capacity). Limits of this type may also be relative to utilization of
 499 other resources (for example, a limit for firewall software is not based
 500 on use of the firewall software, but on the number of network
 501 subscribers).
 502
 503 The metadata describing this type of limit includes the unit of measure
 504 (e.g., # users, # sessions, # MB, # TB, etc.), the quantity of units,
 505 any aggregation function (e.g., peak or average users), and aggregation
 506 interval (day, month, quarter, year, etc.).
 507
 508 Table C8. Required Fields for Amount
 509 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 510
 511 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 512 | **Field Name**         | **Description**                                                                                                                                                                                                                                                | **Data Type**   | **Type**    |
 513 +========================+================================================================================================================================================================================================================================================================+=================+=============+
 514 | Limit Identifier       | Each limit defined for an entitlement or license key must be identified by a unique value (e.g., numbered)                                                                                                                                                     | String          | Mandatory   |
 515 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 516 | Limit Description      | Verbiage describing the limit.                                                                                                                                                                                                                                 | String          | Mandatory   |
 517 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 518 | Limit Behavior         | Description of the actions taken when the limit boundaries are reached.                                                                                                                                                                                        | String          | Mandatory   |
 519 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 520 | Limit Category         | Valid value: **amount**                                                                                                                                                                                                                                        | String          | Mandatory   |
 521 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 522 | Limit Type             | Valid values: **trunk, user, subscriber, session, token, transactions, seats, KB, MB, TB, GB**                                                                                                                                                                 | String          | Mandatory   |
 523 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 524 | Type of Utilization    | Is the limit relative to utilization of the functions of the software or relative to utilization of other resources?                                                                                                                                           | String          | Mandatory   |
 525 |                        |                                                                                                                                                                                                                                                                |                 |             |
 526 |                        | Valid values:                                                                                                                                                                                                                                                  |                 |             |
 527 |                        |                                                                                                                                                                                                                                                                |                 |             |
 528 |                        | -  **software functions**                                                                                                                                                                                                                                      |                 |             |
 529 |                        |                                                                                                                                                                                                                                                                |                 |             |
 530 |                        | -  **other resources**                                                                                                                                                                                                                                         |                 |             |
 531 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 532 | Limit Quantification   | The quantity (amount) the limit expresses.                                                                                                                                                                                                                     | Number          | Optional    |
 533 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 534 | Aggregation Function   | Valid values: **peak, average**                                                                                                                                                                                                                                | String          | Optional    |
 535 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 536 | Aggregation Interval   | Time period over which the aggregation is done (e.g., average sessions per quarter). Required when an Aggregation Function is specified.                                                                                                                       | String          | Optional    |
 537 |                        |                                                                                                                                                                                                                                                                |                 |             |
 538 |                        | Valid values: **day, month, quarter, year, minute, second, millisecond**                                                                                                                                                                                       |                 |             |
 539 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 540 | Aggregation Scope      | Is the limit quantity applicable to a single entitlement or license key (each separately)? Or may the limit quantity be combined with others of the same type (resulting in limit amount that is the sum of all the purchased entitlements or license keys)?   | String          | Optional    |
 541 |                        |                                                                                                                                                                                                                                                                |                 |             |
 542 |                        | Valid values:                                                                                                                                                                                                                                                  |                 |             |
 543 |                        |                                                                                                                                                                                                                                                                |                 |             |
 544 |                        | -  **single**                                                                                                                                                                                                                                                  |                 |             |
 545 |                        |                                                                                                                                                                                                                                                                |                 |             |
 546 |                        | -  **combined**                                                                                                                                                                                                                                                |                 |             |
 547 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 548 | Type of User           | Describes the types of users of the functionality offered by the software (e.g., authorized, named). This field is included when Limit Type is user.                                                                                                           | String          | Optional    |
 549 +------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------+-------------+
 550
 551
 552 **Appendix D – Ansible Server Specification**
 553
 554 This section outlines the specifications for an ONAP compliant Ansible
 555 Server that can optionally be provided by the VNF Vendor. The Ansible
 556 Server will be used as a repository to store Ansible playbooks as well
 557 as an execution engine which upon a REST API request, will execute
 558 Ansible playbook against VNFs.
 559
 560 Table D1. Ansible Server Requirements
 561 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 562
 563 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 564 | **Principle**                                | **Description**                                                                                                                                                                                                                                                                                                                                                              | **Type**   | **ID #**   |
 565 +==============================================+==============================================================================================================================================================================================================================================================================================================================================================================+============+============+
 566 | Ansible Server Scope                         |     The Ansible Server is required to support storage and execution of playbooks that are in yaml format or a collection of playbooks compressed and uploaded in tar-ball format.                                                                                                                                                                                            | Must       | D1000      |
 567 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 568 |                                              |     The Ansible Server must accept requests for execution of playbooks via a REST interface. The scope of each request will involve exactly one action and will request execution of one playbook.                                                                                                                                                                           | Must       | D1010      |
 569 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 570 |                                              |     The playbook executed by the Ansible Server will be responsible for execution of the entire action against the VNF (e.g., calling other playbooks, running tasks on multiple VMs in the VNF) and return back the status of the action as well as any necessary output in its entirety after the action is finished.                                                      | Must       | D1020      |
 571 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 572 |                                              |     The Ansible Server must support simultaneous execution of multiple playbooks against different VNFs in parallel (i.e., process multiple requests).                                                                                                                                                                                                                       | Must       | D1030      |
 573 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 574 |                                              | The Ansible Server will be loaded with all necessary credentials to invoke playbooks against target VNF(s).                                                                                                                                                                                                                                                                  | Must       | D1040      |
 575 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 576 | Ansible Server/ONAP Interface                | Load Playbook\ **:** The Ansible Server must expose an authenticated interface to allow loading all necessary playbooks for a target VNF. It should impose an identification mechanism that allows each playbook to be uniquely identified.                                                                                                                                  | Must       | D1050      |
 577 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 578 |                                              | -  It is recommended that the load Playbook API be a REST API.                                                                                                                                                                                                                                                                                                               |            |            |
 579 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 580 |                                              | Request API: The Ansible Server must expose a REST endpoint that accepts a POST message to request execution of the playbook. The POST request must be a JSON block as outlined in Table D2.                                                                                                                                                                                 | Must       | D1060      |
 581 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 582 |                                              | When the Ansible server accepts an authenticated request to execute a playbook, it is required to send back an initial response indicating whether the request is accepted or rejected. The response must be a JSON Object with the key value pairs as described in Table D3.                                                                                                | Must       | D1070      |
 583 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 584 |                                              | Result API: If the Ansible Server accepts a request to execute a playbook, it must make available status of the execution of the playbook at a Results REST endpoint indexed by the Id in the request in the form <url>?Id=<RequestId>&Type=GetResult where <url> is the URL used for submitting requests.                                                                   | Must       | D1080      |
 585 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 586 |                                              | When a GET is invoked against the Results REST endpoint, the Ansible Server must reply with an appropriate response:                                                                                                                                                                                                                                                         | Must       | D1090      |
 587 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 588 |                                              | -  If the Endpoint is invalid (no request, or request expired), reply with a standard HTTP 404 error.                                                                                                                                                                                                                                                                        |            |            |
 589 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 590 |                                              | -  If the playbook execution is still ongoing, then the Ansible Server is required to block on the GET request till the execution finishes or terminates.                                                                                                                                                                                                                    |            |            |
 591 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 592 |                                              | -  Upon completion of execution, the Ansible Server is required to respond to the GET request with the result of the playbook execution in the form of a JSON message as outlined in the Table D4.                                                                                                                                                                           |            |            |
 593 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 594 |                                              | The dictionary associated with the ‘Results’ key in the Result Response must be a key-value pair where each key corresponds to an entry in the NodeList and the value is a dictionary with the format as outlined in Table D5.                                                                                                                                               | Must       | D1100      |
 595 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 596 | Ansible Server Actions                       | The Ansible Server must take the following actions when triggered by a request to execute a playbook:                                                                                                                                                                                                                                                                        | Must       | D1110      |
 597 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 598 |                                              | -  Determine if the request is valid, and if so, must send back an initial response message accepting the request.                                                                                                                                                                                                                                                           |            |            |
 599 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 600 |                                              | -  If the request contains a “FileParameters” key that is not NULL, create all the necessary files.                                                                                                                                                                                                                                                                          |            |            |
 601 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 602 |                                              | -  Invoke the ansible playbook while providing it all appropriate parameters listed in EnvParameters and inventory information listed in NodeList. The playbook will be responsible for execution of all necessary steps required by the VNF action.                                                                                                                         |            |            |
 603 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 604 |                                              | -  If the playbook finishes, use the PLAY\_RECAP functionality to determine whether playbook finished successfully on each endpoint identified in the NodeList.                                                                                                                                                                                                              |            |            |
 605 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 606 |                                              | -  If the playbook finishes, collect any output returned by the playbook. A playbook conforming to the ONAP vendor requirements document will write out any necessary output to a file named ‘<hostname>\_results.txt’ in the working directory, where ‘hostname’ is an element of the NodeList where the playbook is being executed.                                        |            |            |
 607 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 608 |                                              | -  If the playbook execution exceeds the Timeout value, the playbook execution process is terminated and ansible log that captures the last task executed is stored.                                                                                                                                                                                                         |            |            |
 609 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 610 |                                              | -  Make results available on the Results REST Endpoint as documented in Table D3.                                                                                                                                                                                                                                                                                            |            |            |
 611 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 612 |                                              | -  If Callback url was provided in initial request, post the final response message on the Callback URL along with an additional key additional key “Id “: which corresponds to the request Id sent in the request.                                                                                                                                                          |            |            |
 613 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 614 | Ansible Server Result Storage Requirements   | The Ansible Server must cache and provide results of an execution as well as retain logs for debugging purposes as outlined below:                                                                                                                                                                                                                                           | Must       | D1120      |
 615 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 616 |                                              | -  The results from a playbook execution result must be retained by the Ansible Server and made available through the respective REST endpoint for a duration that is configurable.                                                                                                                                                                                          |            |            |
 617 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 618 |                                              |    -  Recommended duration is 2 x Timeout.                                                                                                                                                                                                                                                                                                                                   |            |            |
 619 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 620 |                                              | -  The log from a playbook must be stored by the Ansible Server, tagged with the Id along with all other parameters in the initial request in a format that allows for examination for debugging purposes.                                                                                                                                                                   |            |            |
 621 |                                              |                                                                                                                                                                                                                                                                                                                                                                              |            |            |
 622 |                                              | -  The results from playbook execution and log files shall be removed after a configurable defined retention period for this type of file.                                                                                                                                                                                                                                   |            |            |
 623 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 624 | Ansible Server Locking Mechanism             | The Ansible Server shall lock VNF while running playbooks that require exclusive use of a VNF (Configure is an example) and not accept requests to run other playbooks or queue those requests until playbook that requires exclusivity completes                                                                                                                            | Must       | D1130      |
 625 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+
 626
 627 Table D2. Request Message
 628 ~~~~~~~~~~~~~~~~~~~~~~~~~
 629
 630 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 631 | **Key**           | **Description**                                                                                                                                                                                                                                                                                                                                         | **Type**    | **Comment**                                                                                                                        |
 632 +===================+=========================================================================================================================================================================================================================================================================================================================================================+=============+====================================================================================================================================+
 633 | Id                | A unique string that identifies this request. For e.g., a UUID                                                                                                                                                                                                                                                                                          | Mandatory   | NOT NULL                                                                                                                           |
 634 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 635 | PlaybookName      | A string which contains the name of the playbook to execute.                                                                                                                                                                                                                                                                                            | Mandatory   | NOT NULL                                                                                                                           |
 636 |                   |                                                                                                                                                                                                                                                                                                                                                         |             |                                                                                                                                    |
 637 |                   | Example: memthres.yaml                                                                                                                                                                                                                                                                                                                                  |             |                                                                                                                                    |
 638 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 639 | Action            | Name of action                                                                                                                                                                                                                                                                                                                                          | Optional    |                                                                                                                                    |
 640 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 641 | NodeList          | List of endpoints of the VNF against which the playbook should be executed.                                                                                                                                                                                                                                                                             | Optional    | If not specified, playbook executed within Ansible Server (localhost)                                                              |
 642 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 643 | Timeout           | Time the Ansible Server should wait (in seconds), before terminating playbook execution. The Ansible Server will apply the timeout for the entire playbook execution (i.e., independent of number of endpoints against which the playbook is executing). If playbook execution time exceeds the timeout value, the server will terminate the process.   | Optional    | If not specified, Ansible server will use internal default value (configurable)                                                    |
 644 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 645 | LocalParameters   | A JSON dictionary that can be used to provide key value pairs that are specific to each individual VNF/VM instance. Key must be endpoint FQDN and value a JSON dictionary with key-value pairs for the playbook run associated with that host/group.                                                                                                    | Optional    |                                                                                                                                    |
 646 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 647 | EnvParameters     | A JSON dictionary that can be used to specify key value pairs passed at run time to the playbook that are common across all hosts against which the playbook will run.                                                                                                                                                                                  | Optional    |                                                                                                                                    |
 648 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 649 | CallbackUrl       | A callback URL that Ansible Server can POST results to once playbook finishes execution or is terminated.                                                                                                                                                                                                                                               | Optional    | If present, Ansible Server is required to POST response back on the Callback URL                                                   |
 650 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 651 | FileParameters    | A dictionary where keys correspond to file names to be generated and values correspond to contents of files.                                                                                                                                                                                                                                            | Optional    | If present, Ansible Server will first process this and write out contents to appropriate files and then process other parameters   |
 652 +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+------------------------------------------------------------------------------------------------------------------------------------+
 653
 654 Table D3. Initial Response Message
 655 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 656
 657 +--------------------+------------------------------------------------------------------------------------------+-------------+---------------+
 658 | **Key**            | **Description**                                                                          | **Type**    | **Comment**   |
 659 +====================+==========================================================================================+=============+===============+
 660 | StatusCode         | An integer indicating status of the request. It MUST take one of the following values:   | Mandatory   |               |
 661 |                    |                                                                                          |             |               |
 662 |                    | 100 if request is accepted                                                               |             |               |
 663 |                    |                                                                                          |             |               |
 664 |                    | 101 if request is rejected                                                               |             |               |
 665 +--------------------+------------------------------------------------------------------------------------------+-------------+---------------+
 666 | StatusMessage      | A string describing Server’s response                                                    | Mandatory   |               |
 667 |                    |                                                                                          |             |               |
 668 |                    | It MUST be set to ‘PENDING’ if StatusCode=100                                            |             |               |
 669 |                    |                                                                                          |             |               |
 670 |                    | It MUST be set to appropriate error exception message if StatusCode=101                  |             |               |
 671 +--------------------+------------------------------------------------------------------------------------------+-------------+---------------+
 672 | ExpectedDuration   | Time the server expects (in seconds) to finish the playbook execution.                   | Optional    |               |
 673 +--------------------+------------------------------------------------------------------------------------------+-------------+---------------+
 674
 675 Table D4. Final Response Message
 676 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 677
 678 +-----------------+-------------------------------------------------------------------------------------------------------+-------------+------------------------+
 679 | **Key**         | **Description**                                                                                       | **Type**    | **Comment**            |
 680 +=================+=======================================================================================================+=============+========================+
 681 | StatusCode      | 200 if Execution finished normally                                                                    | Mandatory   |                        |
 682 |                 |                                                                                                       |             |                        |
 683 |                 | 500 otherwise.                                                                                        |             |                        |
 684 +-----------------+-------------------------------------------------------------------------------------------------------+-------------+------------------------+
 685 | StatusMessage   | A string which be set to either of the TWO values:                                                    | Mandatory   |                        |
 686 |                 |                                                                                                       |             |                        |
 687 |                 | -  ‘FINISHED’ if StatusCode=200                                                                       |             |                        |
 688 |                 |                                                                                                       |             |                        |
 689 |                 | -  Appropriate error exception message if StatusCode=500                                              |             |                        |
 690 +-----------------+-------------------------------------------------------------------------------------------------------+-------------+------------------------+
 691 | Duration        | Time it took for execution to finish (in seconds).                                                    | Optional    |                        |
 692 +-----------------+-------------------------------------------------------------------------------------------------------+-------------+------------------------+
 693 | Result          | A JSON dictionary that lists the status of playbook execution for each VM (or VNF) in the NodeList.   | Optional    | Not present if empty   |
 694 +-----------------+-------------------------------------------------------------------------------------------------------+-------------+------------------------+
 695
 696 Table D5. Result Block Format
 697 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 698
 699 +-----------------+----------------------------------------------------------+-------------+------------------------+
 700 | **Key**         | **Description**                                          | **Type**    | **Comment**            |
 701 +=================+==========================================================+=============+========================+
 702 | GroupName       | Group under which the VM (or VNF) falls in a playbook.   | Optional    |                        |
 703 +-----------------+----------------------------------------------------------+-------------+------------------------+
 704 | StatusCode      | A string which must have the following values:           | Mandatory   |                        |
 705 |                 |                                                          |             |                        |
 706 |                 | -  200 if SUCCESS                                        |             |                        |
 707 |                 |                                                          |             |                        |
 708 |                 | -  500 otherwise                                         |             |                        |
 709 +-----------------+----------------------------------------------------------+-------------+------------------------+
 710 | StatusMessage   | An integer with the following values:                    | Mandatory   |                        |
 711 |                 |                                                          |             |                        |
 712 |                 | -  ‘SUCCESS’ if StatusCode=200                           |             |                        |
 713 |                 |                                                          |             |                        |
 714 |                 | -  Error exception message otherwise                     |             |                        |
 715 +-----------------+----------------------------------------------------------+-------------+------------------------+
 716 | Output          | Any output the playbook is required to return.           | Optional    | Not present if empty   |
 717 +-----------------+----------------------------------------------------------+-------------+------------------------+
 718
 719 Some illustrative examples are shown below:
 720
 721 1. An example POST for requesting execution of a Playbook :
 722
 723    {"Id": "10", “Action”:”HealthCheck”, "PlaybookName":
 724    "ansible\_getresource.yml", "NodeList":
 725    ["interface1.vnf\_b.onap.com", ["interface2.vnf\_b.onap.com"],
 726    "Timeout": 60, "EnvParameters": {"Retry": 3, "Wait": 5}}
 727
 728 2. Potential examples of Ansible Server initial response.
 729
 730    a. Successfully accepted request: {"StatusCode": "100",
 731       "ExpectedDuration": "60sec", "StatusMessage": "PENDING"}
 732
 733    b. Request rejected: {"StatusCode": "101", "StatusMessage": "PLAYBOOK
 734       NOT FOUND "}
 735
 736 3. Potential examples of final response by Ansible Server to a GET on
 737
 738    a. Playbook successful execution: {"Duration": "4.864815sec",
 739       “StatusCode”: 200, “StatusMessage”:”FINISHED”, "Results":
 740       {"interface\_1.vnf\_b.onap.com": {"StatusCode": "200",
 741       "GroupName": "vnf-x-oam", "StatusMessage": "SUCCESS",
 742       “Output”:{“CPU”:30, “Memory”:”5Gb”},
 743       "interface\_1.vnf\_b.onap.com": {"StatusCode": "200", "GroupName":
 744       "vnf-x-oam", "StatusMessage": "SUCCESS", “Output”:{“CPU”:60,
 745       “Memory”:”10Gb”}}}
 746
 747    b. Playbook failed execution on one of the hosts: {"Duration":
 748       "10.8sec", “StatusCode”: 200, “StatusMessage”:”FINISHED”,
 749       "Results": {"interface\_1.vnf\_b.onap.com": {"StatusCode": "500",
 750       "GroupName": "vnf-x-oam", "StatusMessage": "Error executing
 751       command ", "interface\_1.vnf\_b.onap.com": {"StatusCode": "200",
 752       "GroupName": "vnf-x-oam", "StatusMessage": "SUCCESS",
 753       “Output”:{“CPU”:60, “Memory”:”10Gb”}}}
 754
 755    c. Playbook terminated: {"Duration": "61 sec", “StatusCode”: 500,
 756       “StatusMessage”:”TERMINATED” }
 757
 758
 759 .. [2]
 760    https://github.com/mbj4668/pyang
 761
 762 .. [3]
 763    Decision on which Chef Server instance associates with a VNF will be
 764    made on a case-by-case basis depending on VNF, access requirements,
 765    etc. and are outside the scope of this document. The specific
 766    criteria for this would involve considerations like connectivity and
 767    access required by the VNF, security, VNF topology and proprietary
 768    cookbooks.
 769
 770 .. [4]
 771    Recall that the Node Object **is required** to be identical across
 772    all VMs of a VNF invoked as part of the action except for the “name”.
 773
 774 .. [5]
 775    Decision on which Ansible Server to use may happen on a case-by-case
 776    basis depending on VNF, access requirements etc. and are outside the
 777    scope of this document. The specific criteria for this could involve
 778    considerations like connectivity and access required by the VNF,
 779    security, VNF topology and proprietary playbooks.
 780
 781 .. [6]
 782    Upstream elements must provide the appropriate FQDN in the request to
 783    ONAP for the desired action.
 784
 785 .. [7]
 786    Multiple ONAP actions may map to one playbook.
 787
 788 .. [8]
 789    This option is not currently supported in ONAP and it is currently
 790    under consideration.
 791
 792 .. [9]
 793    https://wiki.opnfv.org/display/PROJ/VNF+Event+Stream
 794
 795 .. [10]
 796    The “name” field is a mandatory field in a valid Chef Node Object
 797    JSON dictionary.