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
 424     :keyword: MUST
 425     :updated: frankfurt
 426
 427     The VNF **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 LCM Operations via NETCONF
1037 ++++++++++++++++++++++++++++++
1038
1039 .. req::
1040     :id: R-246519
1041     :target: VNF or PNF
1042     :keyword: MAY
1043     :introduced: frankfurt
1044
1045     As alternative to Ansible, Chef or REST, a VNF or PNF MAY support YANG models
1046     allowing execution of standard controller LCM operations including HealthCheck.
1047     Note: To support vendor YANG models for LCM operations, the controller is responsible
1048     for performing VNF/PNF specific translation of north-bound API requests into one or more
1049     south-bound NETCONF requests.
1050
1051 .. _xnf_rest_apis:
1052
1053 VNF or PNF REST APIs
1054 ^^^^^^^^^^^^^^^^^^^^
1055
1056 HealthCheck command must be supported using a RESTful interface
1057 (defined in this section) or with NETCONF/YANG (defined in section
1058 `NETCONF Standards and Capabilities`_) or with a Chef cookbook/Ansible playbook
1059 (defined in sections `Chef Standards and Capabilities`_ and
1060 `Ansible Standards and Capabilities`_).
1061
1062 See section 7.3.1.4 for the definition of Full Healthcheck and Partial
1063 Healthchecks.
1064
1065 The VNF or PNF must provide a REST formatted GET RPCs to support HealthCheck
1066 queries via the GET method over HTTP(s).
1067
1068 The port number, url, and other authentication information is provided
1069 by the VNF or PNF provider.
1070
1071 REST APIs
1072 ~~~~~~~~~
1073
1074 .. req::
1075     :id: R-31809
1076     :target: VNF or PNF
1077     :keyword: MUST
1078     :updated: dublin
1079
1080     The VNF or PNF **MUST** support the HealthCheck RPC. The HealthCheck
1081     RPC executes a VNF or PNF Provider-defined VNF or PNF HealthCheck over the
1082     scope of the entire VNF or PNF (e.g., if there are multiple VNFCs, then
1083     run a health check, as appropriate, for all VNFCs). It returns a 200 OK if
1084     the test completes. A JSON object is returned indicating state (healthy,
1085     unhealthy), scope identifier, time-stamp and one or more blocks containing
1086     info and fault information. If the VNF or PNF is unable to run the
1087     HealthCheck, return a standard http error code and message.
1088
1089 Examples of responses when HealthCheck runs and is able to provide a healthy
1090 or unhealthy response:
1091
1092 .. code-block:: java
1093
1094   {
1095     "identifier":"VNF",
1096     "state":"healthy",
1097     "time":"2018-11-28 22:39:00.809466"
1098   },
1099
1100   {
1101     "identifier":"VNF",
1102     "state":"unhealthy",
1103     "info":"There are stopped processes or VNF is not ready, may be quiesced or frozen.",
1104     "fault":"VNF mtn23comx8000v not ready for service.",
1105     "time":"2018-11-30 05:47:48.655959"
1106   }
1107
1108
1109 Chef Standards and Capabilities
1110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1111
1112 .. container:: note
1113
1114     **ATTENTION**: Chef is supported by ONAP, but it is not currently used by
1115     any of the official ONAP use cases and is not part of standard release
1116     testing like REST, Ansible, and Netconf.  For this reason, the other
1117     options are generally favored over Chef at this time.
1118
1119
1120 ONAP will support configuration of VNFs or PNFs via Chef subject to the
1121 requirements and guidelines defined in this section.
1122
1123 The Chef configuration management mechanism follows a client-server
1124 model. It requires the presence of a Chef-Client on the VNF or PNF that will be
1125 directly managed by a Chef Server. The Chef-client will register with
1126 the appropriate Chef Server and are managed via 'cookbooks' and
1127 configuration attributes loaded on the Chef Server which contain all
1128 necessary information to execute the appropriate actions on the VNF or PNF via
1129 the Chef-client.
1130
1131 ONAP will utilize the open source Chef Server, invoke the documented
1132 Chef REST APIs to manage the VNF or PNF and requires the use of open source
1133 Chef-Client and Push Jobs Client on the VNF or PNF
1134 (https://downloads.chef.io/).
1135
1136 VNF or PNF Configuration via Chef Requirements
1137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1138
1139 Chef Client Requirements
1140 +++++++++++++++++++++++++
1141
1142
1143 .. req::
1144     :id: R-79224
1145     :target: VNF or PNF
1146     :keyword: MUST
1147     :updated: dublin
1148
1149     The VNF or PNF **MUST** have the chef-client be preloaded with
1150     validator keys and configuration to register with the designated
1151     Chef Server as part of the installation process.
1152
1153 .. req::
1154     :id: R-72184
1155     :target: VNF or PNF
1156     :keyword: MUST
1157     :updated: dublin
1158
1159     The VNF or PNF **MUST** have routable FQDNs for all the endpoints
1160     (VMs) of a VNF or PNF that contain chef-clients which are used to register
1161     with the Chef Server.  As part of invoking VNF or PNF actions, ONAP will
1162     trigger push jobs against FQDNs of endpoints for a VNF or PNF, if required.
1163
1164 .. req::
1165     :id: R-47068
1166     :target: VNF or PNF
1167     :keyword: MAY
1168     :updated: dublin
1169
1170     The VNF or PNF **MAY** expose a single endpoint that is
1171     responsible for all functionality.
1172
1173 .. req::
1174     :id: R-67114
1175     :target: VNF
1176     :keyword: MUST
1177     :updated: dublin
1178
1179     The VNF or PNF **MUST** be installed with Chef-Client >= 12.0 and Chef
1180     push jobs client >= 2.0.
1181
1182 Chef Roles/Requirements
1183 ++++++++++++++++++++++++++
1184
1185 .. req::
1186     :id: R-27310
1187     :target: VNF or PNF
1188     :keyword: MUST
1189     :updated: dublin
1190
1191     The VNF or PNF Package **MUST** include all relevant Chef artifacts
1192     (roles/cookbooks/recipes) required to execute VNF or PNF actions requested
1193     by ONAP for loading on appropriate Chef Server.
1194
1195 .. req::
1196     :id: R-26567
1197     :target: VNF or PNF
1198     :keyword: MUST
1199     :updated: dublin
1200
1201     The VNF or PNF Package **MUST** include a run list of
1202     roles/cookbooks/recipes, for each supported VNF or PNF action, that will
1203     perform the desired VNF or PNF action in its entirety as specified by ONAP
1204     (see Section 7.c, APPC/SDN-C APIs and Behavior, for list of VNF or PNF
1205     actions and requirements), when triggered by a chef-client run list
1206     in JSON file.
1207
1208 .. req::
1209     :id: R-98911
1210     :target: VNF or PNF
1211     :keyword: MUST NOT
1212     :updated: dublin
1213
1214     The VNF or PNF **MUST NOT** use any instance specific parameters
1215     for the VNF or PNF in roles/cookbooks/recipes invoked for a VNF or PNF
1216     action.
1217
1218 .. req::
1219     :id: R-37929
1220     :target: VNF or PNF
1221     :keyword: MUST
1222     :updated: dublin
1223
1224     The VNF or PNF **MUST** accept all necessary instance specific
1225     data from the environment or node object attributes for the VNF or PNF
1226     in roles/cookbooks/recipes invoked for a VNF or PNF action.
1227
1228 .. req::
1229     :id: R-62170
1230     :target: VNF or PNF
1231     :keyword: MUST
1232     :updated: dublin
1233
1234     The VNF or PNF **MUST** over-ride any default values for
1235     configurable parameters that can be set by ONAP in the roles,
1236     cookbooks and recipes.
1237
1238 .. req::
1239     :id: R-78116
1240     :target: VNF or PNF
1241     :keyword: MUST
1242     :updated: dublin
1243
1244     The VNF or PNF **MUST** update status on the Chef Server
1245     appropriately (e.g., via a fail or raise an exception) if the
1246     chef-client run encounters any critical errors/failures when
1247     executing a VNF or PNF action.
1248
1249 .. req::
1250     :id: R-44013
1251     :target: VNF or PNF
1252     :keyword: MUST
1253     :updated: dublin
1254
1255     The VNF or PNF **MUST** populate an attribute, defined as node
1256     ['PushJobOutput'] with the desired output on all nodes in the push job
1257     that execute chef-client run if the VNF or PNF action requires the output
1258     of a chef-client run be made available (e.g., get running configuration).
1259
1260 .. req::
1261     :id: R-30654
1262     :target: VNF or PNF
1263     :keyword: MUST
1264     :updated: dublin
1265
1266     The VNF or PNF Package **MUST** have appropriate cookbooks that are
1267     designed to automatically 'rollback' to the original state in case of
1268     any errors for actions that change state of the VNF or PNF (e.g.,
1269     configure).
1270
1271 .. req::
1272     :id: R-65755
1273     :target: VNF or PNF
1274     :keyword: SHOULD
1275     :updated: dublin
1276
1277     The VNF or PNF **SHOULD** support callback URLs to return information
1278     to ONAP upon completion of the chef-client run for any chef-client run
1279     associated with a VNF or PNF action.
1280
1281     -  As part of the push job, ONAP will provide two parameters in the
1282        environment of the push job JSON object:
1283
1284         -  "RequestId" a unique Id to be used to identify the request,
1285         -  "CallbackUrl", the URL to post response back.
1286
1287     -  If the CallbackUrl field is empty or missing in the push job, then
1288        the chef-client run need not post the results back via callback.
1289
1290 .. req::
1291     :id: R-15885
1292     :target: VNF or PNF
1293     :keyword: MUST
1294     :updated: dublin
1295
1296     The VNF or PNF **MUST** Upon completion of the chef-client run,
1297     POST back on the callback URL, a JSON object as described in Table
1298     A2 if the chef-client run list includes a cookbook/recipe that is
1299     callback capable. Failure to POST on the Callback Url should not be
1300     considered a critical error. That is, if the chef-client successfully
1301     completes the VNF or PNF action, it should reflect this status on the Chef
1302     Server regardless of whether the Callback succeeded or not.
1303
1304 ONAP Chef API Usage
1305 ~~~~~~~~~~~~~~~~~~~
1306
1307 This section outlines the workflow that ONAP invokes when it receives an
1308 action request against a Chef managed VNF or PNF.
1309
1310 1. When ONAP receives a request for an action for a Chef Managed VNF or PNF, it
1311    retrieves the corresponding template (based on **action** and
1312    **VNF or PNF**) from its database and sets necessary values in the
1313    "Environment", "Node" and "NodeList" keys (if present) from either
1314    the payload of the received action or internal data.
1315
1316 2. If "Environment" key is present in the updated template, it posts the
1317    corresponding JSON dictionary to the appropriate Environment object
1318    REST endpoint on the Chef Server thus updating the Environment
1319    attributes on the Chef Server.
1320
1321 3. Next, it creates a Node Object from the "Node" JSON dictionary for
1322    all elements listed in the NodeList (using the FQDN to construct the
1323    endpoint) by replicating it  [#7.3.2]_. As part of this process, it will
1324    set the name field in each Node Object to the corresponding FQDN.
1325    These node objects are then posted on the Chef Server to
1326    corresponding Node Object REST endpoints to update the corresponding
1327    node attributes.
1328
1329 4. If PushJobFlag is set to "True" in the template, ONAP requests a push
1330    job against all the nodes in the NodeList to trigger
1331    chef-client. It will not invoke any other command via the push
1332    job. ONAP will include a callback URL in the push job request and a
1333    unique Request Id. An example push job posted by ONAP is listed
1334    below:
1335
1336 .. code-block:: java
1337
1338   {
1339    "command": "chef-client"
1340    "run_timeout": 300
1341    "nodes": ["node1.vnf_a.onap.com", "node2.vnf_a.onap.com"]
1342      "env": {
1343               "RequestId":"8279-abcd-aksdj-19231"
1344               "CallbackUrl":"<callback>"
1345             }
1346   }
1347
1348
1349 5. If CallbackCapable field in the template is not present or set to
1350    "False" ONAP will poll the Chef Server to check completion status of
1351    the push job.
1352
1353 6. If "GetOutputFlag" is set to "True" in the template and
1354    CallbackCapable is not set to "True", ONAP will retrieve any output
1355    from each node where the push job has finished by accessing the Node
1356    Object attribute node['PushJobOutput'].
1357
1358 .. _ansible_playbook_requirements:
1359
1360 Ansible Standards and Capabilities
1361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1362
1363 ONAP will support configuration of VNFs or PNFs via Ansible subject to the
1364 requirements and guidelines defined in this section.
1365
1366 Ansible allows agentless management of VNFs or PNFs/VMs/VNFCs via execution
1367 of 'playbooks' over ssh. The 'playbooks' are a structured set of
1368 tasks which contain all the necessary resources and execution capabilities
1369 to take the necessary action on one or more target VMs (and/or VNFCs)
1370 of the VNF. ONAP will utilize the framework of an Ansible Server that
1371 will host all Ansible artifacts and run playbooks to manage VNFs or PNFs that
1372 support Ansible.
1373
1374 VNF or PNF Configuration via Ansible Requirements
1375 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1376
1377 Ansible Client Requirements
1378 +++++++++++++++++++++++++++++
1379
1380
1381 .. req::
1382     :id: R-32217
1383     :target: VNF or PNF
1384     :keyword: MUST
1385     :updated: dublin
1386
1387     The VNF or PNF **MUST** have routable management IP addresses or FQDNs that
1388     are reachable via the Ansible Server for the endpoints (VMs) of a
1389     VNF or PNF that playbooks will target. ONAP will initiate requests to the
1390     Ansible Server for invocation of playbooks against these end
1391     points [#7.3.3]_.
1392
1393 .. req::
1394     :id: R-54373
1395     :target: VNF or PNF
1396     :keyword: MUST
1397     :updated: guilin
1398
1399     The VNF or PNF Provider **MUST** provide Ansible playbooks that are
1400     compatible with the Operator’s deployed versions of Ansible and Python.
1401     As the Ansible runtime itself is not deployed as part of ONAP, the ONAP
1402     project cannot dictate the specific versions supported.
1403
1404 .. req::
1405     :id: R-35401
1406     :target: VNF or PNF
1407     :keyword: MUST
1408     :updated: dublin
1409
1410     The VNF or PNF **MUST** support SSH and allow SSH access by the
1411     Ansible server to the endpoint VM(s) and comply with the Network
1412     Cloud Service Provider guidelines for authentication and access.
1413
1414 .. req::
1415     :id: R-82018
1416     :target: VNF or PNF
1417     :keyword: MUST
1418     :updated: guilin
1419
1420     The VNF or PNF **MUST** load the Ansible Server SSH public key onto VNF or
1421     PNF VM(s) /root/.ssh/authorized_keys as part of instantiation. Alternative,
1422     is for Ansible Server SSH public key to be loaded onto VNF or PNF
1423     under /home/<Mechanized user ID>/.ssh/authorized_keys as part of
1424     instantiation, when a Mechanized user ID is created during instantiation,
1425     and Configure and all playbooks are designed to use a mechanized user ID
1426     only for authentication (never using root authentication during Configure
1427     playbook run). This will allow the Ansible Server to authenticate to
1428     perform post-instantiation configuration without manual intervention and
1429     without requiring specific VNF or PNF login IDs and passwords.
1430
1431     *CAUTION*: For VNFs or PNFs configured using Ansible, to eliminate the need
1432     for manual steps, post-instantiation and pre-configuration, to
1433     upload of SSH public keys, SSH public keys loaded during (heat)
1434     instantiation shall be preserved and not removed by (heat) embedded
1435     (userdata) scripts.
1436
1437 .. req::
1438     :id: R-92866
1439     :target: VNF or PNF Provider
1440     :keyword: MUST
1441     :updated: dublin
1442
1443     The VNF or PNF Provider **MUST** include as part of post-instantiation
1444     configuration done by Ansible Playbooks the removal/update of the SSH
1445     public key from ``/root/.ssh/authorized_keys``, and update of SSH keys
1446     loaded through instantiation to support Ansible. This may include creating
1447     Mechanized user ID(s) used by the Ansible Server(s) on VNF VM(s) and
1448     uploading and installing new SSH keys used by the mechanized use ID(s).
1449
1450 .. req::
1451     :id: R-97345
1452     :target: VNF or PNF
1453     :keyword: MUST
1454     :introduced: casablanca
1455     :updated: dublin
1456
1457     The VNF or PNF **MUST** permit authentication, using root account, only
1458     right after instantiation and until post-instantiation configuration is
1459     completed.
1460
1461 .. req::
1462     :id: R-97451
1463     :target: VNF or PNF
1464     :keyword: MUST
1465     :introduced: casablanca
1466     :updated: dublin
1467
1468     The VNF or PNF **MUST** provide the ability to remove root access once
1469     post-instantiation configuration (Configure) is completed.
1470
1471 .. req::
1472     :id: R-91745
1473     :target: VNF or PNF
1474     :keyword: MUST
1475     :updated: dublin
1476
1477     The VNF or PNF **MUST** update the Ansible Server and other entities
1478     storing and using the SSH keys for authentication when the SSH
1479     keys used by Ansible are regenerated/updated.
1480
1481     **Note**: Ansible Server itself may be used to upload new SSH public
1482     keys onto supported VNFs or PNFs.
1483
1484 .. req::
1485     :id: R-73459
1486     :target: VNF or PNF
1487     :keyword: MUST
1488     :introduced: casablanca
1489     :updated: dublin
1490
1491     The VNF or PNF **MUST** provide the ability to include a "from=" clause in
1492     SSH public keys associated with mechanized user IDs created for an Ansible
1493     Server cluster to use for VNF or PNF VM authentication.
1494
1495 .. req::
1496     :id: R-45197
1497     :target: VNF or PNF
1498     :keyword: MUST
1499     :introduced: casablanca
1500     :updated: dublin
1501
1502     The VNF or PNF **MUST** define the "from=" clause to provide the list of IP
1503     addresses of the Ansible Servers in the Cluster, separated by coma, to
1504     restrict use of the SSH key pair to elements that are part of the Ansible
1505     Cluster owner of the issued and assigned mechanized user ID.
1506
1507 .. req::
1508     :id: R-94567
1509     :target: VNF or PNF Provider
1510     :keyword: MUST
1511     :introduced: casablanca
1512     :updated: guilin
1513
1514     The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
1515     using an inventory hosts file in a supported format with only IP addresses
1516     or IP addresses and VM/VNF or PNF names.
1517
1518 .. req::
1519     :id: R-67124
1520     :target: VNF or PNF Provider
1521     :keyword: MUST
1522     :introduced: casablanca
1523     :updated: guilin
1524
1525     The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
1526     using an inventory hosts file in a supported format; with group names
1527     matching VNFC 3-character string adding "vip" for groups with virtual IP
1528     addresses shared by multiple VMs as seen in examples provided in Appendix.
1529
1530 .. req::
1531     :id: R-24482
1532     :target: VNF or PNF Provider
1533     :keyword: MUST
1534     :introduced: casablanca
1535     :updated: guilin
1536
1537     The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
1538     using an inventory hosts file in a supported format; with site group that
1539     shall be used to add site specific configurations to the target VNF or PNF
1540     VM(s) as needed.
1541
1542 Ansible Playbook Requirements
1543 +++++++++++++++++++++++++++++++
1544
1545 An Ansible playbook is a collection of tasks that is executed on the
1546 Ansible server (local host) and/or the target VM (s) in order to
1547 complete the desired action.
1548
1549 .. req::
1550     :id: R-49396
1551     :target: VNF or PNF Provider
1552     :keyword: MUST
1553     :updated: guilin
1554
1555     The VNF or PNF Provider's Ansible playbooks **MUST** support each APPC/SDN-C
1556     VNF or PNF action by invocation of **one** playbook [#7.3.4]_. The playbook
1557     will be responsible for executing all necessary tasks (as well as calling
1558     other playbooks) to complete the request.
1559
1560 .. req::
1561     :id: R-33280
1562     :target: VNF or PNF Provider
1563     :keyword: MUST NOT
1564     :updated: guilin
1565
1566     The VNF or PNF Provider's Ansible playbooks **MUST NOT** contain instance
1567     specific values that can not be provided by a parameter to the playbook.
1568
1569 .. req::
1570    :id: R-195620
1571    :keyword: SHOULD
1572    :target: VNF or PNF Provider
1573    :introduced: guilin
1574
1575    The VNF or PNF Provider's Ansible playbooks **SHOULD** compare the version(s)
1576    of Ansible that the VNF Provider developed and tested against to the
1577    ``ansible_version.full`` value during playbook execution, and issue a
1578    ``WARNING`` message if the operator version is not one of the tested
1579    versions.
1580
1581 .. req::
1582    :id: R-918136
1583    :keyword: MUST NOT
1584    :target: VNF or PNF Provider
1585    :introduced: guilin
1586
1587    The VNF or PNF Provider's Ansible playbooks **MUST NOT** fail due to
1588    a mismatched version check as specified in R-918136. The warning message
1589    should be issued, and the playbook execution should continue as normal.
1590
1591 .. req::
1592    :id: R-444446
1593    :keyword: SHOULD
1594    :target: VNF or PNF Provider
1595    :introduced: guilin
1596
1597    The VNF or PNF Provider's Ansible playbooks **SHOULD** issue log messages
1598    in the same format as Ansible's default messages:
1599    ``[<Log Level>]: <message>``
1600
1601    Example:
1602
1603       ``[WARNING]: Ansible version 2.9.3 does not match a known,
1604       tested version: 2.8.1, 2.8.2``
1605
1606 .. req::
1607     :id: R-48698
1608     :target: VNF or PNF Provider
1609     :keyword: MUST
1610     :updated: guilin
1611
1612     The VNF or PNF Provider's Ansible playbooks **MUST** utilize information
1613     from key value pairs that will be provided by the Ansible Server as
1614     ``extra-vars`` during invocation to execute the desired VNF or PNF action.
1615     The "extra-vars" attribute-value pairs are passed to the Ansible Server by
1616     an APPC/SDN-C as part of the Rest API request. If the playbook requires
1617     files, they must also be supplied using the methodology detailed in the
1618     Ansible Server API, unless they are bundled with playbooks, example,
1619     generic templates. Any files containing instance specific info
1620     (attribute-value pairs), not obtainable
1621     from any ONAP inventory databases or other sources, referenced and used as
1622     input by playbooks, shall be provisioned (and distributed) in advance of
1623     use, e.g., VNF or PNF instantiation. Recommendation is to avoid these
1624     instance specific, manually created in advance of instantiation, files.
1625
1626 The Ansible Server will determine if a playbook invoked to execute an
1627 VNF or PNF action finished successfully or not using the "PLAY_RECAP" summary
1628 in Ansible log.  The playbook will be considered to successfully finish
1629 only if the "PLAY RECAP" section at the end of playbook execution output
1630 has no unreachable hosts and no failed tasks. Otherwise, the playbook
1631 will be considered to have failed.
1632
1633
1634 .. req::
1635     :id: R-43253
1636     :target: VNF or PNF Provider
1637     :keyword: MUST
1638     :updated: guilin
1639
1640     The VNF or PNF Provider's Ansible playbooks **MUST** be designed to allow
1641     Ansible Server to infer failure or success based on the "PLAY_RECAP"
1642     capability.
1643
1644     **Note**: There are cases where playbooks need to interpret results
1645     of a task and then determine success or failure and return result
1646     accordingly (failure for failed tasks).
1647
1648 .. req::
1649     :id: R-50252
1650     :target: VNF or PNF Provider
1651     :keyword: MUST
1652     :updated: guilin
1653
1654     The VNF or PNF Provider's Ansible playbooks **MUST** write to a response
1655     file in JSON format that will be retrieved and made available by the
1656     Ansible Server if, as part of a VNF or PNF action (e.g., audit), a playbook
1657     is required to return any VNF or PNF information/response. The text files
1658     must be written in the main playbook home directory, in JSON format. The
1659     JSON file must be created for the VNF or PNF with the name '<VNF or PNF name>_results.txt'. All playbook
1660     output results, for all VNF VMS or PNF Server/Blades, to be provided as a
1661     response to the request, must be written to this response file.
1662
1663 .. req::
1664     :id: R-51442
1665     :target: VNF or PNF Provider
1666     :keyword: SHOULD
1667     :updated: guilin
1668
1669     The VNF or PNF Provider's Ansible playbooks **SHOULD** be designed to
1670     automatically 'rollback' to the original state in case of any errors
1671     for actions that change state of the VNF or PNF (e.g., configure).
1672
1673     **Note**: In case rollback at the playbook level is not supported or
1674     possible, the VNF or PNF provider shall provide alternative rollback
1675     mechanism (e.g., for a small VNF or PNF the rollback mechanism may rely
1676     on workflow to terminate and re-instantiate VNF VMs and then re-run
1677     playbook(s)). Backing up updated files is also recommended to support
1678     rollback when soft rollback is feasible.
1679
1680 .. req::
1681     :id: R-58301
1682     :target: VNF or PNF Provider
1683     :keyword: SHOULD NOT
1684     :updated: dublin
1685
1686     The VNF or PNF Provider's Ansible playbooks **SHOULD NOT** make requests to
1687     Cloud resources e.g. Openstack (nova, neutron, glance, heat, etc.);
1688     therefore, there is no use for Cloud specific variables like Openstack
1689     UUIDs in Ansible Playbook related artifacts.
1690
1691     **Rationale**: Flows that require interactions with Cloud services e.g.
1692     Openstack shall rely on workflows run by an Orchestrator
1693     (Change Management) or other capability (such as a control loop or
1694     Operations GUI) outside Ansible Server which can be executed by a
1695     APPC/SDN-C. There are policies, as part of Control Loop
1696     models, that send remediation action requests to an APPC/SDN-C; these
1697     are triggered as a response to an event or correlated events published
1698     to Event Bus.
1699
1700 .. req::
1701     :id: R-02651
1702     :target: VNF or PNF Provider
1703     :keyword: SHOULD
1704     :updated: guilin
1705
1706     The VNF or PNF Provider's Ansible playbooks **SHOULD** use available backup
1707     capabilities to save a copy of configuration files before implementing
1708     changes to support operations such as backing out of software upgrades,
1709     configuration changes or other work as this will help backing out of
1710     configuration changes when needed.
1711
1712 .. req::
1713     :id: R-43353
1714     :target: VNF or PNF Provider
1715     :keyword: MUST
1716     :updated: guilin
1717
1718     The VNF or PNF Provider's Ansible playbooks **MUST** return control only
1719     after all tasks performed by playbook are fully complete, signaling that the
1720     playbook completed all tasks. When starting services, return control
1721     only after all services are up. This is critical for workflows where
1722     the next steps are dependent on prior tasks being fully completed.
1723
1724 Detailed examples:
1725
1726 ``StopApplication Playbook`` – StopApplication Playbook shall return control
1727 and a completion status response only after VNF or PNF application is fully
1728 stopped, all processes/services stopped.
1729
1730 ``StartApplication Playbook`` – StartApplication Playbook shall return control
1731 and a completion status only after all VNF or PNF application services are
1732 fully up, all processes/services started and ready to provide services.
1733
1734 **NOTE**: Start Playbook should not be declared complete/done after starting
1735 one or several processes that start the other processes.
1736
1737 HealthCheck Playbook:
1738
1739 SUCCESS – HealthCheck success shall be returned (return code 0) by a
1740 Playbook or Cookbook only when VNF or PNF is 100% healthy, ready to take
1741 requests and provide services, with all VNF or PNF required capabilities ready
1742 to provide services and with all active and standby resources fully ready with
1743 no open MINOR, MAJOR or CRITICAL alarms.
1744
1745 NOTE: In some cases, a switch may need to be turned on, but a VNF or PNF
1746 reported as healthy, should be ready to take service requests or be
1747 already processing service requests successfully.
1748
1749 A successful execution of a health-check playbook shall create one response
1750 file (per VNF or PNF) in JSON format, named after the VNF or PNF instance,
1751 followed by "_results.txt" (<VNF or PNF instance name>_results.txt) to be
1752 provided as a response to the requestor, indicating  health-check was executed
1753 and completed successfully, example: vfdb9904v_results.txt, with the following
1754 contents:
1755
1756 .. code-block:: java
1757
1758   {
1759    "identifier": "VNF",
1760    "state": "healthy",
1761    "time": "2018-03-16:1139"
1762   }
1763
1764 Example:
1765
1766 .. code-block:: java
1767
1768   $ cat vfdb9904v_results.txt
1769   {
1770    "identifier": "VNF",
1771    "state": "healthy",
1772    "time": "2018-03-16:1139"
1773   }
1774
1775
1776 **NOTE**: See section 7.3.1.4 for comments on support of partial health checks.
1777
1778 FAILURE – A health check playbook shall return a non-zero return code in
1779 case VNF or PNF is not 100% healthy because one or more VNF or PNF application
1780 processes are stopped or not ready to take service requests or because critical
1781 or non-critical resources are not ready or because there are open MINOR, MAJOR
1782 or CRITICAL traps/alarms or because there are issues with the VNF or PNF that
1783 need attention even if they do not impact services provided by the VNF or PNF.
1784
1785 A failed health-check playbook shall also create one file (per VNF or PNF), in
1786 JSON format, named after the VNF or PNF instance name, followed by
1787 "_results.txt" to indicate health-check was executed and found issues in the
1788 health of the VNF or PNF. This is to differentiate from failure to run
1789 health-check playbook or playbook tasks to verify the health of the VNF or
1790 PNF, example: vfdb9904v_results.txt, with the following contents:
1791
1792 .. code-block:: java
1793
1794  {
1795   "identifier": "VNF",
1796   "state": "unhealthy",
1797   "info": "Error in following VM(s). Check hcstatus files
1798   under /tmp/ccfx9901v for details",
1799   "fault": [
1800     "vfdb9904vm001",
1801     "vfdb9904vm002"
1802   ],
1803   "time": "2018-03-16:4044"
1804  }
1805
1806
1807 Example:
1808
1809 .. code-block:: java
1810
1811  $ cat vfdb9904v_results.txt
1812  {
1813   "identifier": "VNF",
1814   "state": "unhealthy",
1815   "info": "Error in following VM(s). Check hcstatus files
1816   under /tmp/ccfx9901v for details",
1817   "fault": [
1818     "vfdb9904vm001",
1819     "vfdb9904vm002"
1820   ],
1821   "time": "2018-03-16:4044"
1822  }
1823
1824
1825 See `VNF or PNF REST APIs`_ for additional details on HealthCheck.
1826
1827 Some VNFs or PNFs may support and desire to run partial health checks and
1828 receive a successful response when partial health check completes without
1829 errors. The parameter name used by HealthCheck playbook to request non-default
1830 partial health check is healthcheck_type. Example of health check types
1831 could be healthcheck_type=GuestOS, healthcheck_type=noDB,
1832 healthcheck_type=noConnections, healthcheck_type=IgnoreAlarms, etc.. This
1833 attribute-value pair may be passed by Orchestrator or Workflow or other
1834 (northbound) APPC/SDN-C clients to APPC/SDN-C as part of the request.
1835
1836 By default, when no argument/parameter is passed, healthcheck playbook
1837 performs a full VNF or PNF health check.
1838
1839 .. req::
1840     :id: R-24189
1841     :target: VNF or PNF Provider
1842     :keyword: MUST
1843     :introduced: casablanca
1844     :updated: guilin
1845
1846     The VNF or PNF Provider **MUST** deliver a new set of Ansible playbooks that
1847     includes all updated and unchanged playbooks for any new revision to an
1848     existing set of playbooks.
1849
1850 .. req::
1851     :id: R-49911
1852     :target: VNF or PNF Provider
1853     :keyword: MUST
1854     :updated: guilin
1855     :introduced: casablanca
1856
1857     The VNF or PNF Provider **MUST** assign a new point release to the updated
1858     Ansible playbook set. The functionality of a new playbook set must be
1859     tested before it is deployed to the production.
1860
1861 .. req::
1862     :id: R-42333
1863     :target: VNF or PNF Provider
1864     :keyword: MUST
1865     :introduced: frankfurt
1866     :updated: guilin
1867
1868     The VNF or PNF Provider's Ansible playbooks that target a subset of VMs (or
1869     servers/blades) part of a VNF (or PNF) instance **MUST** be designed to use
1870     the VNF or PNF inventory host file and to use a parameter named
1871     ``target_vm_list`` to provide the subset of VMs in the VNF instance
1872     specifically targeted by the playbook.
1873
1874     NOTE: Example of such playbooks would be playbooks used to configure VMs
1875     added to a VNF instance as part of a scale-out/up or scale-in/down
1876     operation. Such playbook is expected to also need to perform
1877     configuration/reconfiguration tasks part of the base VNF instance build.
1878
1879 .. req::
1880     :id: R-39003
1881     :target: VNF or PNF Provider
1882     :keyword: MUST
1883     :introduced: frankfurt
1884     :updated: guilin
1885
1886     The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and
1887     other attributes that must remain secret in JSON, YAML or INI files that
1888     can be encrypted/decrypted using Ansible Vault capabilities.
1889
1890 .. req::
1891     :id: R-46823
1892     :target: VNF or PNF Provider
1893     :keyword: MUST
1894     :introduced: frankfurt
1895
1896     The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and
1897     other attributes that must remain secret in JSON, YAML or INI with
1898     differentiated names when passwords and secrets vary from environment to
1899     environment. Example, name must include <Mechanized user ID>_...json or
1900     <Mechanized user ID>_...xml when labs and production use different passwords
1901     and/or secrets. The <Mechanized user ID> is discovered from the environment
1902     ``/etc/ansible/ansible.cfg`` where the playbook runs.
1903
1904 .. req::
1905     :id: R-83092
1906     :target: VNF or PNF Provider
1907     :keyword: MUST
1908     :introduced: frankfurt
1909     :updated: guilin
1910
1911     The VNF or PNF Provider's Ansible playbooks **MUST** load passwords
1912     and other attributes that must remain secret from JSON, YAML or INI files
1913     that can be encrypted/decrypted using Ansible Vault capabilities.
1914
1915 .. req::
1916     :id: R-09209
1917     :target: VNF or PNF Provider
1918     :keyword: MUST
1919     :introduced: frankfurt
1920     :updated: guilin
1921
1922     The VNF or PNF Provider's Ansible playbooks **MUST** store any playbook
1923     configuration data that requires encryption (passwords, secrets, etc.) in
1924     a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, which will be placed
1925     in ``<VNF type>/<Version>/ansible/vars`` directory.
1926
1927 .. req::
1928     :id: R-56988
1929     :target: VNF or PNF Provider
1930     :keyword: MUST
1931     :introduced: frankfurt
1932
1933     The VNF or PNF Provider's Ansible playbooks **MUST** load any configuration
1934     data that requires encryption (passwords, secrets, etc.) in a JSON (.json),
1935     YAML (.yaml|.yml) or INI (.ini) file, from the
1936     ``<VNF type>/<Version>/ansible/vars`` directory.
1937
1938 .. req::
1939     :id: R-20988
1940     :target: VNF or PNF Provider
1941     :keyword: MUST
1942     :introduced: frankfurt
1943     :updated: guilin
1944
1945     The VNF or PNF Provider's Ansible playbooks **MUST** not log or
1946     display passwords and other attributes that must remain secret when
1947     running playbook in debug mode.
1948
1949     NOTE: Use ``no_log: True``
1950
1951 .. req::
1952     :id: R-53245
1953     :target: VNF or PNF Provider
1954     :keyword: MUST NOT
1955     :introduced: frankfurt
1956     :updated: guilin
1957
1958     The VNF or PNF Provider's Ansible playbooks **MUST** require
1959     passwords or secrets to be passed in clear text in the command line or
1960     Rest API request to run the playbook.
1961
1962 .. req::
1963     :id: R-78640
1964     :target: VNF or PNF Provider
1965     :keyword: SHOULD
1966     :introduced: frankfurt
1967     :updated: guilin
1968
1969     The VNF or PNF Provider's Ansible playbooks **SHOULD** provide a single
1970     YAML or JSON file with all the passwords and secrets to reduce the number
1971     of files to be decrypted/encrypted before on-boarding into the central
1972     repository.
1973
1974 .. req::
1975     :id: R-88786
1976     :target: VNF or PNF Provider
1977     :keyword: MUST
1978     :introduced: frankfurt
1979     :updated: guilin
1980
1981     The VNF or PNF Provider's Ansible playbooks **SHOULD** place the passwords
1982     and secrets to be edited at the top of the single YAML or JSON file with
1983     all the secrets, and the (default) ones that are to remain unchanged '
1984     towards the bottom, with commentary separating them.
1985
1986 .. req::
1987     :id: R-88002
1988     :target: VNF or PNF Provider
1989     :keyword: MUST
1990     :introduced: frankfurt
1991
1992     The VNF or PNF Provider **MUST** use a pre-agreed upon password to encrypt
1993     the Ansible Vault file, or provide the vault password used to encrypt
1994     the file to the customer, in a secure manner, to allow the customer to
1995     decrypt/encrypt (rekey) Ansible Vault files before they are checked
1996     into the central repository for distribution.
1997
1998 Ansible API Usage
1999 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2000
2001 This section outlines the workflow that APPC/SDN-C invokes when
2002 it receives an action request against an Ansible managed VNF or PNF.
2003
2004  #. When APPC/SDN-C receives a request for an action for an
2005     Ansible managed VNF or PNF, it retrieves the corresponding template (based
2006     on **action** and **VNF or PNF Type**) from its database and sets necessary
2007     values (such as an Id, NodeList, and EnvParameters) from either
2008     information either in the request or data obtained from other sources,
2009     inventory database, is an example of such sources.
2010     This is referred to as the payload that is sent as a JSON object
2011     to the Ansible server as part of the Rest API request.
2012  #. The APPC/SDN-C sends a request to the Ansible server to
2013     execute the action.
2014  #. The APPC/SDN-C, after sending a request to the Ansible server,
2015     polls it to get results(success or failure). The APPC/SDN-C has a
2016     timeout value which is contained in the action request template. Different
2017     actions can set different timeout values (default setting is 600 seconds).
2018     If the result is not available when the timeout is reached, the APPC/SDN-C
2019     stops polling and returns a timeout error to the requester.
2020     The Ansible Server continues to process the request.
2021
2022
2023 Support of APPC/SDN-C Commands And Southbound Protocols
2024 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025
2026 The following table summarizes the commands and possible protocols selected.
2027 Note that the HealthCheck can also be supported via REST.
2028
2029 Table 8. APPC/SDN-C APIs and NETCONF Commands
2030
2031 +-------------+--------------------+--------------------+--------------------+
2032 |**Command**  |**NETCONF Support** |**Chef Support**    |**Ansible**         |
2033 +=============+====================+====================+====================+
2034 |General      |For each RPC, the   |VNF or PNF Vendor   |VNF Vendor must     |
2035 |Comments     |appropriate RPC     |must provide any    |provide an Ansible  |
2036 |             |operation is listed.|necessary roles,    |playbook to retrieve|
2037 |             |                    |cookbooks, recipes  |the running         |
2038 |             |                    |to retrieve the     |configuration from a|
2039 |             |                    |running             |VNF and place the   |
2040 |             |                    |configuration from  |output on the       |
2041 |             |                    |a VNF or PNF and    |Ansible server in   |
2042 |             |                    |place it in the     |a manner aligned    |
2043 |             |                    |respective Node     |with playbook       |
2044 |             |                    |Objects             |requirements listed |
2045 |             |                    |'PushJobOutput'     |in this document.   |
2046 |             |                    |attribute of all    |                    |
2047 |             |                    |nodes in NodeList   |The PlaybookName    |
2048 |             |                    |when triggered by a |must be provided    |
2049 |             |                    |chef-client run.    |in the JSON file.   |
2050 |             |                    |                    |                    |
2051 |             |                    |The JSON file for   |NodeList must list  |
2052 |             |                    |this VNF or PNF     |IP addresses or DNS |
2053 |             |                    |action is required  |supported FQDNs of  |
2054 |             |                    |to set "PushJobFlag"|the VNF instance    |
2055 |             |                    |to "True" and       |on which to         |
2056 |             |                    |"GetOutputFlag" to  |execute playbook.   |
2057 |             |                    |"True". The "Node"  |                    |
2058 |             |                    |JSON dictionary     |                    |
2059 |             |                    |must have the run   |                    |
2060 |             |                    |list populated      |                    |
2061 |             |                    |with the necessary  |                    |
2062 |             |                    |sequence of roles,  |                    |
2063 |             |                    |cookbooks, recipes. |                    |
2064 |             |                    |                    |                    |
2065 |             |                    |The Environment     |                    |
2066 |             |                    |and Node values     |                    |
2067 |             |                    |should contain all  |                    |
2068 |             |                    |appropriate         |                    |
2069 |             |                    |configuration       |                    |
2070 |             |                    |attributes.         |                    |
2071 |             |                    |                    |                    |
2072 |             |                    |NodeList must       |                    |
2073 |             |                    |list sample FQDNs   |                    |
2074 |             |                    |that are required to|                    |
2075 |             |                    |conduct a           |                    |
2076 |             |                    |chef-client run for |                    |
2077 |             |                    |this VNF Action.    |                    |
2078 +-------------+--------------------+--------------------+--------------------+
2079 |Audit        |The <get-config> is |Supported via a     |Supported via a     |
2080 |             |used to return the  |cookbook that       |playbook that       |
2081 |             |running             |returns the running |returns the running |
2082 |             |configuration.      |configuration.      |configuration.      |
2083 +-------------+--------------------+--------------------+--------------------+
2084 |Configure,   |The <edit-config>   |Supported via a     |Supported via a     |
2085 |ModifyConfig |operation loads all |cookbook that       |playbook that       |
2086 |             |or part of a        |updates the VNF or  |updates the VNF     |
2087 |             |specified data set  |PNF configuration.  |configuration.      |
2088 |             |to the specified    |                    |                    |
2089 |             |target database. If |                    |                    |
2090 |             |there is no         |                    |                    |
2091 |             |<candidate/>        |                    |                    |
2092 |             |database, then the  |                    |                    |
2093 |             |target is the       |                    |                    |
2094 |             |<running/> database.|                    |                    |
2095 |             |A <commit> follows. |                    |                    |
2096 +-------------+--------------------+--------------------+--------------------+
2097 |Other        |This command has no |Supported via a     |Supported via a     |
2098 |Configuration|existing NETCONF RPC|cookbook that       |playbook that       |
2099 |Commands     |action.             |performs            |performs            |
2100 |             |                    |the action.         |the action.         |
2101 +-------------+--------------------+--------------------+--------------------+
2102 |Lifecycle    |This command has no |Supported via a     |Supported via a     |
2103 |Management   |existing NETCONF RPC|cookbook that       |playbook that       |
2104 |Commands     |action.             |performs            |performs            |
2105 |             |                    |the action.         |the action.         |
2106 +-------------+--------------------+--------------------+--------------------+
2107 |Health Check |This command has no |Supported via a     |Supported           |
2108 |             |existing NETCONF RPC|cookbook            |via a               |
2109 |             |action.             |that                |playbook            |
2110 |             |                    |performs            |that                |
2111 |             |                    |a HealthCheck and   |performs            |
2112 |             |                    |returns the results.|the                 |
2113 |             |                    |                    |HealthCheck         |
2114 |             |                    |                    |and returns         |
2115 |             |                    |                    |the                 |
2116 |             |                    |                    |results.            |
2117 +-------------+--------------------+--------------------+--------------------+
2118
2119 .. [#7.3.1]
2120    https://github.com/mbj4668/pyang
2121
2122 .. [#7.3.2]
2123    Recall that the Node Object **is required** to be identical across
2124    all VMs of a VNF or PNF invoked as part of the action except for the "name".
2125
2126 .. [#7.3.3]
2127    Upstream elements must provide the appropriate FQDN in the request to
2128    ONAP for the desired action.
2129
2130 .. [#7.3.4]
2131    Multiple ONAP actions may map to one playbook.
2132
2133