From: Scott Seabolt Date: Tue, 24 Oct 2017 13:12:13 +0000 (-0400) Subject: Added APPC User Guide X-Git-Tag: v1.2.0~20 X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F59%2F20359%2F1;p=appc.git Added APPC User Guide Added the APPC User Guide Identity-Id: APPC-103 Change-Id: I91b24ff47c2d7a670728b4c67147db5d9bf7d1d1 Signed-off-by: Scott Seabolt --- diff --git a/docs/APPC User Guide/APPC User Guide.rst b/docs/APPC User Guide/APPC User Guide.rst new file mode 100644 index 000000000..e94951581 --- /dev/null +++ b/docs/APPC User Guide/APPC User Guide.rst @@ -0,0 +1,1277 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +======================================== +Application Controller (APPC) User Guide +======================================== + +APPC Overview and Architecture +============================== +The Application Controller (APPC) is one of the components of the ONAP +platform. It is responsible for handling the Life Cycle Management (LCM) +of Virtual Network Functions (VNFs). + +This document provides an overview of the APPC components that enable +the LCM operations. + +Implementation +-------------- +The APPC infrastructure is implemented on virtual machines in an +OpenStack cloud in the Amsterdam release. APPC is created on top of the OpenDaylight (ODL) +platform + +The following diagram represents a non-redundant APP-C deployment. + +|image0| + +Features +-------- +The APPC HTTP API supports Life Cycle Management (LCM) commands, +allowing users to manage virtual applications and their components via +other ONAP components. Refer to Architecture section for further +details. + +Interface +--------- +The Application Controller Dashboard interacts with the controller +using REST APIs and performs actions on VNF/VNFC/VMs, such as snapshot, +lock, sync, and health-check. + +Dashboard +~~~~~~~~~ + +To open the Application Controller dashboard, go to: + +|image1| + +Navigate to the available LCM commands by clicking on + **appc-provider-lcm**: + +|image2| + +Click on the URI of the desired action to open a frame with information +about the action and an option to try it out. For example, to send the +action, add the request body as the input parameter value, and click +**Try it out!** + +The following figure shows an example body of a LCM restart request: + +|image3| + +If the request is accepted, you should see the following response: + +|image4| + +APPC Architecture +----------------- + +This section discusses the APPC internal components in detail. + +**APPC High Level Architecture** + +|image5| + +Northbound REST Layer +~~~~~~~~~~~~~~~~~~~~~ + +This layer is responsible for interfacing with APPC clients, such as SO +or SDC and others, exposing YANG-based API via REST HTTP and/or DMaaP +messaging (see the Interfaces Summary section for details). In addition, +it exposes APPC OAM (Operation Administration Management) APIs, enabling +ONAP Operations Manager (OOM) or TechOps portal to perform APPC +lifecycle operations + +APPC Provider +~~~~~~~~~~~~~ + +The APPC Provider module exposes the endpoints for each action +supported by APPC. This module uses the YANG model to define the +YANG Remote Processing Call (RPC) and data model, in other words, +the input and output parameters for each action. The Provider module +is responsible for validating the RPC input and for rejecting any +malformed input. After successful validation, the APPC Provider +calls the Dispatcher to continue the request processing. + +LCM API +~~~~~~~ + +The APPC exposes an HTTP API to support the Life Cycle Management +(LCM) commands sent from ONAP components such as SO, SDC, and the +Portal. These commands enable the components to request APPC to +perform actions such as to control, modify, start, or stop virtual +applications and/or their components.  + +A virtual application is composed of the following layers. A Life +Cycle Management command may affect any number of these layers. + +- Virtual Network Function (VNF) + +- Virtual Network Function Component (VNFC) + +- Virtual Machine (VM) + +APP-C supports two types of LCM requests, as described below. + +**Note:** For further information about LCM API, including details of +all the commands currently supported in APP-C and examples of the +request and response format see the ONAP Application Controller (APPC) API Guide.  + +LCM over REST +^^^^^^^^^^^^^^ + +LCM command requests over REST are sent to the APPC using an HTTP +POST request. APPC returns one or more responses for each LCM +request.  + +The APP-C LCM API provides a POST HTTP API endpoint per command.  + +An **asynchronous** command, containing an authorized and valid +request, results in at least two discrete response events: + +- an ACCEPT (a synchronous HTTP response) to indicate that the request + is accepted and will be processed, and + +- a final asynchronous response for the command containing an execution + status is sent via DMaaP + +An unauthorized or invalid request would result in a single +ERROR response.  + +For commands such as Restart, Start, and Stop, the asynchronous response +is sent over DMaaP. + +A **synchronous** command, for example Lock or Unlock, results in a +single response, which is either SUCCESS or ERROR. For this type of +request, the first response is a synchronous HTTP response.. + +For this release, APPC supports the HTTPS protocol, whereas the plain +HTTP requests are blocked.. + +Endpoint format:  + +``://:/restconf/operations/appc-provider-lcm:`` + +LCM over Message Bus (DMaaP) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +APPC is capable of receiving LCM command requests as messages on the +DMaaP bus. In this case, APPC returns one or more responses for each LCM +request, similar to LCM over REST, while both are communicated over +DMaaP. + +Configure the Read/Write topics for the DMaaP as described in APPC +Deployment, APPC Available Properties. + +APPC client library, embedded into APPC client’s (for example, SO) code, +intends to simplify communication over DMaaP by eliminating topic +provisioning at the client site. Refer to +http://onap.readthedocs.io/en/latest/ for more details on the APPC +Client Library. + +For further information about the request and response format, see +the APPC API Guide at http://onap.readthedocs.io/en/latest/ + +Dispatcher +~~~~~~~~~~ + +The APPC Dispatcher component processes requests received by the Request +Handler from other ECOMP components. The Dispatcher checks the +conditions are sufficient for performing the request and selects the +correct Direct Graph (DG) workflow for execution or rejects the request. +When the DG execution is complete, the Dispatching function is +responsible for notifying the initiator of the operation with the +request execution result (Success/Error) and updates the VNF +Orchestration state in Active and Available Inventory (A&AI). + +The detailed responsibilities of the Dispatcher are as follows: + +- Upon receiving the operation request, the Dispatcher performs the + synchronous part of the execution: + + - Starts the operation's time-to-live countdown + + - Queries A&AI to get the VNF type and its current orchestration + state + + - Checks VNF\_type-specific rules in the LCM State machine for + whether to allow or reject the requested command execution + + - Allocates and initiates an appropriate DG workflow by invoking the + Service Logic Interpreter (SLI) framework to start the + asynchronous part of the execution + + - Returns a response to the initiator: OK or reject (for example, if + the State Machine blocks the operation, no DG or time-to-live, or + bad parameters) + + - If the operation is rejected, the Dispatcher generates an + appropriate Audit log for the Event and Error Logging Framework + (EELF) and the Local Event Journal + +- Upon workflow completion, the Dispatcher: + + - Receives the execution results from the DG from the SLI framework + + - Publishes the execution result over DMaaP (success or error) + + - Updates VNF status in A&AI + + - Generates an Audit log for EELF and Local Event Journal + +Request Handler +^^^^^^^^^^^^^^^ + +The Request Handler manages incoming requests and locks APPC for new +requests, as needed for operations with a specific command execution +sequences. + +Lifecycle Management +^^^^^^^^^^^^^^^^^^^^ + +The Lifecycle Management VNF State Machine enables the Dispatching +function to determine the validity of the requested operation (desired +state) as a function of the current VNF state, acquired from the A&AI. +The State Machine maintains its data (states and valid operations) +in-memory. At the point of APPC initialization, the State Machine +constructs a matrix based on the metadata of the current operation and +the valid desired state.  + +Command Executor +^^^^^^^^^^^^^^^^ + +Manages command execution queue. + +State Machine +~~~~~~~~~~~~~ + +The VNF State machine enables the Dispatching function to determine +the validity of the requested operation (desired state) as a +function of the current VNF state, acquired from the A&AI. The State +machine maintains its data (states and valid operations) in-memory. +At the point of APP-C initialization, the State Machine constructs a +matrix based on the metadata of the current operation and the valid +desired state.  + +The Service Logic Interpreter (SLI) Framework +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SLI framework is responsible for executing Directed Graphs (DGs). +The Dispatcher invokes the SLI framework to execute a specific DG, based +on the input action. The SLI executes the DG and the sub-DG and returns +a success or failure response to the caller along with the context +variables used to exchange data with the calling body (for example, the +Dispatcher). The caller can use the SLI context to specify data required +for DG execution. The DG returns the same context when execution +completes. + +Currently, there is a combination of input action specific and/or VNF +type specific DG’s as well as a DGOrchestrator DG which is action and +VNF type agnostic. The DGOrchestrator approach consists of the +following: + +- DGOrchestrator DG which: + + - Accepts request from the Dispatcher and converts it into DG + context format + + - Calls A&AI to retrieve the inventory for the VNF instance + + - Calls a Sequence Generator for start/stop actions which generates + a workflow sequence containing a set of start or stop VM requests + + - Auto-generates a workflow for other requests with a single step + + - Executes each step in the workflow by invoking DG’s to interact + with the VNF, OpenStack, or Ansible/Chef servers. These DG’s which + are specific to the protocol and possibly action. Some DG’s may + update A&AI (such as for Configure) or retrieve the VNF running + configuration. + + - Returns success/failure status to the Dispatcher. + +In the future, all action/VNF type specific DG’s will be migrated to the +DGOrchestrator approach. + +The following diagram shows the Amsterdam Release DGOrchestrator +architecture + + |image6| + +Westbound Layer +~~~~~~~~~~~~~~~ + +A&AI +^^^^ + + A&AI is an ONAP component, which maintains information about VNF + instances. APPC uses A&AI as a source of the true VNF status, + topology and operational data. In addition, at the end of each + operation, APPC updates the VNF changes that result from the + operation: for example, VNFC record(s) are added after + configuration. The VNF orchestration status is not updated for + read-only operations such as Sync or Audit. In the case of the VNF + Terminate operation, APPC removes the terminated VNF from A&AI by + deleting its Virtual Machines (VMs).  + + The Dispatching function and operation-specific DGs manage access to + the A&AI using the A&AI Adapter.   + +Southbound Layer +~~~~~~~~~~~~~~~~ + +Southbound VNF Adapters +^^^^^^^^^^^^^^^^^^^^^^^ + + APPC uses several adapters to communicate with VNFs. The Interface + as a Service (IAAS) adapter is part of the OpenDayLight (ODL) + platform, while other adapters have been added by the ONAP + development. + +Restconf Adapter +^^^^^^^^^^^^^^^^^ + + The Adapter is responsible for configuration tasks, using JSON + format, for VNFs supporting Restconf API. + +Netconf Adapter +^^^^^^^^^^^^^^^ + + The Adapter is responsible for configuration tasks, using XML + format, for VNFs supporting Netconf API. + +IAAS Adapter  +^^^^^^^^^^^^^ + + The IAAS Adapter connects APPC with the OpenStack controllers to + perform various operations on VMs and VNFs such as Restart, Migrate, + and Rebuild. The IAAS Adapter integrates as a DG plugin, while the + DGs call the services exposed by the adapter. + +SSH (XML/CLI) Adapter +^^^^^^^^^^^^^^^^^^^^^ + + A custom adapter that enables connection to a VNF using an SSH + session. It is designed to support CLI and XML protocols, including + Netconf. It is used to load configurations and retrieve the running + configuration. + +Chef Adaptor +^^^^^^^^^^^^ + + This adaptor incorporates a client for an external Chef server, + which connects to VNF NB APIs. The adaptor enables APPC to operate + cookbooks (Chef recipes) to perform various LCM operations over + VNFs, connected to the Chef server. + +Ansible Adapter +^^^^^^^^^^^^^^^ + + This adaptor incorporates a client for an external Ansible server, + which connects to VNF NB APIs. The adaptor enables APPC to operate + playbooks to perform various LCM operations over VNFs connected to + the Ansible server. + +Cross Cutting Components +~~~~~~~~~~~~~~~~~~~~~~~~ + +The Cross Cutting Component services operate across all APPC modules. + +Configuration +^^^^^^^^^^^^^ + +Used to configure operational parameters of APPC modules based on +function-specific configuration files, for example: + +- ``log4j.properties`` for the logging service + +- ``appc.properties`` for core APPC-related configuration + +- ``dblib.properties`` for managing APPC database-related configuration + +- ``aaiclient.properties`` for managing A&AI-related configuration + +KPI Service +^^^^^^^^^^^ + +This Cross Cutting component manages KPI measurement, storage and +reporting. + +Enable matrix logs to log the number of hits of the configured method of +APPC, by configuring the following properties in ``appc.properties:``:: + + metric.enabled= + schedule.policy.metric.start.time=