This wiki provides documentation regarding the design, capabilities and usage of the Saltstack Extension for APP-C. Saltstack is a an open-source config management tool that can be used in VNF management framework that allows provide an almost cli like set of tools in a structured form. Here Saltstack Server is called as salt master and clients are called as salt minions which run as agents in the client machine, Salt uses YAML config files, organized into templates or packages called states. In the target VNF it is necessary to have a) an SSH server, b) salt minions and dependencies and d) any necessary software that is specific to the VNF to run its functions. Many actions such as configure, restart, health check can be executed on the VNF by constructing a salt-states (set of sls files) that is executed by an Saltstack server on the VNF via SSH.
The Saltstack Extension for APP-C allows management of VNFs that support Saltstack through the following two additions :
- Saltstack Directed Graph : The Saltstack Directed graph is generic DG that can be used to invoke salt-states via Saltstack (and hence any APP-C action, VNF actions map to salt-states) corresponding to an LCM action.
- An APP-C Saltstack adapter : The Saltstack adapter is an OSGI bundle in the APP-C Karaf container that interacts with the Saltstack Server . It is essentially a set of SSH calls that performs two actions, submit job request for a salt-states to be executed, and get the results of the execution (in synchronous mode).
Details of each of these two aspects are listed below :
1. Saltstack Directed Graph (DG):
Field | Value |
|---|---|
| module | APPC |
| rpc | saltstack-adapter-1.0 |
| version | 1.0.0 |
The inputs that the saltstack DG expects in DG context memory are listed below.
| Table 1: Input Parameters to the Saltstack Directed Graph | |||
|---|---|---|---|
| Variable Name | Description | Type | Comments |
| User | Saltstack server's SSH UserName. | Mandatory | Should be provided by App-C |
| Password | Saltstack server's SSH Password. | Mandatory | Should be provided by App-C |
| HostName | Saltstack server's host name IP address. to post the request for execution and retrieve results (in synchronous mode) | Mandatory | Should be provided by App-C |
| Port | Saltstack server's port to make SSH connection to. | Optional | Should be provided by App-C |
| withRetry | Specify 'true' if you wanna connect to server with retry. | Optional | |
| SlsName | Name of the SLS file (if SlsExec is true) | Mandatory | To be provided to App-C during Run-Time |
| Timeout | Time Saltstack Server should wait before terminating session. Set large timeout if your SLS file will take large time to finish executing (in sec) | Optional | To be provided to App-C during Run-Time |
| NodeList | Set name of VNFC (in salstack context minions) you want to execute the SLS file onto. If not specified, then this exec will be onto all VNFs managed by saltstack server. | Optional | To be provided to App-C during Run-Time |
| EnvParameters | A JSON dictionary (stringified) listing the parameters to be passed to the Saltstack playbook | Optional | A JSON dictionary which should list key value pairs to be passed to the Salstack command to run SLS. These values would correspond to instance specific parameters that a playbook may need to execute an action. |
| FileParameters | A JSON dictionary (stringified) listing file names and files to be created for Saltstack playbook | Optional | A JSON dictionary where keys are filenames and values are contents of files. The Saltstack Server will utilize this feature to generate files with keys as filenames and values as content. This attribute can be used to generate files that a SSL file may require as part of execution |
The 'template' referred in the above table must be a JSON file and must contain the key-value pairs listed above (that are expected to be in the template). An LCM API Directed graph should fill in necessary parameters in the template, and then put the key-value pairs from the template as listed above in DG context memory before calling the Saltstack DG,
Upon completion the Saltstack DG sets the following variables in DG context memory for success/failure notification.
| Table 2: Output Variables set by Ansible DG | |
|---|---|
| Variable Name | Description |
| output.status.code | Result of the request : 400 if SUCCESS , 200 if FAILURE. The ansible playbook may have multiple sub-tasks, playbooks etc and may run on multiple VMs of a host. The request is considered to fail if even one of the tasks is incomplete. |
| output.status.message | If Salt finished execution, set to corresponding message. If abnormal error, reported in message |
| output.status.results | A JSON dictionary with results corresponding to Saltstack execution.. |
2. APP-C Ansible Adapter : The App-C Ansible Adapter is an OSGI bundle which essentially makes REST calls to the Ansible Server. It exposes three methods that can be invoked by the Service Logic Interpreter (SLI) via Directed Graphs
- void reqExecSLS(Map<String, String> params, SvcLogicContext ctx) throws SvcLogicException :
Method to execute a single sls on SaltState server (Where the SLS file already located on the server). The command entered will only be the SLS file name and the output will be in JSON format automatically. The response from Saltstack comes in json format and it is automatically put to context for DGs access, with a certain request-ID as prefix. If request Id (Id) is not passed as part of input param, then a random Id will be generated and put to properties in "org.onap.appc.adapter.saltstack.Id" field. All the output message from the execution will be appended with reqId.
- void reqExecCommand(Map<String, String> params, SvcLogicContext ctx) throws SvcLogicException :
- Method to execute a single command on SaltState server ( can also execute a SLS file located on the server). For the adaptor to parse the response, the command entered should request the output in JSON format, this can be done by appending json-out outputter as specified in https://docs.saltstack.com/en/latest/ref/output/all/salt.output.json_out.html#module-salt.output.json_out and https://docs.saltstack.com/en/2017.7/ref/cli/salt-call.html . The response from Saltstack comes in json format and it is automatically put to context for DGs access, with a certain request-ID as prefix. If Id is not passed as part of input param, then a random Id will be generated and put to properties in "org.onap.appc.adapter.saltstack.Id" field. All the output message from the execution will be appended with reqId. Example, execute a single command on SaltState server :
- Command to test if all VNFC are running e.g."salt '*' test.ping --out=json --static".
- void reqExecSLSFile(Map<String, String> params, SvcLogicContext ctx) throws SvcLogicException : A method to retreive the logs from a request (not used in the Ansible DG currently).
Method to execute a single sls on SaltState server (Where the SLS file is located in the adaptor). The param entered will only be the SLS file location on the APPC/ODL container and this is automatically uploaded to server and executed, where the output from server will be in JSON format automatically. The response from Saltstack comes in json format and it is automatically put to context for DGs access, with a certain request-ID as prefix. If request Id (Id) is not passed as part of input param, then a random Id will be generated and put to properties in "org.onap.appc.adapter.saltstack.Id" field. All the output message from the execution will be appended with reqId.
Currently, the "Input Parameters to the Saltstack Directed Graph" defined above is only for reqExecSLS method. DG for using all the methods will be provided, as depicted in the image above.
In order to communicate with the Ansible Server, it is currently assumed that :
a. Credentials comprise of a username and password.
b. Communication is over SSH