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