1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
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
7 .. https://creativecommons.org/licenses/by/4.0/
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.
15 .. _vnf_configuration_management:
17 Configuration Management
18 ------------------------
20 Controller Interactions With xNF
21 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23 APPC/SDN-C expose a northbound API to clients (such as SO) in order for
24 the clients to initiate an activity (aka command) on a xNF. APPC/SDN-C
25 interact with xNFs through Network and Application Adapters to perform
26 configuration and other lifecycle management activities within NFV environment.
27 The standardized models, protocols and mechanisms by which network functions
28 are configured are equally applicable to VNFs and PNFs.
30 This section describes the list of commands that should be supported
31 by the xNF. The following sections describe the standard protocols
32 that are supported (NETCONF, Chef, Ansible, and REST).
34 The commands below are expected to be supported on all xNF's, unless
35 The commands below are expected to be supported on all xNF's, unless
36 noted otherwise, either directly (via the NETCONF or REST interface)
37 or indirectly (via a Chef Cookbook or Ansible server).
39 **Note that there are additional commands offered to northbound clients that
40 are not shown below, as these commands either act internally on APPC/SDN-C
41 itself or depend upon network cloud components for implementation (thus, these
42 actions do not put any special requirement on the xNF provider).**
44 The commands allow for parametric data to be passed from APPC/SDN-C
45 to the xNF or Ansible/Chef server in the request. The format of the
46 parameter data can be either xml (for NETCONF) or JSON (for Ansible,
49 Configuration Commands
50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52 ``Configure``: The APPC/SDN-C client is requesting that a post-instantiation
53 configuration be applied to the target xNF. After the Configure
54 action is completed, the xNF instance should be ready for service.
55 Note that customer specific configurations may need to be applied using
56 the ConfigModify action. This command requires exclusive access rights of
59 ``ConfigModify``: The APPC client is requesting a configuration
60 update to a subset of the total configuration parameters of an xNF or to
61 apply customer specific configurations. The configuration update is
62 typically done while the xNF is in service and should not disrupt traffic.
63 This command requires exclusive access rights of the xNF.
65 ``ConfigBackup``: The APPC client is requesting a backup of the
66 configuration parameters where the parameters are stored on the xNF.
67 This command is typically requested as part of an orchestration flow
68 for scenarios such as a software upgrade. The ConfigBackup is typically
69 done while the xNF is not in service (i.e., in a maintenance state).
70 When the ConfigBackup command is executed, the current xNF configuration
71 parameters are saved in storage that is preserved (if there is an existing
72 set of backed up parameters, they are overwritten). This command requires
73 exclusive access rights of the xNF.
75 ``ConfigRestore``: The APPC client is requesting a restore action of
76 the configuration parameters to the xNF that were saved by ConfigBackup
77 command. This command is typically requested as part of an orchestration
78 flow for scenarios such as a software upgrade where the software upgrade
79 may have failed and the xNF needs to be rolled back to the prior configuration.
80 When the ConfigRestore command is executed, the xNF configuration parameters
81 which were backed to persistent preserved storage are applied to the xNF
82 (replacing existing parameters). The ConfigRestore is typically done while
83 the xNF is not in service (i.e., in a maintenance state). This command
84 requires exclusive access rights of the xNF.
86 ``ConfigScaleOut``: The APPC/SDN-C client is requesting that a configuration
87 be applied after the VNF instance has been scaled out (i.e., one or more
88 additional VM's instantiated to increase capacity). For some VNF's,
89 ConfigScaleOut is not needed because the VNF is auto-configured after
90 scale-out. This command is being introduced in the Beijing release to support
91 manual Scale Out and will be extended to support Auto ScaleOut in Casablanca
92 release. This command requires exclusive access rights of the VNF.
94 ``Audit``: The APPC client is requesting that the current (last known
95 configuration update) is audited against the running configuration on the VNF
104 The xNF **MUST** support APPC/SDN-C ``Configure`` command.
112 The xNF **MUST** support APPC ``ConfigModify`` command.
120 The xNF **MUST** support APPC ``ConfigBackup`` command.
128 The xNF **MUST** support APPC ``ConfigRestore`` command.
136 The xNF **MUST** support APPC/SDN-C ``ConfigScaleOut`` command.
144 The xNF **MUST** support APPC ``Audit`` command.
146 Lifecycle Management Related Commands
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149 **The following commands are needed to support various lifecycle management
150 flows where the VNF may need to be removed for service.**
152 Full details on the APIs can be found in the :doc:`APPC LCM API Guide <../../../../appc.git/docs/APPC LCM API Guide/APPC LCM API Guide>`
154 ``DistributeTraffic`` The APPC/SDN-C client is requesting a change to
155 traffic distribution (redistribution) done by a traffic balancing/distribution
156 entity (aka anchor point) or mechanism. This action targets the traffic
157 balancing/distribution entity, in some cases DNS, other cases a load balancer
158 external to the VNF instance, as examples. Traffic distribution (weight)
159 changes intended to take a VNF instance out of service are completed only
160 when all in-flight traffic/transactions have been completed. To complete
161 the traffic redistribution process, gracefully taking a VNF instance
162 out-of-service, without dropping in-flight calls or sessions, QuiesceTraffic
163 command may need to follow traffic distribution changes (assigning weight 0
164 or very low weight to VNF instance). The VNF application remains in an active
167 ``QuiesceTraffic`` The APPC/SDN-C client is requesting the xNF gracefully
168 stop traffic (aka block and drain traffic). The method for quiescing traffic
169 is specific to the xNF architecture. The action is completed when all
170 (in-flight transactions) traffic has stopped. The xNF remains in an active
171 state where the xNF is able to process traffic (initiated using the
172 ResumeTraffic action).
174 ``ResumeTraffic``: The APPC/SDN-C client is requesting the xNF resume
175 processing traffic. The method to resume traffic is specific to the xNF
178 ``StopApplication``: The APPC client is requesting that the application
179 running on the xNF is stopped gracefully (i.e., without traffic loss).
180 This is equivalent to quiescing the traffic and then stopping the application
181 processes. The processes can be restarted using the StartApplication command.
183 ``StartApplication``: The APPC client is requesting that the application
184 running on the xNF is started. Get ready to process traffic. Traffic processing
185 can be resumed using the ResumeTraffic command.
187 **The following commands are needed to support software upgrades, in-place or
188 other type of software upgrade. The xNF instance may be removed from service
191 ``UpgradePrecheck``: The APPC/SDN-C client is requesting a confirmation that
192 the xNF can (and needs to) be upgraded to a specific software version
193 (specified in the request). Checking software installed and running on
194 the xNF matches software version, intended to be upgraded, is one of the
197 ``UpgradeSoftware``: The APPC/SDN-C client is requesting that a (in-place)
198 software upgrade be performed on the xNF. The software to be applied is
199 pre-loaded to a specified location.
201 ``UpgradePostCheck``: The APPC/SDN-C client is requesting a confirmation that
202 the xNF software upgrade has been completed successfully (xNF upgraded to
203 the new software version). Checking software installed and running on the xNF
204 matches software version, of the newly upgraded software, is one of the
207 ``UpgradeBackup``: The APPC/SDN-C client is requesting that the xNF is backed
208 up prior to the UpgradeSoftware.
210 ``UpgradeBackOut``: The APPC/SDN-C client is requesting that the xNF upgrade
211 is backed out (in the event that the SoftwareUpgrade or UpgradePostCheck
218 :introduced: casablanca
220 The xNF **MUST**, if serving as a distribution point or anchor point for
221 steering point from source to destination, support the ONAP Controller's
222 ``DistributeTraffic`` command.
230 The xNF **MUST** support APPC/SDN-C ``QuiesceTraffic`` command.
238 The xNF **MUST** support APPC/SDN-C ``ResumeTraffic`` command.
246 The xNF **MUST** support APPC ``StopApplication`` command.
254 The xNF **MUST** support APPC ``StartApplication`` command.
262 The xNF **MUST** support APPC/SDN-C ``UpgradePrecheck`` command.
270 The xNF **MUST** support APPC/SDN-C ``UpgradeSoftware`` command.
278 The xNF **MUST** support APPC/SDN-C ``UpgradePostCheck`` command.
286 The xNF **MUST** support APPC/SDN-C ``UpgradeBackup`` command.
294 The xNF **MUST** support APPC/SDN-C ``UpgradeBackOut`` command.
297 HealthCheck and Failure Related Commands
298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
300 ``HealthCheck`` The APPC/SDN-C client is requesting a health check over the
301 entire scope of the xNF. The xNF must be 100% healthy, ready to take requests
302 and provide services, with all xNF required capabilities ready to provide
303 services and with all active and standby resources fully ready with no open
304 MINOR, MAJOR or CRITICAL alarms. This is expected to be the default in the
305 event that no parameter is passed to the Healthcheck playbook, cookbook, etc.
307 Some xNFs may support and desire to run partial healthchecks and receive a
308 successful response when partial health check completes without errors.
309 The parameter name used by HealthCheck playbook to request non-default
310 partial health check is healthcheck_type. Example of health check types
311 could be healthcheck_type=GuestOS, healthcheck_type=noDB,
312 healthcheck_type=noConnections, healthcheck_type=IgnoreAlarms, etc..
313 This attribute-value pair may be passed by the Orchestrator or Workflow
314 or other (northbound) APPC/SDN-C clients to the APPC/SDN-C as part of the
317 **Note**: In addition to the commands above, the APPC/SDN-C supports a set of
318 Openstack failure recovery related commands that are executed on-demand or via
319 Control Loop at the VM level. The VNF must support these commands in a fully
328 The xNF **MUST** support APPC/SDN-C ``HealthCheck`` command.
330 Notes On Command Support Using APPC/SDN-C Southbound Protocols
331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
333 APPC/SDN-C are designed to support a standard set of protocols in
334 order to communicate with the xNF instance. The supported protocols are
335 NETCONF, Ansible, Chef, and REST.
337 NETCONF and REST require the xNF to implement a server which supports the RPC
340 Ansible and Chef require the use of a Ansible or Chef server which communicates
341 with the APPC/SDN-C (northbound) and the xNF VM's (southbound).
343 The vendor must select which protocol to support for the commands listed above.
346 * NETCONF is most suitable for configuration related commands.
348 * Ansible and Chef are suitable for any command.
349 Ansible has the advantage that it is agentless.
351 * REST is specified as an option only for the HealthCheck.
354 Additional details can be found in the
355 `ONAP Application Controller (APPC) API Guide <https://onap.readthedocs.io/en/latest/submodules/appc.git/docs/index.html>`_,
356 `ONAP VF-C project <https://onap.readthedocs.io/en/latest/submodules/vfc/nfvo/lcm.git/docs/index.html>`_ and
357 the `ONAP SDNC project <https://onap.readthedocs.io/en/latest/submodules/sdnc/oam.git/docs/index.html>`_.
359 NETCONF Standards and Capabilities
360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362 APPC/SDN-C and their Adapters utilize device YANG model and
363 NETCONF APIs to make the required changes in the xNF state and
364 configuration. The xNF providers must provide the Device YANG model and
365 NETCONF server supporting NETCONF APIs to comply with target ONAP and
368 xNF Configuration via NETCONF Requirements
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371 Configuration Management
372 +++++++++++++++++++++++++++
380 The xNF **MUST** include a NETCONF server enabling
381 runtime configuration and lifecycle management capabilities.
388 The xNF **MUST** provide a NETCONF interface fully defined
389 by supplied YANG models for the embedded NETCONF server.
391 NETCONF Server Requirements
392 ++++++++++++++++++++++++++++++
400 The xNF **MUST** allow the NETCONF server connection
401 parameters to be configurable during virtual machine instantiation
402 through Heat templates where SSH keys, usernames, passwords, SSH
403 service and SSH port numbers are Heat template parameters.
411 The xNF **MUST** implement the protocol operation:
412 ``close-session()`` - Gracefully close the current session.
420 The xNF **MUST** implement the protocol operation:
421 ``commit(confirmed, confirm-timeout)`` - Commit candidate
422 configuration data store to the running configuration.
430 The xNF **MUST** implement the protocol operation:
431 ``discard-changes()`` - Revert the candidate configuration
432 data store to the running configuration.
440 The xNF **MUST** implement the protocol operation:
441 ``edit-config(target, default-operation, test-option, error-option,
442 config)`` - Edit the target configuration data store by merging,
443 replacing, creating, or deleting new config elements.
450 The xNF **MUST** implement the protocol operation:
451 ``get(filter)`` - Retrieve (a filtered subset of) the running
452 configuration and device state information. This should include
453 the list of xNF supported schemas.
461 The xNF **MUST** implement the protocol operation:
462 ``get-config(source, filter`` - Retrieve a (filtered subset of
463 a) configuration from the configuration data store source.
471 The xNF **MUST** implement the protocol operation:
472 ``kill-session(session``- Force the termination of **session**.
480 The xNF **MUST** implement the protocol operation:
481 ``lock(target)`` - Lock the configuration data store target.
489 The xNF **MUST** implement the protocol operation:
490 ``unlock(target)`` - Unlock the configuration data store target.
498 The xNF **SHOULD** implement the protocol operation:
499 ``copy-config(target, source)`` - Copy the content of the
500 configuration data store source to the configuration data store target.
508 The xNF **SHOULD** implement the protocol operation:
509 ``delete-config(target)`` - Delete the named configuration
517 The xNF **SHOULD** implement the protocol operation:
518 ``get-schema(identifier, version, format)`` - Retrieve the YANG schema.
525 The xNF **MUST** allow all configuration data to be
526 edited through a NETCONF <edit-config> operation. Proprietary
527 NETCONF RPCs that make configuration changes are not sufficient.
534 The xNF **MUST** allow the entire configuration of the xNF to be
535 retrieved via NETCONF's <get-config> and <edit-config>, independently
536 of whether it was configured via NETCONF or other mechanisms.
543 The xNF **MUST** support ``:partial-lock`` and
544 ``:partial-unlock`` capabilities, defined in RFC 5717. This
545 allows multiple independent clients to each write to a different
546 part of the <running> configuration at the same time.
553 The xNF **MUST** support ``:rollback-on-error`` value for
554 the <error-option> parameter to the <edit-config> operation. If any
555 error occurs during the requested edit operation, then the target
556 database (usually the running configuration) will be left unaffected.
557 This provides an 'all-or-nothing' edit mode for a single <edit-config>
565 The xNF **MUST** support the ``:startup`` capability. It
566 will allow the running configuration to be copied to this special
567 database. It can also be locked and unlocked.
574 The xNF **MUST** support the ``:url`` value to specify
575 protocol operation source and target parameters. The capability URI
576 for this feature will indicate which schemes (e.g., file, https, sftp)
577 that the server supports within a particular URL value. The 'file'
578 scheme allows for editable local configuration databases. The other
579 schemes allow for remote storage of configuration databases.
586 The xNF **MUST** implement both ``:candidate`` and
587 ``:writable-running`` capabilities. When both ``:candidate`` and
588 ``:writable-running`` are provided then two locks should be supported.
595 The xNF **MUST** fully support the XPath 1.0 specification
596 for filtered retrieval of configuration and other database contents.
597 The 'type' attribute within the <filter> parameter for <get> and
598 <get-config> operations may be set to 'xpath'. The 'select' attribute
599 (which contains the XPath expression) will also be supported by the
600 server. A server may support partial XPath retrieval filtering, but
601 it cannot advertise the ``:xpath`` capability unless the entire XPath
602 1.0 specification is supported.
609 The xNF **MUST** implement the ``:validate`` capability.
616 The xNF **MUST** implement ``:confirmed-commit`` If
617 ``:candidate`` is supported.
624 The xNF **MUST** implement the ``:with-defaults`` capability
632 The xNF **MUST** implement the data model discovery and
633 download as defined in [RFC6022].
640 The VNF or PNF **MUST** define all data models in YANG 1.0 [RFC6020] or
641 YANG 1.1 [RFC7950]. A combination of YANG 1.0 and YANG 1.1 modules is
642 allowed subject to the rules in [RFC7950] section 12. The mapping to
643 NETCONF shall follow the rules defined in this RFC.
650 The VNF or PNF **MUST** follow the data model update rules defined in
651 [RFC6020] section 10 for YANG 1.0 modules, and [RFC7950] section 11
652 for YANG 1.1 modules. All deviations from the aforementioned update
653 rules shall be handled by a built-in automatic upgrade mechanism.
660 The xNF **MUST** support parallel and simultaneous
661 configuration of separate objects within itself.
668 The xNF **MUST** support locking if a common object is
669 being manipulated by two simultaneous NETCONF configuration operations
670 on the same xNF within the context of the same writable running data
671 store (e.g., if an interface parameter is being configured then it
672 should be locked out for configuration by a simultaneous configuration
673 operation on that same interface parameter).
680 The xNF **MUST** apply locking based on the sequence of
681 NETCONF operations, with the first configuration operation locking
682 out all others until completed.
689 The xNF **MUST** permit locking at the finest granularity
690 if a xNF needs to lock an object for configuration to avoid blocking
691 simultaneous configuration operations on unrelated objects (e.g., BGP
692 configuration should not be locked out if an interface is being
693 configured or entire Interface configuration should not be locked out
694 if a non-overlapping parameter on the interface is being configured).
701 The xNF **MUST** be able to specify the granularity of the
702 lock via a restricted or full XPath expression.
709 The xNF **MUST** guarantee the xNF configuration integrity
710 for all simultaneous configuration operations (e.g., if a change is
711 attempted to the BUM filter rate from multiple interfaces on the same
712 EVC, then they need to be sequenced in the xNF without locking either
713 configuration method out).
720 The xNF **MUST** release locks to prevent permanent lock-outs
721 when/if a session applying the lock is terminated (e.g., SSH session
729 The xNF **MUST** release locks to prevent permanent lock-outs
730 when the corresponding <partial-unlock> operation succeeds.
737 The xNF **MUST** release locks to prevent permanent lock-outs
738 when a user configured timer has expired forcing the NETCONF SSH Session
739 termination (i.e., product must expose a configuration knob for a user
740 setting of a lock expiration timer).
747 The xNF **MUST** allow another NETCONF session to be able to
748 initiate the release of the lock by killing the session owning the lock,
749 using the <kill-session> operation to guard against hung NETCONF sessions.
756 The xNF **MUST** support simultaneous <commit> operations
757 within the context of this locking requirements framework.
764 The xNF **MUST** support all operations, administration and
765 management (OAM) functions available from the supplier for xNFs using
766 the supplied YANG code and associated NETCONF servers.
773 The xNF **MUST** support sub tree filtering.
780 TThe xNF **MUST** support heartbeat via a <get> with null filter.
787 The xNF PACKAGE **MUST** validated YANG code using the open
788 source pyang [#7.3.1]_ program using the following commands:
792 $ pyang --verbose --strict <YANG-file-name(s)> $ echo $!
799 The xNF **MUST** have the echo command return a zero value
800 otherwise the validation has failed.
807 The xNF **MUST** support a NETCONF server that can be mounted on
808 OpenDaylight (client) and perform the operations of: modify, update,
809 change, rollback configurations using each configuration data element,
810 query each state (non-configuration) data element, execute each YANG
811 RPC, and receive data through each notification statement.
813 The following requirements provides the Yang models that suppliers must
814 conform, and those where applicable, that suppliers need to use.
822 The xNF **MUST** conform its YANG model to RFC 6470,
823 "NETCONF Base Notifications".
830 The xNF **MUST** conform its YANG model to RFC 6244,
831 "An Architecture for Network Management Using NETCONF and YANG".
838 The xNF **MUST** conform its YANG model to RFC 6087,
839 "Guidelines for Authors and Reviewers of YANG Data Model Documents".
846 The xNF **SHOULD** conform its YANG model to RFC 6991,
847 "Common YANG Data Types".
854 The xNF **SHOULD** conform its YANG model to RFC 6536,
855 "NETCONF Access Control Model".
862 The xNF **SHOULD** conform its YANG model to RFC 7223,
863 "A YANG Data Model for Interface Management".
870 The xNF **SHOULD** conform its YANG model to RFC 7223,
871 "IANA Interface Type YANG Module".
878 The xNF **SHOULD** conform its YANG model to RFC 7277,
879 "A YANG Data Model for IP Management".
886 The xNF **SHOULD** conform its YANG model to RFC 7317,
887 "A YANG Data Model for System Management".
894 The xNF **SHOULD** conform its YANG model to RFC 7407,
895 "A YANG Data Model for SNMP Configuration", if Netconf used to
896 configure SNMP engine.
898 The NETCONF server interface shall fully conform to the following
907 The xNF **MUST** conform to the NETCONF RFC 4741,
908 "NETCONF Configuration Protocol".
915 The xNF **MUST** conform to the NETCONF RFC 4742,
916 "Using the NETCONF Configuration Protocol over Secure Shell (SSH)".
923 The xNF **MUST** conform to the NETCONF RFC 5277,
924 "NETCONF Event Notification".
931 The xNF **MUST** conform to the NETCONF RFC 5717,
932 "Partial Lock Remote Procedure Call".
939 The xNF **MUST** conform to the NETCONF RFC 6241,
940 "NETCONF Configuration Protocol".
947 The xNF **MUST** conform to the NETCONF RFC 6242,
948 "Using the Network Configuration Protocol over Secure Shell".
956 The VNF or PNF **SHOULD** support TLS as secure transport for the NETCONF
957 protocol according to [RFC7589].
965 HealthCheck is a command for which no NETCONF support exists.
966 Therefore, this must be supported using a RESTful interface
967 (defined in this section) or with a Chef cookbook/Ansible playbook
968 (defined in sections `Chef Standards and Capabilities`_ and
969 `Ansible Standards and Capabilities`_).
971 See section 7.3.1.4 for the definition of Full Healthcheck and Partial
974 The xNF must provide a REST formatted GET RPCs to support HealthCheck
975 queries via the GET method over HTTP(s).
977 The port number, url, and other authentication information is provided
988 The xNF **MUST** support the HealthCheck RPC. The HealthCheck
989 RPC executes a xNF Provider-defined xNF HealthCheck over the scope of
990 the entire xNF (e.g., if there are multiple VNFCs, then run a health check,
991 as appropriate, for all VNFCs). It returns a 200 OK if the test completes.
992 A JSON object is returned indicating state (healthy, unhealthy), scope
993 identifier, time-stamp and one or more blocks containing info and fault
994 information. If the xNF is unable to run the HealthCheck, return a
995 standard http error code and message.
997 Examples of responses when HealthCheck runs and is able to provide a healthy
998 or unhealthy response:
1000 .. code-block:: java
1003 "identifier": "scope represented",
1005 "time": "01-01-1000:0000"
1009 "identifier": "scope represented",
1010 "state": "unhealthy",
1012 "info": "System threshold exceeded details",
1016 "cpuThreshold": 0.45
1019 "time": "01-01-1000:0000"
1023 Chef Standards and Capabilities
1024 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1026 ONAP will support configuration of xNFs via Chef subject to the
1027 requirements and guidelines defined in this section.
1029 The Chef configuration management mechanism follows a client-server
1030 model. It requires the presence of a Chef-Client on the xNF that will be
1031 directly managed by a Chef Server. The Chef-client will register with
1032 the appropriate Chef Server and are managed via 'cookbooks' and
1033 configuration attributes loaded on the Chef Server which contain all
1034 necessary information to execute the appropriate actions on the xNF via
1037 ONAP will utilize the open source Chef Server, invoke the documented
1038 Chef REST APIs to manage the xNF and requires the use of open source
1039 Chef-Client and Push Jobs Client on the xNF
1040 (https://downloads.chef.io/).
1042 xNF Configuration via Chef Requirements
1043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1045 Chef Client Requirements
1046 +++++++++++++++++++++++++
1054 The xNF **MUST** have the chef-client be preloaded with
1055 validator keys and configuration to register with the designated
1056 Chef Server as part of the installation process.
1063 The xNF **MUST** have routable FQDNs for all the endpoints
1064 (VMs) of a xNF that contain chef-clients which are used to register
1065 with the Chef Server. As part of invoking xNF actions, ONAP will
1066 trigger push jobs against FQDNs of endpoints for a xNF, if required.
1073 The xNF **MAY** expose a single endpoint that is
1074 responsible for all functionality.
1081 The xNF **MUST** be installed with Chef-Client >= 12.0 and Chef
1082 push jobs client >= 2.0.
1084 Chef Roles/Requirements
1085 ++++++++++++++++++++++++++
1092 The xNF Package **MUST** include all relevant Chef artifacts
1093 (roles/cookbooks/recipes) required to execute xNF actions requested by
1094 ONAP for loading on appropriate Chef Server.
1100 :updated: casablanca
1102 The xNF Package **MUST** include a run list of
1103 roles/cookbooks/recipes, for each supported xNF action, that will
1104 perform the desired xNF action in its entirety as specified by ONAP
1105 (see Section 7.c, APPC/SDN-C APIs and Behavior, for list of xNF
1106 actions and requirements), when triggered by a chef-client run list
1114 The xNF **MUST NOT** use any instance specific parameters
1115 for the xNF in roles/cookbooks/recipes invoked for a xNF action.
1122 The xNF **MUST** accept all necessary instance specific
1123 data from the environment or node object attributes for the xNF
1124 in roles/cookbooks/recipes invoked for a xNF action.
1131 The xNF **MUST** over-ride any default values for
1132 configurable parameters that can be set by ONAP in the roles,
1133 cookbooks and recipes.
1140 The xNF **MUST** update status on the Chef Server
1141 appropriately (e.g., via a fail or raise an exception) if the
1142 chef-client run encounters any critical errors/failures when
1143 executing a xNF action.
1150 The xNF **MUST** populate an attribute, defined as node
1151 ['PushJobOutput'] with the desired output on all nodes in the push job
1152 that execute chef-client run if the xNF action requires the output of a
1153 chef-client run be made available (e.g., get running configuration).
1160 The xNF Package **MUST** have appropriate cookbooks that are
1161 designed to automatically 'rollback' to the original state in case of
1162 any errors for actions that change state of the xNF (e.g., configure).
1169 The xNF **SHOULD** support callback URLs to return information
1170 to ONAP upon completion of the chef-client run for any chef-client run
1171 associated with a xNF action.
1173 - As part of the push job, ONAP will provide two parameters in the
1174 environment of the push job JSON object:
1176 - "RequestId" a unique Id to be used to identify the request,
1177 - "CallbackUrl", the URL to post response back.
1179 - If the CallbackUrl field is empty or missing in the push job, then
1180 the chef-client run need not post the results back via callback.
1187 The xNF **MUST** Upon completion of the chef-client run,
1188 POST back on the callback URL, a JSON object as described in Table
1189 A2 if the chef-client run list includes a cookbook/recipe that is
1190 callback capable. Failure to POST on the Callback Url should not be
1191 considered a critical error. That is, if the chef-client successfully
1192 completes the xNF action, it should reflect this status on the Chef
1193 Server regardless of whether the Callback succeeded or not.
1198 This section outlines the workflow that ONAP invokes when it receives an
1199 action request against a Chef managed xNF.
1201 1. When ONAP receives a request for an action for a Chef Managed xNF, it
1202 retrieves the corresponding template (based on **action** and
1203 **xNF**) from its database and sets necessary values in the
1204 "Environment", "Node" and "NodeList" keys (if present) from either
1205 the payload of the received action or internal data.
1207 2. If "Environment" key is present in the updated template, it posts the
1208 corresponding JSON dictionary to the appropriate Environment object
1209 REST endpoint on the Chef Server thus updating the Environment
1210 attributes on the Chef Server.
1212 3. Next, it creates a Node Object from the "Node" JSON dictionary for
1213 all elements listed in the NodeList (using the FQDN to construct the
1214 endpoint) by replicating it [#7.3.2]_. As part of this process, it will
1215 set the name field in each Node Object to the corresponding FQDN.
1216 These node objects are then posted on the Chef Server to
1217 corresponding Node Object REST endpoints to update the corresponding
1220 4. If PushJobFlag is set to "True" in the template, ONAP requests a push
1221 job against all the nodes in the NodeList to trigger
1222 chef-client. It will not invoke any other command via the push
1223 job. ONAP will include a callback URL in the push job request and a
1224 unique Request Id. An example push job posted by ONAP is listed
1227 .. code-block:: java
1230 "command": "chef-client"
1232 "nodes": ["node1.vnf_a.onap.com", "node2.vnf_a.onap.com"]
1234 "RequestId":"8279-abcd-aksdj-19231"
1235 "CallbackUrl":"<callback>"
1240 5. If CallbackCapable field in the template is not present or set to
1241 "False" ONAP will poll the Chef Server to check completion status of
1244 6. If "GetOutputFlag" is set to "True" in the template and
1245 CallbackCapable is not set to "True", ONAP will retrieve any output
1246 from each node where the push job has finished by accessing the Node
1247 Object attribute node['PushJobOutput'].
1249 .. _ansible_playbook_requirements:
1251 Ansible Standards and Capabilities
1252 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1254 ONAP will support configuration of xNFs via Ansible subject to the
1255 requirements and guidelines defined in this section.
1257 Ansible allows agentless management of xNFs/VMs/VNFCs via execution
1258 of 'playbooks' over ssh. The 'playbooks' are a structured set of
1259 tasks which contain all the necessary resources and execution capabilities
1260 to take the necessary action on one or more target VMs (and/or VNFCs)
1261 of the VNF. ONAP will utilize the framework of an Ansible Server that
1262 will host all Ansible artifacts and run playbooks to manage xNFs that support
1265 xNF Configuration via Ansible Requirements
1266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1268 Ansible Client Requirements
1269 +++++++++++++++++++++++++++++
1276 :updated: casablanca
1278 The xNF **MUST** have routable management IP addresses or FQDNs that
1279 are reachable via the Ansible Server for the endpoints (VMs) of a
1280 xNF that playbooks will target. ONAP will initiate requests to the
1281 Ansible Server for invocation of playbooks against these end
1289 The xNF **MUST** have Python >= 2.6 on the endpoint VM(s)
1290 of a xNF on which an Ansible playbook will be executed.
1296 :updated: casablanca
1298 The xNF **MUST** support SSH and allow SSH access by the
1299 Ansible server to the endpoint VM(s) and comply with the Network
1300 Cloud Service Provider guidelines for authentication and access.
1306 :updated: casablanca
1308 The xNF **MUST** load the Ansible Server SSH public key onto xNF
1309 VM(s) /root/.ssh/authorized_keys as part of instantiation. Alternative,
1310 is for Ansible Server SSH public key to be loaded onto xNF VM(s) under
1311 /home/<Mechanized user ID>/.ssh/authorized_keys as part of instantiation,
1312 when a Mechanized user ID is created during instantiation, and Configure
1313 and all playbooks are designed to use a mechanized user ID only for
1314 authentication (never using root authentication during Configure playbook
1315 run). This will allow the Ansible Server to authenticate to perform
1316 post-instantiation configuration without manual intervention and without
1317 requiring specific xNF login IDs and passwords.
1319 *CAUTION*: For xNFs configured using Ansible, to eliminate the need
1320 for manual steps, post-instantiation and pre-configuration, to
1321 upload of SSH public keys, SSH public keys loaded during (heat)
1322 instantiation shall be preserved and not removed by (heat) embedded
1329 :updated: casablanca
1331 The xNF **MUST** include as part of post-instantiation configuration
1332 done by Ansible Playbooks the removal/update of the SSH public key from
1333 /root/.ssh/authorized_keys, and update of SSH keys loaded through
1334 instantiation to support Ansible. This may include creating Mechanized user
1335 ID(s) used by the Ansible Server(s) on VNF VM(s) and uploading and
1336 installing new SSH keys used by the mechanized use ID(s).
1342 :introduced: casablanca
1344 The xNF **MUST** permit authentication, using root account, only right
1345 after instantiation and until post-instantiation configuration is
1352 :introduced: casablanca
1354 The xNF **MUST** provide the ability to remove root access once
1355 post-instantiation configuration (Configure) is completed.
1361 :updated: casablanca
1363 The xNF **MUST** update the Ansible Server and other entities
1364 storing and using the SSH keys for authentication when the SSH
1365 keys used by Ansible are regenerated/updated.
1367 **Note**: Ansible Server itself may be used to upload new SSH public
1368 keys onto supported xNFs.
1374 :introduced: casablanca
1376 The xNF **MUST** provide the ability to include a "from=" clause in SSH
1377 public keys associated with mechanized user IDs created for an Ansible
1378 Server cluster to use for xNF VM authentication.
1384 :introduced: casablanca
1386 The xNF **MUST** define the "from=" clause to provide the list of IP
1387 addresses of the Ansible Servers in the Cluster, separated by coma, to
1388 restrict use of the SSH key pair to elements that are part of the Ansible
1389 Cluster owner of the issued and assigned mechanized user ID.
1395 :introduced: casablanca
1397 The xNF **MUST** provide Ansible playbooks that are designed to run using
1398 an inventory hosts file in a supported format with only IP addresses or
1399 IP addresses and VM/xNF names.
1405 :introduced: casablanca
1407 The xNF **MUST** provide Ansible playbooks that are designed to run using
1408 an inventory hosts file in a supported format; with group names matching
1409 VNFC 3-character string adding "vip" for groups with virtual IP addresses
1410 shared by multiple VMs as seen in examples provided in Appendix.
1416 :introduced: casablanca
1418 The xNF **MUST** provide Ansible playbooks that are designed to run using
1419 an inventory hosts file in a supported format; with site group that shall
1420 be used to add site specific configurations to the target xNF VM(s) as
1423 Ansible Playbook Requirements
1424 +++++++++++++++++++++++++++++++
1426 An Ansible playbook is a collection of tasks that is executed on the
1427 Ansible server (local host) and/or the target VM (s) in order to
1428 complete the desired action.
1434 :introduced: casablanca
1436 The xNF **MUST** support Ansible playbooks that are compatible with
1437 Ansible version 2.6 or later.
1444 The xNF **MUST** make available playbooks that conform
1445 to the ONAP requirement.
1451 :updated: casablanca
1453 The xNF **MUST** support each APPC/SDN-C xNF action
1454 by invocation of **one** playbook [#7.3.4]_. The playbook will be responsible
1455 for executing all necessary tasks (as well as calling other playbooks)
1456 to complete the request.
1463 The xNF **MUST NOT** use any instance specific parameters
1470 :updated: casablanca
1472 The xNF **MUST** utilize information from key value pairs that will be
1473 provided by the Ansible Server as "extra-vars" during invocation to
1474 execute the desired xNF action. The "extra-vars" attribute-value pairs
1475 are passed to the Ansible Server by an APPC/SDN-C as part of the
1476 Rest API request. If the playbook requires files, they must also be
1477 supplied using the methodology detailed in the Ansible Server API, unless
1478 they are bundled with playbooks, example, generic templates. Any files
1479 containing instance specific info (attribute-value pairs), not obtainable
1480 from any ONAP inventory databases or other sources, referenced and used an
1481 input by playbooks, shall be provisioned (and distributed) in advance of
1482 use, e.g., xNF instantiation. Recommendation is to avoid these instance
1483 specific, manually created in advance of instantiation, files.
1485 The Ansible Server will determine if a playbook invoked to execute an
1486 xNF action finished successfully or not using the "PLAY_RECAP" summary
1487 in Ansible log. The playbook will be considered to successfully finish
1488 only if the "PLAY RECAP" section at the end of playbook execution output
1489 has no unreachable hosts and no failed tasks. Otherwise, the playbook
1490 will be considered to have failed.
1498 The xNF **MUST** use playbooks designed to allow Ansible
1499 Server to infer failure or success based on the "PLAY_RECAP" capability.
1501 **Note**: There are cases where playbooks need to interpret results
1502 of a task and then determine success or failure and return result
1503 accordingly (failure for failed tasks).
1509 :updated: casablanca
1511 The xNF **MUST** write to a response file in JSON format that will be
1512 retrieved and made available by the Ansible Server if, as part of a xNF
1513 action (e.g., audit), a playbook is required to return any xNF
1514 information/response. The text files must be written in the main playbook
1515 home directory, in JSON format. The JSON file must be created for the xNF
1516 with the name '<xNF name>_results.txt'. All playbook output results, for
1517 all xNF VMs, to be provided as a response to the request, must be written
1518 to this response file.
1524 :updated: casablanca
1526 The xNF **SHOULD** use playbooks that are designed to
1527 automatically 'rollback' to the original state in case of any errors
1528 for actions that change state of the xNF (e.g., configure).
1530 **Note**: In case rollback at the playbook level is not supported or
1531 possible, the xNF provider shall provide alternative rollback
1532 mechanism (e.g., for a small xNF the rollback mechanism may rely
1533 on workflow to terminate and re-instantiate VNF VMs and then re-run
1534 playbook(s)). Backing up updated files is also recommended to support
1535 rollback when soft rollback is feasible.
1540 :keyword: SHOULD NOT
1541 :updated: casablanca
1543 The xNF **SHOULD NOT** use playbooks that make requests to
1544 Cloud resources e.g. Openstack (nova, neutron, glance, heat, etc.);
1545 therefore, there is no use for Cloud specific variables like Openstack
1546 UUIDs in Ansible Playbook related artifacts.
1548 **Rationale**: Flows that require interactions with Cloud services e.g.
1549 Openstack shall rely on workflows run by an Orchestrator
1550 (Change Management) or other capability (such as a control loop or
1551 Operations GUI) outside Ansible Server which can be executed by a
1552 APPC/SDN-C. There are policies, as part of Control Loop
1553 models, that send remediation action requests to an APPC/SDN-C; these
1554 are triggered as a response to an event or correlated events published
1561 :updated: casablanca
1563 The xNF **SHOULD** use available backup capabilities to save a
1564 copy of configuration files before implementing changes to support
1565 operations such as backing out of software upgrades, configuration
1566 changes or other work as this will help backing out of configuration
1567 changes when needed.
1573 :updated: casablanca
1575 The xNF **MUST** return control from Ansible Playbooks only after all
1576 tasks performed by playbook are fully complete, signaling that the
1577 playbook completed all tasks. When starting services, return control
1578 only after all services are up. This is critical for workflows where
1579 the next steps are dependent on prior tasks being fully completed.
1583 ``StopApplication Playbook`` – StopApplication Playbook shall return control
1584 and a completion status response only after xNF application is fully stopped,
1585 all processes/services stopped.
1587 ``StartApplication Playbook`` – StartApplication Playbook shall return control
1588 and a completion status only after all xNF application services are fully up,
1589 all processes/services started and ready to provide services.
1591 **NOTE**: Start Playbook should not be declared complete/done after starting
1592 one or several processes that start the other processes.
1594 HealthCheck Playbook:
1596 SUCCESS – HealthCheck success shall be returned (return code 0) by a
1597 Playbook or Cookbook only when xNF is 100% healthy, ready to take requests
1598 and provide services, with all xNF required capabilities ready to provide
1599 services and with all active and standby resources fully ready with no
1600 open MINOR, MAJOR or CRITICAL alarms.
1602 NOTE: In some cases, a switch may need to be turned on, but a xNF
1603 reported as healthy, should be ready to take service requests or be
1604 already processing service requests successfully.
1606 A successful execution of a health-check playbook shall create one response
1607 file (per xNF) in JSON format, named after the xNF instance, followed by
1608 "_results.txt" (<xNF instance name>_results.txt) to be provided as a response
1609 to the requestor, indicating health-check was executed and completed
1610 successfully, example: vfdb9904v_results.txt, with the following contents:
1612 .. code-block:: java
1615 "identifier": "VNF",
1617 "time": "2018-03-16:1139"
1622 .. code-block:: java
1624 $ cat vfdb9904v_results.txt
1626 "identifier": "VNF",
1628 "time": "2018-03-16:1139"
1632 **NOTE**: See section 7.3.1.4 for comments on support of partial health checks.
1634 FAILURE – A health check playbook shall return a non-zero return code in
1635 case xNF is not 100% healthy because one or more xNF application processes
1636 are stopped or not ready to take service requests or because critical or
1637 non-critical resources are not ready or because there are open MINOR, MAJOR
1638 or CRITICAL traps/alarms or because there are issues with the xNF that
1639 need attention even if they do not impact services provided by the xNF.
1641 A failed health-check playbook shall also create one file (per xNF), in
1642 JSON format, named after the xNF instance name, followed by "_results.txt"
1643 to indicate health-check was executed and found issues in the health of
1644 the xNF. This is to differentiate from failure to run health-check playbook
1645 or playbook tasks to verify the health of the xNF,
1646 example: vfdb9904v_results.txt, with the following contents:
1648 .. code-block:: java
1651 "identifier": "VNF",
1652 "state": "unhealthy",
1653 "info": "Error in following VM(s). Check hcstatus files
1654 under /tmp/ccfx9901v for details",
1659 "time": "2018-03-16:4044"
1665 .. code-block:: java
1667 $ cat vfdb9904v_results.txt
1669 "identifier": "VNF",
1670 "state": "unhealthy",
1671 "info": "Error in following VM(s). Check hcstatus files
1672 under /tmp/ccfx9901v for details",
1677 "time": "2018-03-16:4044"
1681 See `xNF REST APIs`_ for additional details on HealthCheck.
1683 Some xNFs may support and desire to run partial health checks and receive
1684 a successful response when partial health check completes without errors.
1685 The parameter name used by HealthCheck playbook to request non-default
1686 partial health check is healthcheck_type. Example of health check types
1687 could be healthcheck_type=GuestOS, healthcheck_type=noDB,
1688 healthcheck_type=noConnections, healthcheck_type=IgnoreAlarms, etc.. This
1689 attribute-value pair may be passed by Orchestrator or Workflow or other
1690 (northbound) APPC/SDN-C clients to APPC/SDN-C as part of the request.
1692 By default, when no argument/parameter is passed, healthcheck playbook
1693 performs a full xNF health check.
1699 :introduced: casablanca
1701 The xNF provider **MUST** deliver a new set of playbooks that includes
1702 all updated and unchanged playbooks for any new revision to an existing
1709 :updated: casablanca
1710 :introduced: casablanca
1712 The xNF provider **MUST** assign a new point release to the updated
1713 playbook set. The functionality of a new playbook set must be tested before
1714 it is deployed to the production.
1718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1720 This section outlines the workflow that APPC/SDN-C invokes when
1721 it receives an action request against an Ansible managed xNF.
1723 #. When APPC/SDN-C receives a request for an action for an
1724 Ansible managed xNF, it retrieves the corresponding template (based
1725 on **action** and **xNF Type**) from its database and sets necessary
1726 values (such as an Id, NodeList, and EnvParameters) from either
1727 information either in the request or data obtained from other sources,
1728 inventory database, is an example of such sources.
1729 This is referred to as the payload that is sent as a JSON object
1730 to the Ansible server as part of the Rest API request.
1731 #. The APPC/SDN-C sends a request to the Ansible server to
1733 #. The APPC/SDN-C, after sending a request to the Ansible server,
1734 polls it to get results(success or failure). The APPC/SDN-C has a
1735 timeout value which is contained in the action request template. Different
1736 actions can set different timeout values (default setting is 600 seconds).
1737 If the result is not available when the timeout is reached, the APPC/SDN-C
1738 stops polling and returns a timeout error to the requester.
1739 The Ansible Server continues to process the request.
1742 Support of APPC/SDN-C Commands And Southbound Protocols
1743 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1745 The following table summarizes the commands and possible protocols selected.
1746 Note that the HealthCheck can also be supported via REST.
1748 Table 8. APPC/SDN-C APIs and NETCONF Commands
1750 +-------------+--------------------+--------------------+--------------------+
1751 |**Command** |**NETCONF Support** |**Chef Support** |**Ansible** |
1752 +=============+====================+====================+====================+
1753 |General |For each RPC, the |xNF Vendor must |VNF Vendor must |
1754 |Comments |appropriate RPC |provide any |provide an Ansible |
1755 | |operation is listed.|necessary roles, |playbook to retrieve|
1756 | | |cookbooks, recipes |the running |
1757 | | |to retrieve the |configuration from a|
1758 | | |running |VNF and place the |
1759 | | |configuration from |output on the |
1760 | | |a xNF and place it |Ansible server in |
1761 | | |in the respective |a manner aligned |
1762 | | |Node Objects |with playbook |
1763 | | |'PushJobOutput' |requirements listed |
1764 | | |attribute of all |in this document. |
1765 | | |nodes in NodeList | |
1766 | | |when triggered |The PlaybookName |
1767 | | |by a chef-client |must be provided |
1768 | | |run. |in the JSON file. |
1770 | | |The JSON file for |NodeList must list |
1771 | | |this xNF action is |IP addresses or DNS |
1772 | | |required to set |supported FQDNs of |
1773 | | |"PushJobFlag" to |an example VNF |
1774 | | |"True" and |on which to |
1775 | | |"GetOutputFlag" to |execute playbook. |
1776 | | |"True". The "Node" | |
1777 | | |JSON dictionary | |
1778 | | |must have the run | |
1779 | | |list populated | |
1780 | | |with the necessary | |
1781 | | |sequence of roles, | |
1782 | | |cookbooks, recipes. | |
1784 | | |The Environment | |
1785 | | |and Node values | |
1786 | | |should contain all | |
1787 | | |appropriate | |
1788 | | |configuration | |
1789 | | |attributes. | |
1791 | | |NodeList must | |
1792 | | |list sample FQDNs | |
1793 | | |that are required to| |
1795 | | |chef-client run for | |
1796 | | |this VNF Action. | |
1797 +-------------+--------------------+--------------------+--------------------+
1798 |Audit |The <get-config> is |Supported via a |Supported via a |
1799 | |used to return the |cookbook that |playbook that |
1800 | |running |returns the running |returns the running |
1801 | |configuration. |configuration. |configuration. |
1802 +-------------+--------------------+--------------------+--------------------+
1803 |Configure, |The <edit-config> |Supported via a |Supported via a |
1804 |ModifyConfig |operation loads all |cookbook that |playbook that |
1805 | |or part of a |updates the xNF |updates the VNF |
1806 | |specified data set |configuration. |configuration. |
1807 | |to the specified | | |
1808 | |target database. If | | |
1809 | |there is no | | |
1810 | |<candidate/> | | |
1811 | |database, then the | | |
1812 | |target is the | | |
1813 | |<running/> database.| | |
1814 | |A <commit> follows. | | |
1815 +-------------+--------------------+--------------------+--------------------+
1816 |Other |This command has no |Supported via a |Supported via a |
1817 |Configuration|existing NETCONF RPC|cookbook that |playbook that |
1818 |Commands |action. |performs |performs |
1819 | | |the action. |the action. |
1820 +-------------+--------------------+--------------------+--------------------+
1821 |Lifecycle |This command has no |Supported via a |Supported via a |
1822 |Management |existing NETCONF RPC|cookbook that |playbook that |
1823 |Commands |action. |performs |performs |
1824 | | |the action. |the action. |
1825 +-------------+--------------------+--------------------+--------------------+
1826 |Health Check |This command has no |Supported via a |Supported |
1827 | |existing NETCONF RPC|cookbook |via a |
1828 | |action. |that |playbook |
1829 | | |performs |that |
1830 | | |a HealthCheck and |performs |
1831 | | |returns the results.|the |
1832 | | | |HealthCheck |
1833 | | | |and returns |
1836 +-------------+--------------------+--------------------+--------------------+
1839 https://github.com/mbj4668/pyang
1842 Recall that the Node Object **is required** to be identical across
1843 all VMs of a xNF invoked as part of the action except for the "name".
1846 Upstream elements must provide the appropriate FQDN in the request to
1847 ONAP for the desired action.
1850 Multiple ONAP actions may map to one playbook.
Code Review / vnfrqts / requirements.git / blob