saltstack-adapter/README.md

   1 This source repository contains the code for the CCSDK plugins.
   2
   3 To compile this code:
   4
   5 1. Make sure your local Maven settings file ($HOME/.m2/settings.xml) contains references to the ONAP repositories and OpenDaylight repositories.  See example-settings.xml for an example.
   6
   7 2. To compile, run "mvn clean install".
   8
   9
  10 ***SaltStack Adaptor:*** CCSDK SLI ADAPTORS to support SaltStack server:
  11
  12 ***Connection from CCSDK SLI ADAPTOR Adaptor to SaltStack server:***
  13
  14 Create an Adaptor to communicate with the SaltStack server:
  15 1) SaltStack server doesn’t expose any REST API unlike Chef.
  16 2) SSH based communication with the SaltStack server, one command at a time (preferred). This will mean that SaltStack server should have it’s SSH enabled.
  17 3) Create a REST-wrap around SaltStack server like is done for Ansible server.
  18
  19 ***SSH based communication:***
  20 1) Adaptor can execute commands on the Salt Master and bring back the result and put to the context memory for DG based analysis. (https://docs.saltstack.com/en/latest/ref/modules/all/index.html#all-salt-modules).
  21 2) This can be useful for several reasons, for instance it might be useful to know the interfaces in the minions before executing certain network config based commands. This can simple be done by running, 'salt '*' network.interfaces' on server.
  22 3) SaltStack Server, Output module support: The json-out outputter can be used to display the return data in JSON format. So the DG can put this onto context memory for execution. https://docs.saltstack.com/en/latest/ref/output/all/index.html#all-salt-output
  23 4) Since the command execution on server might take time, a thread can be spawn to make a single SSH command execution in a SYNC manner. The thread executes the command and brings back the result and puts to the context memory for DG’s access.
  24 5) For some specific executions operations like configure and upgrade, each configuration execution on the server will be handled by 2 or more SSH command execution. (1 for sending configuration and another for verifying the result). This will give the DGs and Saltstack adaptor with more control on the SaltStack server.
  25
  26 ***SaltState (SLS) file for execution on the SaltStack server:***
  27  The desired SLS file can be executed by one of the following three ways:
  28 1) The SLS file for VNF configuration can be assumed to be already on the server, similar to Ansible. In this case, no addition requirements are necessary. We would already know the name of SLS file to execute so the configuration is performed on the VNF.
  29 2) SLS file creation using DG: Create a DG to parse the configuration and create an SLS file using adaptors such as FileRecorder. Then this SLS file can be passed to the adaptor, so the adaptor can send the configuration to server. The adaptor can also send a SLS file to the Saltstack server and then run the command to execute it.
  30 3) Third option is for the configuration SLS file that is to be sent to the VNF after instantiation is attached at the design time. This SLS formula- SaltStack file can be picked up and stored in the DB, as part of UEB listener. This can then be sent to adaptor using DGs.
  31
  32 ***Requirements and benefits of the chosen SSH method:***
  33 1) The SaltStack server should have it’s SSH enabled.
  34 2) Via ssh user account we should have the access to run saltstack command.
  35 3) Such execution method will give the DGs and adaptor with more refined control on the SaltStack server.
  36 ==================================================================================================================
  37
  38
  39 ***Defining Saltstack server properties:*** Can be done with 2 different methods.
  40 1) Saltstack server details are found in the property file named saltstack-adapter.properties. Param has to be given with following types.
  41     "org.onap.appc.adapter.saltstack.clientType"; -> Supported types are (BASIC || SSH_CERT || BOTH).
  42     "org.onap.appc.adapter.saltstack.host"; ->  Saltstack server's host name IP address.
  43     "org.onap.appc.adapter.saltstack.port"; ->  Saltstack server's port to make SSH connection to.
  44     "org.onap.appc.adapter.saltstack.userName"; ->  Saltstack server's SSH UserName.
  45     "org.onap.appc.adapter.saltstack.userPasswd"; ->  Saltstack server's SSH Password.
  46     "org.onap.appc.adapter.saltstack.sshKey"; ->  Saltstack server's SSH KEY file location.
  47 2) All the server related details can also be passed as param to the adaptor from the Directed Graphs. Param has to be given with following types.
  48     "HostName";  ->  Saltstack server's host name IP address.
  49     "Port"; ->  Saltstack server's port to make SSH connection to.
  50     "Password"; ->  Saltstack server's SSH UserName.
  51     "User"; ->  Saltstack server's SSH Password.
  52     "withRetry"; -> Specify 'true' if you wanna connect to server with retry.
  53   Note: SSH_CERT based Auth is not supported in this method.
  54
  55 ***Using Saltstack Adaptor Commands and params to pass in: reqExecCommand API:***
  56
  57 Method to execute a single command on SaltState server and execute a SLS file located on the server. 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
  58 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.
  59 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.
  60 1) Execute a single command on SaltState server : Example command will look like:
  61 1.1) Command to test if all VNFC are running: "salt '*' test.ping --out=json --static"
  62 1.2) To check Network interfaces on your minions: "salt '*' network.interfaces --out=json --static"
  63 1.3) Restart Minion service after upgrade process: "salt minion1 service.restart salt-minion --out=json --static"
  64 Note: If using --out=json, you will probably want --static as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use --static as well.
  65
  66 This "reqExecCommand" method gives the Operator/Directed Graphs to execute commands in a fine-tuned manner, which also means the operator/DG-creator should know what to expect as output as a result of command execution (for both success/failure case).
  67 By this way using DGs, the operator can check for success/failure of the executed comment.
  68 If the output is not in JSON format, then the adaptor still tries to convert it into properties, in addition, params that will hold the command execution result for DG access are (note: this is just to check if the command was executed successfully on the server, this doesn't check the status of the command on saltstack server):
  69 Result code at: org.onap.appc.adapter.saltstack.result.code (On success: This will be always be 250, means command execution was success but the result of the execution is unknown and is to be checked from ctx using DGs)
  70 Message at: org.onap.appc.adapter.saltstack.message
  71 Both user inputted/auto generated req Id at:  org.onap.appc.adapter.saltstack.Id
  72 To check the status of the command configuration on saltstack server: the user should exactly know what to look for in the context
  73 so the user can identify if the configuration execution on the saltstack server succeded or not.
  74 here for instance, in 1.1) the user should check if $reqId.<minion-name> is set to true in the context memory using DGs.
  75
  76 2) Execute a SLS file located on the server : Example command will look like:
  77 Knowing the saltstack server has vim.sls file located at "/srv/salt" directory then user can execute the following commands:
  78 1.1) Command to run the vim.sls file on saltstack server: Cmd = "salt '*' state.apply vim --out=json --static"
  79 1.2) Command to run the nettools.sls file on saltstack server: Cmd = "cd /srv/salt/; salt '*' state.apply <sls-file-name> --out=json --static"
  80 Important thing to note: If the reqExecCommand is used to execute sls file then along with following,
  81     "HostName";  ->  Saltstack server's host name IP address.
  82     "Port"; ->  Saltstack server's port to make SSH connection to.
  83     "Password"; ->  Saltstack server's SSH UserName.
  84     "User"; ->  Saltstack server's SSH Password.
  85 the param should contain,
  86     "SlsExec"; ->  this variable should be set to true.
  87     "Timeout"; -> set large timeout if your SLS file will take large time to finish executing (in Seconds).
  88
  89 In this case, params that will hold the command execution result for DG access in Key:
  90 Result code at: org.onap.appc.adapter.saltstack.result.code (On success: This will be 200, this means the command was executed successfully and also configuration change made using the SLS file was also successful)
  91 Message at: org.onap.appc.adapter.saltstack.message
  92 Both user inputted/auto generated req Id at:  org.onap.appc.adapter.saltstack.Id
  93 The result code here will be the execution of configuration SLS file on the server.
  94 NOTE: It would be better to use reqExecSLS, where you will only have to specify SLS file name on server to execute it.
  95
  96
  97 ***Using Saltstack Adaptor Commands and params to pass in: reqExecSLS API:***
  98
  99 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.
 100 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.
 101 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.
 102 1) Execute a single command on SaltState server : Example command will look like:
 103     In the context set the "SlsName" to "test.sls"
 104     In the context set the "Timeout"; -> set large timeout if your SLS file will take large time to finish executing (in Seconds).
 105     In the context set the "NodeList" to "minion1" //to the minions or VNFCs you want to apply the SLS file to.
 106     "NodeList" can be empty or set to "*" is the SLS has to be applied to all the minions or VNFCs.
 107     In the context set the "FileParameters: 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 (Optional).
 108     In the context set the "EnvParameters: 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.
 109
 110 In this case, params that will hold the command execution result for DG access in Key:
 111 Result code at: org.onap.appc.adapter.saltstack.result.code (On success: This will be 200, this means the command was executed successfully and also configuration change made using the SLS file was also successful)
 112 Message at: org.onap.appc.adapter.saltstack.message
 113 Both user inputted/auto generated req Id at:  org.onap.appc.adapter.saltstack.Id
 114 The result code here will be the execution of configuration SLS file on the server.
 115
 116 ***Using Saltstack Adaptor Commands and params to pass in: reqExecSLSFile API:***
 117
 118 Method to execute a single sls on SaltState server (Where the SLS file in the adaptor). The command entered will only be the SLS file location on the APPC/ODL container and the output from server will be in JSON format automatically.
 119 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.
 120 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.
 121 1) Execute a single command on SaltState server : Example command will look like:
 122     In the context set the "SlsFile" to "/path/to/test.sls" //mention the path of the SLS file in ODL container.
 123     In the context set the "Timeout"; -> set large timeout if your SLS file will take large time to finish executing (in Seconds).
 124     In the context set the "NodeList" to "minion1" //to the minions or VNFCs you want to apply the SLS file to.
 125     "NodeList" can be empty or set to 'minion*' (pattern matching) or set to "*" is the SLS has to be applied to all the minions or VNFCs.
 126     In the context set the "FileParameters: 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 (Optional).
 127     In the context set the "EnvParameters: 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.
 128
 129 In this case, params that will hold the command execution result for DG access in Key:
 130 Result code at: org.onap.appc.adapter.saltstack.result.code (On success: This will be 200, this means the command was executed successfully and also configuration change made using the SLS file was also successful)
 131 Message at: org.onap.appc.adapter.saltstack.message
 132 Both user inputted/auto generated req Id at:  org.onap.appc.adapter.saltstack.Id
 133 The result code here will be the execution of configuration SLS file on the server.
 134
 135 Control the state system on the minion: by specifying Env Params (pillars) and Files.
 136
 137 https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.state.html