docs/Chapter7/Configuration-Management.rst

   1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
   2
   3 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   4    (the "License"); you may not use this documentation except in compliance
   5    with the License. You may obtain a copy of the License at
   6
   7 .. https://creativecommons.org/licenses/by/4.0/
   8
   9 .. Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15
  16 Configuration Management
  17 ------------------------
  18
  19 Controller Interactions With VNF
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 ONAP Controllers (such as APPC) expose a northbound API to clients
  23 (such as SO) in order for the clients to initiate an activity
  24 (aka command) on a VNF.   ONAP controllers interact with VNFs through
  25 Network and Application Adapters to perform configuration and other
  26 lifecycle management activities within NFV environment.
  27 The standardized models, protocols and mechanisms by which network
  28 functions are configured are equally applicable to VNFs and PNFs.
  29
  30 This section describes the list of commands that should be supported
  31 by the VNF.   The following sections describe the standard protocols
  32 that are supported (NETCONF, Chef, Ansible, and REST).
  33
  34 The commands below are expected to be supported on all VNF's, unless
  35 noted otherwise, either directly (via the NETCONF or REST interface)
  36 or indirectly (via a Chef Cookbook or Ansible server).  Note that there
  37 are additional commands offered to northbound clients that are not shown
  38 below, as these commands either act internally on the Controller itself
  39 or depend upon network cloud components for implementation (thus, these
  40 actions do not put any special requirement on the VNF provider).
  41
  42 The commands allow for parametric data to be passed from the controller
  43 to the VNF or Ansible/Chef server in the request.  The format of the
  44 parameter data can be either xml (for NETCONF) or JSON (for Ansible,
  45 Chef, or REST).
  46
  47 Configuration Commands
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 **Configure**: The Controller client is requesting that a post-instantiation
  51 configuration be applied to the target VNF instance. After the Configure
  52 action is completed, the VNF instance should be ready for service.
  53 Note that customer specific configurations may need to be applied using
  54 the ConfigModify action.
  55
  56 **ConfigModify**: The Controller client is requesting a configuration
  57 update to a subset of the total configuration parameters of a VNF or to
  58 apply customer specific configurations. The configuration update is
  59 typically done while the VNF is in service and should not disrupt traffic.
  60
  61 **ConfigBackup**: The Controller client is requesting a backup of the
  62 configuration parameters where the parameters are stored on the VNF.
  63 This command is typically requested as part of an orchestration flow
  64 for scenarios such as a software upgrade. The ConfigBackup is typically
  65 done while the VNF is not in service (i.e., in a maintenance state).
  66 When the ConfigBackup command is executed, the current VNF configuration
  67 parameters are saved in storage that is preserved (if there is an existing
  68 set of backed up parameters, they are overwritten).
  69
  70 **ConfigRestore**: The Controller client is requesting a restore action of
  71 the configuration parameters to the VNF that were saved by ConfigBackup
  72 command. This command is typically requested as part of an orchestration
  73 flow for scenarios such as a software upgrade where the software upgrade
  74 may have failed and the VNF needs to be rolled back to the prior configuration.
  75 When the ConfigRestore command is executed, the VNF configuration parameters
  76 which were backed to persistent preserved storage are applied to the VNF
  77 (replacing existing parameters). The ConfigRestore is typically done while
  78 the VNF is not in service (i.e., in a maintenance state).
  79
  80 **ConfigScaleOut**: The Controller client is requesting that a configuration
  81 be applied after the VNF instance has been scaled out (i.e., one or more
  82 additional VM's instantiated to increase capacity). For some VNF's,
  83 ConfigScaleOut is not needed because the VNF is auto-configured after
  84 scale-out. This command is being introduced in the Beijing release.
  85
  86 **Audit**: The Controller client is requesting that the current (last known
  87 configuration update) is audited against the running configuration on the VNF.
  88
  89
  90 .. req::
  91     :id: R-20741
  92     :target: XNF
  93     :keyword: MUST
  94
  95     The xNF **MUST** support ONAP Controller's **Configure** command.
  96
  97 .. req::
  98     :id: R-19366
  99     :target: XNF
 100     :keyword: MUST
 101
 102     The xNF **MUST** support ONAP Controller's **ConfigModify** command.
 103
 104 .. req::
 105     :id: R-32981
 106     :target: XNF
 107     :keyword: MUST
 108
 109     The xNF **MUST** support ONAP Controller's **ConfigBackup** command.
 110
 111 .. req::
 112     :id: R-48247
 113     :target: XNF
 114     :keyword: MUST
 115
 116     The xNF **MUST** support ONAP Controller's **ConfigRestore** command.
 117
 118 .. req::
 119     :id: R-94084
 120     :target: XNF
 121     :keyword: MUST
 122
 123     The xNF **MUST** support ONAP Controller's **ConfigScaleOut** command.
 124
 125 .. req::
 126     :id: R-56385
 127     :target: XNF
 128     :keyword: MUST
 129
 130     The xNF **MUST** support ONAP Controller's **Audit** command.
 131
 132 LifeCycle Management Related Commands
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 134
 135 **The following commands are needed to support various lifecycle management
 136 flows where the VNF may need to be removed for service.**
 137
 138 **QuiesceTraffic**: The Controller client is requesting the VNF gracefully
 139 stop traffic (aka block and drain traffic). The method for quiescing traffic
 140 is specific to the VNF architecture. The action is completed when all
 141 (in-flight transactions) traffic has stopped.   The VNF remains in an active
 142 state where the VNF is able to process traffic (initiated using the
 143 StartTraffic action).
 144
 145 **ResumeTraffic**: The Controller client is requesting the VNF resume
 146 processing traffic. The method to resume traffic is specific to the VNF
 147 architecture.
 148
 149 **StopApplication**: The Controller client is requesting that the application
 150 running on the VNF is stopped gracefully (i.e., without traffic loss).
 151 This is equivalent to quiescing the traffic and then stopping the application
 152 processes. The processes can be restarted using the StartApplication command.
 153
 154 **StartApplication**: The Controller client is requesting that the application
 155 running on the VNF is started. Get ready to process traffic.
 156
 157 **The following commands are needed to support software upgrades, in-place or
 158 other type of software upgrade. The VNF instance may be removed from service
 159 for the upgrade.**
 160
 161 **UpgradePrecheck**: The Controller client is requesting a confirmation that
 162 the VNF can (and needs to) be upgraded to a specific software version
 163 (specified in the request).
 164
 165 **UpgradeSoftware**: The Controller client is requesting that a (in-place)
 166 software upgrade be performed on the VNF.  The software to be applied is
 167 pre-loaded to a specified location.
 168
 169 **UpgradePostCheck**: The Controller client is requesting a confirmation that
 170 the VNF software upgrade has been completed successfully (VNF upgraded to
 171 the new software version).
 172
 173 **UpgradeBackup**: The Controller client is requesting that the VNF is backed
 174 up prior to the UpgradeSoftware.
 175
 176 **UpgradeBackOut**: The Controller client is requesting that the VNF upgrade
 177 is backed out (in the event that the SoftwareUpgrade or UpgradePostCheck
 178 failed).
 179
 180
 181 .. req::
 182     :id: R-12706
 183     :target: XNF
 184     :keyword: MUST
 185
 186     The xNF **MUST** support ONAP Controller's **QuiesceTraffic** command.
 187
 188 .. req::
 189     :id: R-07251
 190     :target: XNF
 191     :keyword: MUST
 192
 193     The xNF **MUST** support ONAP Controller's **ResumeTraffic** command.
 194
 195 .. req::
 196     :id: R-83146
 197     :target: XNF
 198     :keyword: MUST
 199
 200     The xNF **MUST** support ONAP Controller's **StopApplication** command.
 201
 202 .. req::
 203     :id: R-82811
 204     :target: XNF
 205     :keyword: MUST
 206
 207     The xNF **MUST** support ONAP Controller's **StartApplication** command.
 208
 209 .. req::
 210     :id: R-19922
 211     :target: XNF
 212     :keyword: MUST
 213
 214     The xNF **MUST** support ONAP Controller's **UpgradePrecheck** command.
 215
 216 .. req::
 217     :id: R-49466
 218     :target: XNF
 219     :keyword: MUST
 220
 221     The xNF **MUST** support ONAP Controller's **UpgradeSoftware** command.
 222
 223 .. req::
 224     :id: R-45856
 225     :target: XNF
 226     :keyword: MUST
 227
 228     The xNF **MUST** support ONAP Controller's **UpgradePostCheck** command.
 229
 230 .. req::
 231     :id: R-97343
 232     :target: XNF
 233     :keyword: MUST
 234
 235     The xNF **MUST** support ONAP Controller's **UpgradeBackup** command.
 236
 237 .. req::
 238     :id: R-65641
 239     :target: XNF
 240     :keyword: MUST
 241
 242     The xNF **MUST** support ONAP Controller's **UpgradeBackOut** command.
 243
 244 Virtual Function - Container Recovery Requirements
 245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 246
 247 As part of life cycle management, for Cloud environment, VNFs need to
 248 support a set of basic recovery capabilities to maintain the health
 249 and extend the life of the VNF, eliminating and reducing the frequency
 250 that an entire VNF needs to be rebuilt or re-instantiated to recover one
 251 or more of its containers. For instance, a VNF in an Openstack environment
 252 is composed of one or more containers called VMs (Virtual Machines). During
 253 the life of a VNF it is expected that Cloud infrastructure hardware will
 254 fail or they would need to be taken down for maintenance or hardware and
 255 software upgrades (e.g. firmware upgrades, HostOS (Hypervisor), power
 256 maintenance, power outages, etc.) To deal with such life cycle events
 257 without having to rebuild entire VNFs or even entire sites these basic
 258 recovery capabilities of individual containers, Virtual Machines or other,
 259 must be supported.
 260
 261
 262 .. req::
 263     :id: R-11790
 264     :target: VNF
 265     :keyword: MUST
 266
 267     The VNF **MUST** support ONAP Controller's
 268     **Restart (stop/start or reboot)** command.
 269
 270 .. req::
 271     :id: R-56218
 272     :target: VNF
 273     :keyword: MUST
 274
 275     The VNF **MUST** support ONAP Controller's Migrate command that
 276     moves container (VM) from a live Physical Server / Compute Node to
 277     another live Physical Server / Compute Node.
 278
 279         Note: Container migrations MUST be transparent to the VNF and no more intrusive than a stop,
 280         followed by some down time for the migration to be performed from one Compute Node / Physical
 281         Server to another, followed by a start of the same VM with same configuration on the new
 282         Compute Node / Physical Server.
 283
 284 .. req::
 285     :id: R-38001
 286     :target: VNF
 287     :keyword: MUST
 288
 289     The VNF **MUST** support ONAP Controller's **Rebuild** command.
 290
 291 .. req::
 292     :id: R-76901
 293     :target: VNF
 294     :keyword: MUST
 295
 296     The VNF **MUST** support a container rebuild mechanism based on existing
 297     image (e.g. Glance image in Openstack environment) or a snapshot.
 298
 299 HealthCheck and Failure Related Commands
 300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 301
 302 **HealthCheck**: The Controller client is requesting a health check over the
 303 entire scope of the VNF.  The VNF must be 100% healthy, ready to take requests
 304 and provide services, with all VNF required capabilities ready to provide
 305 services and with all active and standby resources fully ready with no open
 306 MINOR, MAJOR or CRITICAL alarms.
 307
 308 Note: In addition to the commands above, the Controller supports a set of
 309 Openstack failure recovery related commands that are executed on-demand or via
 310 Control Loop at the VM level.  The VNF must support these commands in a fully
 311 automated fashion.
 312
 313
 314 .. req::
 315     :id: R-41430
 316     :target: XNF
 317     :keyword: MUST
 318
 319     The xNF **MUST** support ONAP Controller's **HealthCheck** command.
 320
 321 Notes On Command Support Using Controller Southbound Protocols
 322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 323
 324 The ONAP Controllers are designed to support a standard set of protocols in
 325 order to communicate with the VNF instance.  The supported protocols are
 326 NETCONF, Ansible, Chef, and REST.
 327
 328 NETCONF and REST require the VNF to implement a server which supports the RPC
 329 or REST calls.
 330
 331 Ansible and Chef require the use of a Ansible or Chef server which communicates
 332 with the Controller (northbound) and the VNF VM's (southbound).
 333
 334 The vendor must select which protocol to support for the commands listed above.
 335 Notes:
 336
 337 * NETCONF is most suitable for configuration related commands
 338
 339 * Ansible and Chef are suitable for any command.
 340   Ansible has the advantage that it is agentless.
 341
 342 * REST is specified as an option only for the HealthCheck.
 343
 344
 345 Additional details can be found in the
 346 `ONAP Application Controller (APPC) API Guide <https://onap.readthedocs.io/en/latest/submodules/appc.git/docs/index.html>`_,
 347 `ONAP VF-C project <https://onap.readthedocs.io/en/latest/submodules/vfc/nfvo/lcm.git/docs/index.html>`_ and
 348 the `ONAP SDNC project <https://onap.readthedocs.io/en/latest/submodules/sdnc/oam.git/docs/index.html>`_.
 349
 350 NETCONF Standards and Capabilities
 351 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 352
 353 ONAP Controllers and their Adapters utilize device YANG model and
 354 NETCONF APIs to make the required changes in the VNF state and
 355 configuration. The VNF providers must provide the Device YANG model and
 356 NETCONF server supporting NETCONF APIs to comply with target ONAP and
 357 industry standards.
 358
 359 VNF Configuration via NETCONF Requirements
 360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 361
 362 Configuration Management
 363 +++++++++++++++++++++++++++
 364
 365
 366 .. req::
 367     :id: R-88026
 368     :target: XNF
 369     :keyword: MUST
 370
 371     The xNF **MUST** include a NETCONF server enabling
 372     runtime configuration and lifecycle management capabilities.
 373
 374 .. req::
 375     :id: R-95950
 376     :target: XNF
 377     :keyword: MUST
 378
 379     The xNF **MUST** provide a NETCONF interface fully defined
 380     by supplied YANG models for the embedded NETCONF server.
 381
 382 NETCONF Server Requirements
 383 ++++++++++++++++++++++++++++++
 384
 385
 386 .. req::
 387     :id: R-73468
 388     :target: XNF
 389     :keyword: MUST
 390
 391     The xNF **MUST** allow the NETCONF server connection
 392     parameters to be configurable during virtual machine instantiation
 393     through Heat templates where SSH keys, usernames, passwords, SSH
 394     service and SSH port numbers are Heat template parameters.
 395
 396 .. req::
 397     :id: R-90007
 398     :target: XNF
 399     :keyword: MUST
 400
 401     The xNF **MUST** implement the protocol operation:
 402     **close-session()**- Gracefully close the current session.
 403
 404 .. req::
 405     :id: R-70496
 406     :target: XNF
 407     :keyword: MUST
 408
 409     The xNF **MUST** implement the protocol operation:
 410     **commit(confirmed, confirm-timeout)** - Commit candidate
 411     configuration datastore to the running configuration.
 412
 413 .. req::
 414     :id: R-18733
 415     :target: XNF
 416     :keyword: MUST
 417
 418     The xNF **MUST** implement the protocol operation:
 419     **discard-changes()** - Revert the candidate configuration
 420     datastore to the running configuration.
 421
 422 .. req::
 423     :id: R-44281
 424     :target: XNF
 425     :keyword: MUST
 426
 427     The xNF **MUST** implement the protocol operation:
 428     **edit-config(target, default-operation, test-option, error-option,
 429     config)** - Edit the target configuration datastore by merging,
 430     replacing, creating, or deleting new config elements.
 431
 432 .. req::
 433     :id: R-60106
 434     :target: XNF
 435     :keyword: MUST
 436
 437     The xNF **MUST** implement the protocol operation:
 438     **get(filter)** - Retrieve (a filtered subset of) the running
 439     configuration and device state information. This should include
 440     the list of xNF supported schemas.
 441
 442 .. req::
 443     :id: R-29488
 444     :target: XNF
 445     :keyword: MUST
 446
 447     The xNF **MUST** implement the protocol operation:
 448     **get-config(source, filter)** - Retrieve a (filtered subset of
 449     a) configuration from the configuration datastore source.
 450
 451 .. req::
 452     :id: R-11235
 453     :target: XNF
 454     :keyword: MUST
 455
 456     The xNF **MUST** implement the protocol operation:
 457     **kill-session(session)** - Force the termination of **session**.
 458
 459 .. req::
 460     :id: R-02597
 461     :target: XNF
 462     :keyword: MUST
 463
 464     The xNF **MUST** implement the protocol operation:
 465     **lock(target)** - Lock the configuration datastore target.
 466
 467 .. req::
 468     :id: R-96554
 469     :target: XNF
 470     :keyword: MUST
 471
 472     The xNF **MUST** implement the protocol operation:
 473     **unlock(target)** - Unlock the configuration datastore target.
 474
 475 .. req::
 476     :id: R-29324
 477     :target: XNF
 478     :keyword: SHOULD
 479
 480     The xNF **SHOULD** implement the protocol operation:
 481     **copy-config(target, source) -** Copy the content of the
 482     configuration datastore source to the configuration datastore target.
 483
 484 .. req::
 485     :id: R-88031
 486     :target: XNF
 487     :keyword: SHOULD
 488
 489     The xNF **SHOULD** implement the protocol operation:
 490     **delete-config(target) -** Delete the named configuration
 491     datastore target.
 492
 493 .. req::
 494     :id: R-97529
 495     :target: XNF
 496     :keyword: SHOULD
 497
 498     The xNF **SHOULD** implement the protocol operation:
 499     **get-schema(identifier, version, format) -** Retrieve the YANG schema.
 500
 501 .. req::
 502     :id: R-62468
 503     :target: XNF
 504     :keyword: MUST
 505
 506     The xNF **MUST** allow all configuration data to be
 507     edited through a NETCONF <edit-config> operation. Proprietary
 508     NETCONF RPCs that make configuration changes are not sufficient.
 509
 510 .. req::
 511     :id: R-01382
 512     :target: XNF
 513     :keyword: MUST
 514
 515     The xNF **MUST** allow the entire configuration of the xNF to be
 516     retrieved via NETCONF's <get-config> and <edit-config>, independently
 517     of whether it was configured via NETCONF or other mechanisms.
 518
 519 .. req::
 520     :id: R-28756
 521     :target: XNF
 522     :keyword: MUST
 523
 524     The xNF **MUST** support **:partial-lock** and
 525     **:partial-unlock** capabilities, defined in RFC 5717. This
 526     allows multiple independent clients to each write to a different
 527     part of the <running> configuration at the same time.
 528
 529 .. req::
 530     :id: R-83873
 531     :target: XNF
 532     :keyword: MUST
 533
 534     The xNF **MUST** support **:rollback-on-error** value for
 535     the <error-option> parameter to the <edit-config> operation. If any
 536     error occurs during the requested edit operation, then the target
 537     database (usually the running configuration) will be left unaffected.
 538     This provides an 'all-or-nothing' edit mode for a single <edit-config>
 539     request.
 540
 541 .. req::
 542     :id: R-68990
 543     :target: XNF
 544     :keyword: MUST
 545
 546     The xNF **MUST** support the **:startup** capability. It
 547     will allow the running configuration to be copied to this special
 548     database. It can also be locked and unlocked.
 549
 550 .. req::
 551     :id: R-68200
 552     :target: XNF
 553     :keyword: MUST
 554
 555     The xNF **MUST** support the **:url** value to specify
 556     protocol operation source and target parameters. The capability URI
 557     for this feature will indicate which schemes (e.g., file, https, sftp)
 558     that the server supports within a particular URL value. The 'file'
 559     scheme allows for editable local configuration databases. The other
 560     schemes allow for remote storage of configuration databases.
 561
 562 .. req::
 563     :id: R-20353
 564     :target: XNF
 565     :keyword: MUST
 566
 567     The xNF **MUST** implement both **:candidate** and
 568     **:writable-running** capabilities. When both **:candidate** and
 569     **:writable-running** are provided then two locks should be supported.
 570
 571 .. req::
 572     :id: R-11499
 573     :target: XNF
 574     :keyword: MUST
 575
 576     The xNF **MUST** fully support the XPath 1.0 specification
 577     for filtered retrieval of configuration and other database contents.
 578     The 'type' attribute within the <filter> parameter for <get> and
 579     <get-config> operations may be set to 'xpath'. The 'select' attribute
 580     (which contains the XPath expression) will also be supported by the
 581     server. A server may support partial XPath retrieval filtering, but
 582     it cannot advertise the **:xpath** capability unless the entire XPath
 583     1.0 specification is supported.
 584
 585 .. req::
 586     :id: R-83790
 587     :target: XNF
 588     :keyword: MUST
 589
 590     The xNF **MUST** implement the **:validate** capability.
 591
 592 .. req::
 593     :id: R-49145
 594     :target: XNF
 595     :keyword: MUST
 596
 597     The xNF **MUST** implement **:confirmed-commit** If
 598     **:candidate** is supported.
 599
 600 .. req::
 601     :id: R-58358
 602     :target: XNF
 603     :keyword: MUST
 604
 605     The xNF **MUST** implement the **:with-defaults** capability
 606     [RFC6243].
 607
 608 .. req::
 609     :id: R-59610
 610     :target: XNF
 611     :keyword: MUST
 612
 613     The xNF **MUST** implement the data model discovery and
 614     download as defined in [RFC6022].
 615
 616 .. req::
 617     :id: R-93443
 618     :target: XNF
 619     :keyword: MUST
 620
 621     The xNF **MUST** define all data models in YANG [RFC6020],
 622     and the mapping to NETCONF shall follow the rules defined in this RFC.
 623
 624 .. req::
 625     :id: R-26115
 626     :target: XNF
 627     :keyword: MUST
 628
 629     The xNF **MUST** follow the data model upgrade rules defined
 630     in [RFC6020] section 10. All deviations from section 10 rules shall
 631     be handled by a built-in automatic upgrade mechanism.
 632
 633 .. req::
 634     :id: R-10716
 635     :target: XNF
 636     :keyword: MUST
 637
 638     The xNF **MUST** support parallel and simultaneous
 639     configuration of separate objects within itself.
 640
 641 .. req::
 642     :id: R-29495
 643     :target: XNF
 644     :keyword: MUST
 645
 646     The xNF **MUST** support locking if a common object is
 647     being manipulated by two simultaneous NETCONF configuration operations
 648     on the same xNF within the context of the same writable running data
 649     store (e.g., if an interface parameter is being configured then it
 650     should be locked out for configuration by a simultaneous configuration
 651     operation on that same interface parameter).
 652
 653 .. req::
 654     :id: R-53015
 655     :target: XNF
 656     :keyword: MUST
 657
 658     The xNF **MUST** apply locking based on the sequence of
 659     NETCONF operations, with the first configuration operation locking
 660     out all others until completed.
 661
 662 .. req::
 663     :id: R-02616
 664     :target: XNF
 665     :keyword: MUST
 666
 667     The xNF **MUST** permit locking at the finest granularity
 668     if a xNF needs to lock an object for configuration to avoid blocking
 669     simultaneous configuration operations on unrelated objects (e.g., BGP
 670     configuration should not be locked out if an interface is being
 671     configured or entire Interface configuration should not be locked out
 672     if a non-overlapping parameter on the interface is being configured).
 673
 674 .. req::
 675     :id: R-41829
 676     :target: XNF
 677     :keyword: MUST
 678
 679     The xNF **MUST** be able to specify the granularity of the
 680     lock via a restricted or full XPath expression.
 681
 682 .. req::
 683     :id: R-66793
 684     :target: XNF
 685     :keyword: MUST
 686
 687     The xNF **MUST** guarantee the xNF configuration integrity
 688     for all simultaneous configuration operations (e.g., if a change is
 689     attempted to the BUM filter rate from multiple interfaces on the same
 690     EVC, then they need to be sequenced in the xNF without locking either
 691     configuration method out).
 692
 693 .. req::
 694     :id: R-54190
 695     :target: XNF
 696     :keyword: MUST
 697
 698     The xNF **MUST** release locks to prevent permanent lock-outs
 699     when/if a session applying the lock is terminated (e.g., SSH session
 700     is terminated).
 701
 702 .. req::
 703     :id: R-03465
 704     :target: XNF
 705     :keyword: MUST
 706
 707     The xNF **MUST** release locks to prevent permanent lock-outs
 708     when the corresponding <partial-unlock> operation succeeds.
 709
 710 .. req::
 711     :id: R-63935
 712     :target: XNF
 713     :keyword: MUST
 714
 715     The xNF **MUST** release locks to prevent permanent lock-outs
 716     when a user configured timer has expired forcing the NETCONF SSH Session
 717     termination (i.e., product must expose a configuration knob for a user
 718     setting of a lock expiration timer).
 719
 720 .. req::
 721     :id: R-10173
 722     :target: XNF
 723     :keyword: MUST
 724
 725     The xNF **MUST** allow another NETCONF session to be able to
 726     initiate the release of the lock by killing the session owning the lock,
 727     using the <kill-session> operation to guard against hung NETCONF sessions.
 728
 729 .. req::
 730     :id: R-88899
 731     :target: XNF
 732     :keyword: MUST
 733
 734     The xNF **MUST** support simultaneous <commit> operations
 735     within the context of this locking requirements framework.
 736
 737 .. req::
 738     :id: R-07545
 739     :target: XNF
 740     :keyword: MUST
 741
 742     The xNF **MUST** support all operations, administration and
 743     management (OAM) functions available from the supplier for xNFs using
 744     the supplied YANG code and associated NETCONF servers.
 745
 746 .. req::
 747     :id: R-60656
 748     :target: XNF
 749     :keyword: MUST
 750
 751     The xNF **MUST** support sub tree filtering.
 752
 753 .. req::
 754     :id: R-80898
 755     :target: XNF
 756     :keyword: MUST
 757
 758     TThe xNF **MUST** support heartbeat via a <get> with null filter.
 759
 760 .. req::
 761     :id: R-25238
 762     :target: VNF
 763     :keyword: MUST
 764
 765     The xNF PACKAGE **MUST** validated YANG code using the open
 766     source pyang [#7.3.1]_ program using the following commands:
 767
 768     .. code-block:: text
 769
 770       $ pyang --verbose --strict <YANG-file-name(s)> $ echo $!
 771
 772 .. req::
 773     :id: R-63953
 774     :target: XNF
 775     :keyword: MUST
 776
 777     The xNF **MUST** have the echo command return a zero value
 778     otherwise the validation has failed.
 779
 780 .. req::
 781     :id: R-26508
 782     :target: XNF
 783     :keyword: MUST
 784
 785     The xNF **MUST** support a NETCONF server that can be mounted on
 786     OpenDaylight (client) and perform the operations of: modify, update,
 787     change, rollback configurations using each configuration data element,
 788     query each state (non-configuration) data element, execute each YANG
 789     RPC, and receive data through each notification statement.
 790
 791 The following requirements provides the Yang models that suppliers must
 792 conform, and those where applicable, that suppliers need to use.
 793
 794
 795 .. req::
 796     :id: R-28545
 797     :target: XNF
 798     :keyword: MUST
 799
 800     The xNF **MUST** conform its YANG model to RFC 6060,
 801     "YANG - A Data Modeling Language for the Network Configuration
 802     Protocol (NETCONF)".
 803
 804 .. req::
 805     :id: R-22700
 806     :target: XNF
 807     :keyword: MUST
 808
 809     The xNF **MUST** conform its YANG model to RFC 6470,
 810     "NETCONF Base Notifications".
 811
 812 .. req::
 813     :id: R-10353
 814     :target: XNF
 815     :keyword: MUST
 816
 817     The xNF **MUST** conform its YANG model to RFC 6244,
 818     "An Architecture for Network Management Using NETCONF and YANG".
 819
 820 .. req::
 821     :id: R-53317
 822     :target: XNF
 823     :keyword: MUST
 824
 825     The xNF **MUST** conform its YANG model to RFC 6087,
 826     "Guidelines for Authors and Reviewers of YANG Data Model Documents".
 827
 828 .. req::
 829     :id: R-33955
 830     :target: XNF
 831     :keyword: SHOULD
 832
 833     The xNF **SHOULD** conform its YANG model to RFC 6991,
 834     "Common YANG Data Types".
 835
 836 .. req::
 837     :id: R-22946
 838     :target: XNF
 839     :keyword: SHOULD
 840
 841     The xNF **SHOULD** conform its YANG model to RFC 6536,
 842     "NETCONF Access Control Model".
 843
 844 .. req::
 845     :id: R-10129
 846     :target: XNF
 847     :keyword: SHOULD
 848
 849     The xNF **SHOULD** conform its YANG model to RFC 7223,
 850     "A YANG Data Model for Interface Management".
 851
 852 .. req::
 853     :id: R-12271
 854     :target: XNF
 855     :keyword: SHOULD
 856
 857     The xNF **SHOULD** conform its YANG model to RFC 7223,
 858     "IANA Interface Type YANG Module".
 859
 860 .. req::
 861     :id: R-49036
 862     :target: XNF
 863     :keyword: SHOULD
 864
 865     The xNF **SHOULD** conform its YANG model to RFC 7277,
 866     "A YANG Data Model for IP Management".
 867
 868 .. req::
 869     :id: R-87564
 870     :target: XNF
 871     :keyword: SHOULD
 872
 873     The xNF **SHOULD** conform its YANG model to RFC 7317,
 874     "A YANG Data Model for System Management".
 875
 876 .. req::
 877     :id: R-24269
 878     :target: XNF
 879     :keyword: SHOULD
 880
 881     The xNF **SHOULD** conform its YANG model to RFC 7407,
 882     "A YANG Data Model for SNMP Configuration", if Netconf used to
 883     configure SNMP engine.
 884
 885 The NETCONF server interface shall fully conform to the following
 886 NETCONF RFCs.
 887
 888
 889 .. req::
 890     :id: R-33946
 891     :target: XNF
 892     :keyword: MUST
 893
 894     The xNF **MUST** conform to the NETCONF RFC 4741,
 895     "NETCONF Configuration Protocol".
 896
 897 .. req::
 898     :id: R-04158
 899     :target: XNF
 900     :keyword: MUST
 901
 902     The xNF **MUST** conform to the NETCONF RFC 4742,
 903     "Using the NETCONF Configuration Protocol over Secure Shell (SSH)".
 904
 905 .. req::
 906     :id: R-13800
 907     :target: XNF
 908     :keyword: MUST
 909
 910     The xNF **MUST** conform to the NETCONF RFC 5277,
 911     "NETCONF Event Notification".
 912
 913 .. req::
 914     :id: R-01334
 915     :target: XNF
 916     :keyword: MUST
 917
 918     The xNF **MUST** conform to the NETCONF RFC 5717,
 919     "Partial Lock Remote Procedure Call".
 920
 921 .. req::
 922     :id: R-08134
 923     :target: XNF
 924     :keyword: MUST
 925
 926     The xNF **MUST** conform to the NETCONF RFC 6241,
 927     "NETCONF Configuration Protocol".
 928
 929 .. req::
 930     :id: R-78282
 931     :target: XNF
 932     :keyword: MUST
 933
 934     The xNF **MUST** conform to the NETCONF RFC 6242,
 935     "Using the Network Configuration Protocol over Secure Shell".
 936
 937 VNF REST APIs
 938 ^^^^^^^^^^^^^^^
 939
 940 HealthCheck is a command for which no NETCONF support exists.
 941 Therefore, this must be supported using a RESTful interface
 942 (defined in this section) or with a Chef cookbook/Ansible playbook
 943 (defined in sections `Chef Standards and Capabilities`_ and
 944 `Ansible Standards and Capabilities`_).
 945
 946 HealthCheck Definition: The VNF level HealthCheck is a check over
 947 the entire scope of the VNF. The VNF must be 100% healthy, ready
 948 to take requests and provide services, with all VNF required
 949 capabilities ready to provide services and with all active and
 950 standby resources fully ready with no open MINOR, MAJOR or CRITICAL
 951 alarms.  NOTE: A switch may need to be turned on, but the VNF should
 952 be ready to take service requests or be already processing service
 953 requests successfully.
 954
 955 The VNF must provide a REST formatted GET RPCs to support HealthCheck
 956 queries via the GET method over HTTP(s).
 957
 958 The port number, url, and other authentication information is provided
 959 by the VNF provider.
 960
 961 REST APIs
 962 ~~~~~~~~~
 963
 964
 965 .. req::
 966     :id: R-31809
 967     :target: XNF
 968     :keyword: MUST
 969
 970     The xNF **MUST** support the HealthCheck RPC. The HealthCheck
 971     RPC executes a xNF Provider-defined xNF HealthCheck over the scope of
 972     the entire xNF (e.g., if there are multiple VNFCs, then run a health check,
 973     as appropriate, for all VNFCs). It returns a 200 OK if the test completes.
 974     A JSON object is returned indicating state (healthy, unhealthy), scope
 975     identifier, time-stamp and one or more blocks containing info and fault
 976     information. If the xNF is unable to run the HealthCheck, return a
 977     standard http error code and message.
 978
 979 Examples of responses when HealthCheck runs and is able to provide a healthy
 980 or unhealthy response:
 981
 982 .. code-block:: java
 983
 984  {
 985    "identifier": "scope represented",
 986    "state": "healthy",
 987    "time": "01-01-1000:0000"
 988  }
 989
 990  {
 991    "identifier": "scope represented",
 992    "state": "unhealthy",
 993     {[
 994    "info": "System threshold exceeded details",
 995    "fault":
 996      {
 997        "cpuOverall": 0.80,
 998        "cpuThreshold": 0.45
 999      }
1000      ]},
1001    "time": "01-01-1000:0000"
1002  }
1003
1004
1005 Chef Standards and Capabilities
1006 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1007
1008 ONAP will support configuration of VNFs via Chef subject to the
1009 requirements and guidelines defined in this section.
1010
1011 The Chef configuration management mechanism follows a client-server
1012 model. It requires the presence of a Chef-Client on the VNF that will be
1013 directly managed by a Chef Server. The Chef-client will register with
1014 the appropriate Chef Server and are managed via 'cookbooks' and
1015 configuration attributes loaded on the Chef Server which contain all
1016 necessary information to execute the appropriate actions on the VNF via
1017 the Chef-client.
1018
1019 ONAP will utilize the open source Chef Server, invoke the documented
1020 Chef REST APIs to manage the VNF and requires the use of open source
1021 Chef-Client and Push Jobs Client on the VNF
1022 (https://downloads.chef.io/).
1023
1024 VNF Configuration via Chef Requirements
1025 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1026
1027 Chef Client Requirements
1028 +++++++++++++++++++++++++
1029
1030
1031 .. req::
1032     :id: R-79224
1033     :target: XNF
1034     :keyword: MUST
1035
1036     The xNF **MUST** have the chef-client be preloaded with
1037     validator keys and configuration to register with the designated
1038     Chef Server as part of the installation process.
1039
1040 .. req::
1041     :id: R-72184
1042     :target: XNF
1043     :keyword: MUST
1044
1045     The xNF **MUST** have routable FQDNs for all the endpoints
1046     (VMs) of a xNF that contain chef-clients which are used to register
1047     with the Chef Server.  As part of invoking xNF actions, ONAP will
1048     trigger push jobs against FQDNs of endpoints for a xNF, if required.
1049
1050 .. req::
1051     :id: R-47068
1052     :target: XNF
1053     :keyword: MAY
1054
1055     The xNF **MAY** expose a single endpoint that is
1056     responsible for all functionality.
1057
1058 .. req::
1059     :id: R-67114
1060     :target: VNF
1061     :keyword: MUST
1062
1063     The xNF **MUST** be installed with Chef-Client >= 12.0 and Chef
1064     push jobs client >= 2.0.
1065
1066 Chef Roles/Requirements
1067 ++++++++++++++++++++++++++
1068
1069
1070 .. req::
1071     :id: R-27310
1072     :target: XNF
1073     :keyword: MUST
1074
1075     The xNF Package **MUST** include all relevant Chef artifacts
1076     (roles/cookbooks/recipes) required to execute xNF actions requested by
1077     ONAP for loading on appropriate Chef Server.
1078
1079 .. req::
1080     :id: R-26567
1081     :target: XNF
1082     :keyword: MUST
1083
1084     The xNF Package **MUST** include a run list of
1085     roles/cookbooks/recipes, for each supported xNF action, that will
1086     perform the desired xNF action in its entirety as specified by ONAP
1087     (see Section 7.c, ONAP Controller APIs and Behavior, for list of xNF
1088     actions and requirements), when triggered by a chef-client run list
1089     in JSON file.
1090
1091 .. req::
1092     :id: R-98911
1093     :target: XNF
1094     :keyword: MUST NOT
1095
1096     The xNF **MUST NOT** use any instance specific parameters
1097     for the xNF in roles/cookbooks/recipes invoked for a xNF action.
1098
1099 .. req::
1100     :id: R-37929
1101     :target: XNF
1102     :keyword: MUST
1103
1104     The xNF **MUST** accept all necessary instance specific
1105     data from the environment or node object attributes for the xNF
1106     in roles/cookbooks/recipes invoked for a xNF action.
1107
1108 .. req::
1109     :id: R-62170
1110     :target: XNF
1111     :keyword: MUST
1112
1113     The xNF **MUST** over-ride any default values for
1114     configurable parameters that can be set by ONAP in the roles,
1115     cookbooks and recipes.
1116
1117 .. req::
1118     :id: R-78116
1119     :target: XNF
1120     :keyword: MUST
1121
1122     The xNF **MUST** update status on the Chef Server
1123     appropriately (e.g., via a fail or raise an exception) if the
1124     chef-client run encounters any critical errors/failures when
1125     executing a xNF action.
1126
1127 .. req::
1128     :id: R-44013
1129     :target: XNF
1130     :keyword: MUST
1131
1132     The xNF **MUST** populate an attribute, defined as node
1133     ['PushJobOutput'] with the desired output on all nodes in the push job
1134     that execute chef-client run if the xNF action requires the output of a
1135     chef-client run be made available (e.g., get running configuration).
1136
1137 .. req::
1138     :id: R-30654
1139     :target: XNF
1140     :keyword: MUST
1141
1142     The xNF Package **MUST** have appropriate cookbooks that are
1143     designed to automatically 'rollback' to the original state in case of
1144     any errors for actions that change state of the xNF (e.g., configure).
1145
1146 .. req::
1147     :id: R-65755
1148     :target: XNF
1149     :keyword: SHOULD
1150
1151     The xNF **SHOULD** support callback URLs to return information
1152     to ONAP upon completion of the chef-client run for any chef-client run
1153     associated with a xNF action.
1154
1155     -  As part of the push job, ONAP will provide two parameters in the
1156        environment of the push job JSON object:
1157
1158         -  "RequestId" a unique Id to be used to identify the request,
1159         -  "CallbackUrl", the URL to post response back.
1160
1161     -  If the CallbackUrl field is empty or missing in the push job, then
1162        the chef-client run need not post the results back via callback.
1163
1164 .. req::
1165     :id: R-15885
1166     :target: XNF
1167     :keyword: MUST
1168
1169     The xNF **MUST** Upon completion of the chef-client run,
1170     POST back on the callback URL, a JSON object as described in Table
1171     A2 if the chef-client run list includes a cookbook/recipe that is
1172     callback capable. Failure to POST on the Callback Url should not be
1173     considered a critical error. That is, if the chef-client successfully
1174     completes the xNF action, it should reflect this status on the Chef
1175     Server regardless of whether the Callback succeeded or not.
1176
1177 ONAP Chef API Usage
1178 ~~~~~~~~~~~~~~~~~~~
1179
1180 This section outlines the workflow that ONAP invokes when it receives an
1181 action request against a Chef managed VNF.
1182
1183 1. When ONAP receives a request for an action for a Chef Managed VNF, it
1184    retrieves the corresponding template (based on **action** and
1185    **VNF)** from its database and sets necessary values in the
1186    "Environment", "Node" and "NodeList" keys (if present) from either
1187    the payload of the received action or internal data.
1188
1189 2. If "Environment" key is present in the updated template, it posts the
1190    corresponding JSON dictionary to the appropriate Environment object
1191    REST endpoint on the Chef Server thus updating the Environment
1192    attributes on the Chef Server.
1193
1194 3. Next, it creates a Node Object from the "Node" JSON dictionary for
1195    all elements listed in the NodeList (using the FQDN to construct the
1196    endpoint) by replicating it  [#7.3.2]_. As part of this process, it will
1197    set the name field in each Node Object to the corresponding FQDN.
1198    These node objects are then posted on the Chef Server to
1199    corresponding Node Object REST endpoints to update the corresponding
1200    node attributes.
1201
1202 4. If PushJobFlag is set to "True" in the template, ONAP requests a push
1203    job against all the nodes in the NodeList to trigger
1204    chef-client\ **.** It will not invoke any other command via the push
1205    job. ONAP will include a callback URL in the push job request and a
1206    unique Request Id. An example push job posted by ONAP is listed
1207    below:
1208
1209 .. code-block:: java
1210
1211   {
1212    "command": "chef-client"
1213    "run\_timeout": 300
1214    "nodes": ["node1.vnf\_a.onap.com", "node2.vnf\_a.onap.com"]
1215      "env": {
1216               "RequestId":"8279-abcd-aksdj-19231"
1217               "CallbackUrl":"<callback>"
1218             }
1219   }
1220
1221
1222 5. If CallbackCapable field in the template is not present or set to
1223    "False" ONAP will poll the Chef Server to check completion status of
1224    the push job.
1225
1226 6. If "GetOutputFlag" is set to "True" in the template and
1227    CallbackCapable is not set to "True", ONAP will retrieve any output
1228    from each node where the push job has finished by accessing the Node
1229    Object attribute node['PushJobOutput'].
1230
1231 Ansible Standards and Capabilities
1232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1233
1234 ONAP will support configuration of VNFs via Ansible subject to the
1235 requirements and guidelines defined in this section.
1236
1237 Ansible allows agentless management of VNFs/VMs/VNFCs via execution
1238 of 'playbooks' over ssh. The 'playbooks' are a structured set of
1239 tasks which contain all the necessary resources and execution capabilities
1240 to take the necessary action on one or more target VMs (and/or VNFCs)
1241 of the VNF. ONAP will utilize the framework of an Ansible Server that
1242 will host all Ansible artifacts and run playbooks to manage VNFs that support
1243 Ansible.
1244
1245 VNF Configuration via Ansible Requirements
1246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1247
1248 Ansible Client Requirements
1249 +++++++++++++++++++++++++++++
1250
1251
1252 .. req::
1253     :id: R-32217
1254     :target: XNF
1255     :keyword: MUST
1256
1257     The xNF **MUST** have routable FQDNs that are reachable via
1258     the Ansible Server for the endpoints (VMs) of a xNF on which playbooks
1259     will be executed. ONAP will initiate requests to the Ansible Server
1260     for invocation of playbooks against these end points [#7.3.3]_.
1261
1262 .. req::
1263     :id: R-54373
1264     :target: XNF
1265     :keyword: MUST
1266
1267     The xNF **MUST** have Python >= 2.6 on the endpoint VM(s)
1268     of a xNF on which an Ansible playbook will be executed.
1269
1270 .. req::
1271     :id: R-35401
1272     :target: XNF
1273     :keyword: MUST
1274
1275     The xNF **MUST** support SSH and allow SSH access by the
1276     Ansible server for the endpoint VM(s) and comply with the Network
1277     Cloud Service Provider guidelines for authentication and access.
1278
1279 .. req::
1280     :id: R-82018
1281     :target: XNF
1282     :keyword: MUST
1283
1284     The xNF **MUST** load the Ansible Server SSH public key onto xNF
1285     VM(s) as part of instantiation. This will allow the Ansible Server
1286     to authenticate to perform post-instantiation configuration without
1287     manual intervention and without requiring specific xNF login IDs and
1288     passwords.
1289
1290     CAUTION: For VNFs configured using Ansible, to eliminate the need
1291     for manual steps, post-instantiation and pre-configuration, to
1292     upload of SSH public keys, SSH public keys loaded during (heat)
1293     instantiation shall be preserved and not removed by (heat) embedded
1294     (userdata) scripts.
1295
1296 .. req::
1297     :id: R-92866
1298     :target: XNF
1299     :keyword: MUST
1300
1301     The xNF **MUST** include as part of post-instantiation configuration
1302     done by Ansible Playbooks the removal/update of the SSH public key from
1303     /root/.ssh/authorized_keys, and  update of SSH keys loaded through
1304     instantiation to support Ansible. This may include download and install of
1305     new SSH keys and new mechanized IDs.
1306
1307 .. req::
1308     :id: R-91745
1309     :target: XNF
1310     :keyword: MUST
1311
1312     The xNF **MUST** update the Ansible Server and other entities
1313     storing and using the SSH keys for authentication when the SSH
1314     keys used by Ansible are regenerated/updated.
1315
1316     Note: Ansible Server itself may be used to upload new SSH public
1317     keys onto supported VNFs.
1318
1319 Ansible Playbook Requirements
1320 +++++++++++++++++++++++++++++++
1321
1322 An Ansible playbook is a collection of tasks that is executed on the
1323 Ansible server (local host) and/or the target VM (s) in order to
1324 complete the desired action.
1325
1326
1327 .. req::
1328     :id: R-40293
1329     :target: XNF
1330     :keyword: MUST
1331
1332     The xNF **MUST** make available playbooks that conform
1333     to the ONAP requirement.
1334
1335 .. req::
1336     :id: R-49396
1337     :target: XNF
1338     :keyword: MUST
1339
1340     The xNF **MUST** support each ONAP (APPC) xNF action
1341     by invocation of **one** playbook [#7.3.4]_. The playbook will be responsible
1342     for executing all necessary tasks (as well as calling other playbooks)
1343     to complete the request.
1344
1345 .. req::
1346     :id: R-33280
1347     :target: XNF
1348     :keyword: MUST NOT
1349
1350     The xNF **MUST NOT** use any instance specific parameters
1351     in a playbook.
1352
1353 .. req::
1354     :id: R-48698
1355     :target: XNF
1356     :keyword: MUST
1357
1358     The xNF **MUST** utilize information from key value pairs
1359     that will be provided by the Ansible Server as "extra-vars" during
1360     invocation to execute the desired xNF action. If the playbook requires
1361     files, they must also be supplied using the methodology detailed in
1362     the Ansible Server API, unless they are bundled with playbooks, example,
1363     generic templates.
1364
1365 The Ansible Server will determine if a playbook invoked to execute a
1366 xNF action finished successfully or not using the "PLAY_RECAP" summary
1367 in Ansible log.  The playbook will be considered to successfully finish
1368 only if the "PLAY RECAP" section at the end of playbook execution output
1369 has no unreachable hosts and no failed tasks. Otherwise, the playbook
1370 will be considered to have failed.
1371
1372
1373 .. req::
1374     :id: R-43253
1375     :target: XNF
1376     :keyword: MUST
1377
1378     The xNF **MUST** use playbooks designed to allow Ansible
1379     Server to infer failure or success based on the "PLAY_RECAP" capability.
1380
1381     Note: There are cases where playbooks need to interpret results
1382     of a task and then determine success or failure and return result
1383     accordingly (failure for failed tasks).
1384
1385 .. req::
1386     :id: R-50252
1387     :target: XNF
1388     :keyword: MUST
1389
1390     The xNF **MUST** write to a specific one text files that
1391     will be retrieved and made available by the Ansible Server if, as part
1392     of a xNF action (e.g., audit), a playbook is required to return any
1393     xNF information. The text files must be written in the same directory as
1394     the one from which the playbook is being executed. A text file must be
1395     created for the xNF playbook run targets/affects, with the name
1396     '<VNFname>_results.txt' into which any desired output from each
1397     respective VM/xNF must be written.
1398
1399 .. req::
1400     :id: R-51442
1401     :target: XNF
1402     :keyword: SHOULD
1403
1404     The xNF **SHOULD** use playbooks that are designed to
1405     automatically 'rollback' to the original state in case of any errors
1406     for actions that change state of the xNF (e.g., configure).
1407
1408         Note: In case rollback at the playbook level is not supported or
1409         possible, the xNF provider shall provide alternative locking
1410         mechanism (e.g., for a small xNF the rollback mechanism may rely
1411         on workflow to terminate and re-instantiate VNF VMs and then re-run
1412         playbook(s)). Backing up updated files also recommended to support
1413         rollback when soft rollback is feasible.
1414
1415 .. req::
1416     :id: R-58301
1417     :target: XNF
1418     :keyword: SHOULD NOT
1419
1420     The xNF **SHOULD NOT** use playbooks that make requests to
1421     Cloud resources e.g. Openstack (nova, neutron, glance, heat, etc.);
1422     therefore, there is no use for Cloud specific variables like Openstack
1423     UUIDs in Ansible Playbooks.
1424
1425     Rationale: Flows that require interactions with Cloud services e.g.
1426     Openstack shall rely on workflows run by an Orchestrator
1427     (Change Management) or other capability (such as a control loop or
1428     Operations GUI) outside Ansible Server which can be executed by a
1429     Controller such as APPC. There are policies, as part of Control Loop
1430     models, that send remediation action requests to APPC; these are
1431     triggered as a response to an event or correlated events published
1432     to Event Bus.
1433
1434 .. req::
1435     :id: R-02651
1436     :target: XNF
1437     :keyword: SHOULD
1438
1439     The xNF **SHOULD** use the Ansible backup feature to save a
1440     copy of configuration files before implementing changes to support
1441     operations such as backing out of software upgrades, configuration
1442     changes or other work as this will help backing out of configuration
1443     changes when needed.
1444
1445 .. req::
1446     :id: R-43353
1447     :target: XNF
1448     :keyword: MUST
1449
1450     The xNF **MUST** return control from Ansible Playbooks only
1451     after tasks are fully complete, signaling that the playbook completed
1452     all tasks. When starting services, return control only after all services
1453     are up. This is critical for workflows where the next steps are dependent
1454     on prior tasks being fully completed.
1455
1456 Detailed examples:
1457
1458 StopApplication Playbook – StopApplication Playbook shall return control
1459 and a completion status only after VNF application is fully stopped, all
1460 processes/services stopped.
1461 StartApplication Playbook – StartApplication Playbook shall return control
1462 and a completion status only after all VNF application services are fully up,
1463 all processes/services started and ready to provide services. NOTE: Start
1464 Playbook should not be declared complete/done after starting one or several
1465 processes that start the other processes.
1466
1467 HealthCheck Playbook:
1468
1469 SUCCESS – HealthCheck success shall be returned (return code 0) by a
1470 Playbook or Cookbook only when VNF is 100% healthy, ready to take requests
1471 and provide services, with all VNF required capabilities ready to provide
1472 services and with all active and standby resources fully ready with no
1473 open MINOR, MAJOR or CRITICAL alarms.
1474
1475 NOTE: In some cases, a switch may need to be turned on, but a VNF
1476 reported as healthy, should be ready to take service requests or be
1477 already processing service requests successfully.
1478
1479 A successful execution of a health-check playbook shall also create one
1480 file per VNF VM, named after the VNF instance name followed by
1481 "_results.txt (<vnf_instance>_results.txt) to indicate health-check was
1482 executed and completed successfully, example: vfdb9904v_results.txt,
1483 with the following contents:
1484
1485 .. code-block:: java
1486
1487   {
1488    "identifier": "VNF",
1489    "state": "healthy",
1490    "time": "2018-03-16:1139"
1491   }
1492
1493 Example:
1494
1495 .. code-block:: java
1496
1497   $ cat vfdb9904v_results.txt
1498   {
1499    "identifier": "VNF",
1500    "state": "healthy",
1501    "time": "2018-03-16:1139"
1502   }
1503 ..
1504
1505 FAILURE – A health check playbook shall return a non-zero return code in
1506 case VNF is not 100% healthy because one or more VNF application processes
1507 are stopped or not ready to take service requests or because critical or
1508 non-critical resources are not ready or because there are open MINOR, MAJOR
1509 or CRITICAL traps/alarms or because there are issues with the VNF that
1510 need attention even if they do not impact services provided by the VNF.
1511
1512 A failed health-check playbook shall also create one file per VNF,
1513 named after the VNF instance name, followed by
1514 "_results.txt to indicate health-check was executed and found issues
1515 in the health of the VNF. This is to differentiate from failure to
1516 run health-check playbook or playbook tasks to verify the health of the VNF,
1517 example: vfdb9904v_results.txt, with the following contents:
1518
1519 .. code-block:: java
1520
1521  {
1522   "identifier": "VNF",
1523   "state": "unhealthy",
1524   "info": "Error in following VM(s). Check hcstatus files
1525   under /tmp/ccfx9901v for details",
1526   "fault": [
1527     "vfdb9904vm001",
1528     "vfdb9904vm002"
1529   ],
1530   "time": "2018-03-16:4044"
1531  }
1532 ..
1533
1534 Example:
1535
1536 .. code-block:: java
1537
1538  $ cat vfdb9904v_results.txt
1539  {
1540   "identifier": "VNF",
1541   "state": "unhealthy",
1542   "info": "Error in following VM(s). Check hcstatus files
1543   under /tmp/ccfx9901v for details",
1544   "fault": [
1545     "vfdb9904vm001",
1546     "vfdb9904vm002"
1547   ],
1548   "time": "2018-03-16:4044"
1549  }
1550 ..
1551
1552 See `VNF REST APIs`_ for additional details on HealthCheck.
1553
1554
1555
1556 ONAP Controller / Ansible API Usage
1557 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1558
1559 This section outlines the workflow that ONAP Controller invokes when
1560 it receives an action request against an Ansible managed VNF.
1561
1562  #. When ONAP Controller receives a request for an action for an
1563     AnsibleManaged VNF, it retrieves the corresponding template (based
1564     on **action** and **VNF**) from its database and sets necessary
1565     values (such as an Id, NodeList, and EnvParameters) from either
1566     information in the request or data obtained from other sources.
1567     This is referred to as the payload that is sent as a JSON object
1568     to the Ansible server.
1569  #. The ONAP Controller sends a request to the Ansible server to
1570     execute the action.
1571  #. The ONAP Controller polls the Ansible Server for result (success
1572     or failure).  The ONAP Controllers has a timeout value which is
1573     contained in the template.   If the result is not available when the
1574     timeout is reached, the ONAP Controller stops polling and returns a
1575     timeout error to the requester.   The Ansible Server continues to
1576     process the request.
1577
1578
1579 Support of Controller Commands And Southbound Protocols
1580 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1581
1582 The following table summarizes the commands and possible protocols selected.
1583 Note that the HealthCheck can also be supported via REST.
1584
1585 Table 8. ONAP Controller APIs and NETCONF Commands
1586
1587 +-------------+--------------------+--------------------+--------------------+
1588 |**Command**  |**NETCONF Support** |**Chef Support**    |**Ansible**         |
1589 +=============+====================+====================+====================+
1590 |General      |For each RPC, the   |VNF Vendor must     |VNF Vendor must     |
1591 |Comments     |appropriate RPC     |provide any         |provide an Ansible  |
1592 |             |operation is listed.|necessary roles,    |playbook to retrieve|
1593 |             |                    |cookbooks, recipes  |the running         |
1594 |             |                    |to retrieve the     |configuration from a|
1595 |             |                    |running             |VNF and place the   |
1596 |             |                    |configuration from  |output on the       |
1597 |             |                    |a VNF and place it  |Ansible server in   |
1598 |             |                    |in the respective   |a manner aligned    |
1599 |             |                    |Node Objects        |with playbook       |
1600 |             |                    |'PushJobOutput'     |requirements listed |
1601 |             |                    |attribute of all    |in this document.   |
1602 |             |                    |nodes in NodeList   |                    |
1603 |             |                    |when triggered      |The PlaybookName    |
1604 |             |                    |by a chef-client    |must be provided    |
1605 |             |                    |run.                |in the JSON file.   |
1606 |             |                    |                    |                    |
1607 |             |                    |The JSON file for   |NodeList must list  |
1608 |             |                    |this VNF action is  |IP addresses or DNS |
1609 |             |                    |required to set     |supported FQDNs of  |
1610 |             |                    |"PushJobFlag" to    |an example VNF      |
1611 |             |                    |"True" and          |on which to         |
1612 |             |                    |"GetOutputFlag" to  |execute playbook.   |
1613 |             |                    |"True". The "Node"  |                    |
1614 |             |                    |JSON dictionary     |                    |
1615 |             |                    |must have the run   |                    |
1616 |             |                    |list populated      |                    |
1617 |             |                    |with the necessary  |                    |
1618 |             |                    |sequence of roles,  |                    |
1619 |             |                    |cookbooks, recipes. |                    |
1620 |             |                    |                    |                    |
1621 |             |                    |The Environment     |                    |
1622 |             |                    |and Node values     |                    |
1623 |             |                    |should contain all  |                    |
1624 |             |                    |appropriate         |                    |
1625 |             |                    |configuration       |                    |
1626 |             |                    |attributes.         |                    |
1627 |             |                    |                    |                    |
1628 |             |                    |NodeList must       |                    |
1629 |             |                    |list sample FQDNs   |                    |
1630 |             |                    |that are required to|                    |
1631 |             |                    |conduct a           |                    |
1632 |             |                    |chef-client run for |                    |
1633 |             |                    |this VNF Action.    |                    |
1634 +-------------+--------------------+--------------------+--------------------+
1635 |Audit        |The <get-config> is |Supported via a     |Supported via a     |
1636 |             |used to return the  |cookbook that       |playbook that       |
1637 |             |running             |returns the running |returns the running |
1638 |             |configuration.      |configuration.      |configuration.      |
1639 +-------------+--------------------+--------------------+--------------------+
1640 |Configure,   |The <edit-config>   |Supported via a     |Supported via a     |
1641 |ModifyConfig |operation loads all |cookbook that       |playbook that       |
1642 |             |or part of a        |updates the VNF     |updates the VNF     |
1643 |             |specified data set  |configuration.      |configuration.      |
1644 |             |to the specified    |                    |                    |
1645 |             |target database. If |                    |                    |
1646 |             |there is no         |                    |                    |
1647 |             |<candidate/>        |                    |                    |
1648 |             |database, then the  |                    |                    |
1649 |             |target is the       |                    |                    |
1650 |             |<running/> database.|                    |                    |
1651 |             |A <commit> follows. |                    |                    |
1652 +-------------+--------------------+--------------------+--------------------+
1653 |Other        |This command has no |Supported via a     |Supported via a     |
1654 |Configuration|existing NETCONF RPC|cookbook that       |playbook that       |
1655 |Commands     |action.             |performs            |performs            |
1656 |             |                    |the action.         |the action.         |
1657 +-------------+--------------------+--------------------+--------------------+
1658 |Lifecycle    |This command has no |Supported via a     |Supported via a     |
1659 |Management   |existing NETCONF RPC|cookbook that       |playbook that       |
1660 |Commands     |action.             |performs            |performs            |
1661 |             |                    |the action.         |the action.         |
1662 +-------------+--------------------+--------------------+--------------------+
1663 |Health Check |This command has no |Supported via a     |Supported           |
1664 |             |existing NETCONF RPC|cookbook            |via a               |
1665 |             |action.             |that                |playbook            |
1666 |             |                    |performs            |that                |
1667 |             |                    |a HealthCheck and   |performs            |
1668 |             |                    |returns the results.|the                 |
1669 |             |                    |                    |HealthCheck         |
1670 |             |                    |                    |and returns         |
1671 |             |                    |                    |the                 |
1672 |             |                    |                    |results.            |
1673 +-------------+--------------------+--------------------+--------------------+
1674
1675 .. [#7.3.1]
1676    https://github.com/mbj4668/pyang
1677
1678 .. [#7.3.2]
1679    Recall that the Node Object **is required** to be identical across
1680    all VMs of a VNF invoked as part of the action except for the "name".
1681
1682 .. [#7.3.3]
1683    Upstream elements must provide the appropriate FQDN in the request to
1684    ONAP for the desired action.
1685
1686 .. [#7.3.4]
1687    Multiple ONAP actions may map to one playbook.
1688
1689