API Doc / Server Specs

ONAP Ansible Server Specifications

This document outlines the specifications for an ONAP compliant Ansible Server. The Ansible Server will be used as a repository to store Ansible playbooks as well as an execution engine which upon a REST API request, will execute Ansible playbooks against VNFs.

Ansible Server Scope

1. The Ansible Server is required to support storage and execution of playbooks that are in .yaml format or a collection of playbooks compressed and uploaded in tar-ball format.
2. The Ansible Server must accept requests for execution of playbooks via a REST interface. The scope of each request will involve exactly one action against one VNF and will request execution of one playbook.
3. The playbook executed by the Ansible Server will be responsible for execution of the entire action against the VNF (e.g calling other playbooks, running tasks on multiple VMs in the VNF etc) and return back the status of the action as well as any necessary output in its entirety after the action is finished.
4. The Ansible Server must support simultaneous execution of multiple playbooks against different VNFs in parallel (i.e process multiple requests).
5. The Ansible Server will be loaded with all necessary credentials to invoke playbooks against target VNFs.

Ansible Server/ONAP Interface

The Ansible Server is required to support the following set of  APIs :

1. Load Playbook: The Ansible Server must expose an authenticated interface to allow loading all necessary playbooks for a target VNF. It should impose an identification mechanism that allows each playbook to be uniquely identified.
   1. It is recommended that the Load Playbook API be a REST API.
2. Request API: The Ansible Server must expose a REST endpoint that accepts a POST message to request execution of the playbook  (e.g https://ansible.example.com:8080). The POST request must be a JSON block as outlined in Table 1.

Table 1: Request Message

When the Ansible server accepts an authenticated request to execute a playbook, it is required to send back an initial response indicating whether the request is accepted or rejected. The response must be a JSON Object with the following key value pairs:

Table 2: Initial Response Message

3. Result API: If the Ansible Server accepts a request to execute a playbook,  it must  make available status of the execution of the playbook at a Results REST endpoint indexed by the Id in the request in the form <url>?Id=<RequestId>&Type=GetResult   where <url> is the URL used for submitting requests.  For example: https://ansible.example.com?Id=10&Type=GetResult. 

When a GET is invoked against the Results REST endpoint, the Ansible Server must reply with an appropriate response:

1. If the Endpoint is invalid (no request, or request expired), reply with a standard HTTP 404 error.
2. If the playbook execution is still ongoing, then the Ansible Server is required to block on the GET request till the execution finishes or terminates.
3. Upon completion of execution, the Ansible Server is required to response to the GET request with the result of the playbook execution in the form of a JSON message as outlined in the Table 2.

Table 3: FinalResponse Message

The dictionary associated with the ‘Results’ key in the Result Response must be a key-value pair where each key corresponds to an entry in the NodeList and the value is a dictionary with the format as outlined in Table 4.

Table 4: Results block format

Ansible Server Actions:

The Ansible Server must take the following actions when triggered by a request to execute a playbook:

1. Determine if the request is valid, and if so, must send back an initial response message accepting the request.
2. If the request contains a “FileParameters” key that is not NULL, create all the necessary files.
3. Invoke the ansible playbook while providing it all appropriate parameters listed in EnvParameters and inventory information listed in NodeList.  The playbook will be responsible for execution of all necessary steps required by the VNF action.
4. If the playbook finishes, use the PLAY_RECAP functionality to determine whether playbook finished successfully on each endpoint identified in the NodeList.
5. If the playbook finishes, collect any output returned by the playbook. A playbook conforming to the ONAP vendor requirements document will write out any necessary output to  a file named ‘<hostname>_results.txt’ in the working directory, where ‘hostname’ is an element of the NodeList where the playbook is being executed.
6. If the playbook execution exceeds the Timeout value, the playbook execution process is terminated and ansible log that captures the last task executed is stored.
7. Make results available on the Results REST Endpoint as documented in Table 2.
8. If Callback url was provided in initial request, post the final response message on the Callback URL along with an additional key additional key 
   “Id “ : which corresponds to the request Id sent in the request

Ansible  Server Result Storage Requirements

The Ansible Server must cache and provide results of an exection as well as retain logs for debugging purposes as outlined below:

1. The results from a playbook execution result must be retained by the Ansible Server and made available through the respective REST endpoint for a duration that is configurable.
   1. Recommended duration is 2 x Timeout
2. The log from a playbook must be stored by the Ansible Server, tagged with the Id along with all other parameters in the initial request in a format that allows for examination for debugging purposes.

Some Illustrative Examples

1. An example POST for requesting execution of a Playbook :
   1. {"Id": "10", “Action”:”HealthCheck”, "PlaybookName": "ansible_getresource.yml", "NodeList": ["interface1.vnf_b.onap.com", ["interface2.vnf_b.onap.com"], "Timeout": 60, "EnvParameters": {"Retry": 3, "Wait": 5}}
      
      
2. Potential examples of Ansible Server  initial response.
   1. Successfully accepted request :
      1. {"StatusCode": "100", "ExpectedDuration": "60sec", "StatusMessage": "PENDING"}
   2. Request rejected :
      1. {"StatusCode": "101", "StatusMessage": "PLAYBOOK NOT FOUND "}
         
         
3. Potential examples  of final response by Ansible Server  to a GET on https://<server-url>:port/?Id=10&Type=GetResult
   1. Playbook successful execution:
      1. {"Duration": "4.864815sec",  “StatusCode”: 200, “StatusMessage”:”FINISHED”, "Results": {"interface_1.vnf_b.onap.com": {"StatusCode": "200", "GroupName": "vnf-x-oam", "StatusMessage": "SUCCESS", “Output”:{“CPU”:30, “Memory”:”5Gb”},  "interface_1.vnf_b.onap.com": {"StatusCode": "200", "GroupName": "vnf-x-oam", "StatusMessage": "SUCCESS", “Output”:{“CPU”:60, “Memory”:”10Gb”}}}
   2. Playbook  failed execution  on one of the hosts:
      1. {"Duration": "10.8sec",  “StatusCode”: 200, “StatusMessage”:”FINISHED”, "Results": {"interface_1.vnf_b.onap.com": {"StatusCode": "500", "GroupName": "vnf-x-oam", "StatusMessage": "Error executing command ",  "interface_1.vnf_b.onap.com": {"StatusCode": "200", "GroupName": "vnf-x-oam", "StatusMessage": "SUCCESS", “Output”:{“CPU”:60, “Memory”:”10Gb”}}}
   3. Playbook terminated
      1. {"Duration": "61",  “StatusCode”: 500, “StatusMessage”:”TERMINATED” }