SaltStack Runners模組CLI命令及RunnerClientAPI介面使用指南
阿新 • • 發佈：2018-12-13
文章目錄
- Salt runners模組 & salt-run命令 & RunnerClient API 三者的關係
- SALT RUNNER 模組
- 命令列工具salt-run的使用
- RunnerClient API的使用方法
SaltStack Runners模組的主要用途是執行一些只有在Salt Master上執行時才能有最好效果的工作任務或管理任務，它純粹是一個在Salt Master側才能執行的執行序列。，比如像處理一些網路自動發現、事件管理、本地檔案伺服器管理、從本地發起的HTTP訪問、jobs管理、本地pillar資料的動態管理等等。
Salt runners模組 & salt-run命令 & RunnerClient API 三者的關係
- Salt runners是用於在Salt master上執行便捷管理功能的一個簡單的Salt功能模組。
- salt-run是執行Salt Runners的前端命令。
- RunnerClient API，是Salt Master上執行salt-run CLI工具時呼叫的salt底層介面
在Salt Master上執行的runner程式模組，都是通過呼叫底層的RunnerClient API完成的。
匯入和使用RunnerClient有一個硬性的前提條件，即必須在與Salt Master相同的機器上完成，並且必須使用與執行Salt Master相同的使用者執行。
下面是目前可用的SALT RUNNER MODULES的清單。
對於有複雜使用場景的企業，這些隨Salt模組庫分發的標準模組或模組功能並不能完全覆蓋到大家的使用需求。所以已經有一個專門解決這類問題的開源Salt專案，為開發自定義模組或模組功能提供指導與支援，https://github.com/saltstack/salt-contrib 。
這裡是一個完整Salt Runner Modules列表資訊的連結：
https://docs.saltstack.com/en/latest/ref/runners/all/
命令列工具salt-run的使用
salt-run CLI命令的語法比較簡單，使用的引數也不復雜，如下所示。
主要引數可以劃分為這樣的幾部分：
- 行為配置類引數
- 認證類引數
- 日誌類引數
- 輸出資訊類配置引數
大部分引數只有在遇到一些特別的功能定製需求時才有使用價值，總體來說這個salt-run命令的使用方法很簡單。
$ salt-run -h
Usage: salt-run [options] <function> [arguments]
salt-run is the frontend command for executing Salt Runners. Salt Runners are
modules used to execute convenience functions on the Salt Master
Options:
--version show program's version number and exit
-V, --versions-report
Show program's dependencies version number and exit.
-h, --help show this help message and exit
--saltfile=SALTFILE Specify the path to a Saltfile. If not passed, one
will be searched for in the current working directory.
-c CONFIG_DIR, --config-dir=CONFIG_DIR
Pass in an alternative configuration directory.
Default: '/etc/salt'.
-t TIMEOUT, --timeout=TIMEOUT
Change the timeout, if applicable, for the running
command (in seconds). Default: 1.
--args-stdin Read additional options and/or arguments from stdin.
Each entry is newline separated.
--hard-crash Raise any original exception rather than exiting
gracefully. Default: False.
--no-parse=argname1,argname2,...
Comma-separated list of named CLI arguments (i.e.
argname=value) which should not be parsed as Python
data types
-d, --doc, --documentation
Display documentation for runners, pass a runner or
runner.function to see documentation on only that
runner or function.
--async Start the runner operation and immediately return
control.
Logging Options:
Logging options which override any settings defined on the
configuration files.
-l LOG_LEVEL, --log-level=LOG_LEVEL
Console logging log level. One of 'all', 'garbage',
'trace', 'debug', 'profile', 'info', 'warning',
'error', 'critical', 'quiet'. Default: 'warning'.
--log-file=LOG_FILE
Log file path. Default: '/var/log/salt/master'.
--log-file-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of 'all', 'garbage',
'trace', 'debug', 'profile', 'info', 'warning',
'error', 'critical', 'quiet'. Default: 'warning'.
External Authentication:
-a EAUTH, --auth=EAUTH, --eauth=EAUTH, --external-auth=EAUTH
Specify an external authentication system to use.
-T, --make-token Generate and save an authentication token for re-use.
The token is generated and made available for the
period defined in the Salt Master.
--username=USERNAME
Username for external authentication.
--password=PASSWORD
Password for external authentication.
Output Options:
Configure your preferred output format.
--out=OUTPUT, --output=OUTPUT
Print the output from the 'salt-run' command using the
specified outputter.
--out-indent=OUTPUT_INDENT, --output-indent=OUTPUT_INDENT
Print the output indented by the provided value in
spaces. Negative values disables indentation. Only
applicable in outputters that support indentation.
--out-file=OUTPUT_FILE, --output-file=OUTPUT_FILE
Write the output to the specified file.
--out-file-append, --output-file-append
Append the output to the specified file.
--no-color, --no-colour
Disable all colored output.
--force-color, --force-colour
Force colored output.
--state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT
Override the configured state_output value for minion
output. One of 'full', 'terse', 'mixed', 'changes' or
'filter'. Default: 'none'.
--state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE
Override the configured state_verbose value for minion
output. Set to True or False. Default: none.
Output Options:
Configure your preferred output format.
--quiet Do not display the results of the run.
Profiling support:
--profiling-path=PROFILING_PATH
Folder that will hold all stats generations path.
Default: '/tmp/stats'.
--enable-profiling Enable generating profiling stats. See also:
--profiling-path.
舉幾個例子
使用salt-run呼叫http模組
在Salt Master上執行一個HTTP訪問請求，獲取一個web頁面的資料
# salt-run http.query http://192.168.81.7:8080/
body:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
......
</body>
</html>
- 頁面作為一個json資料返回，key為body，注意不要和html頁面中的body標籤混淆。
現在很多服務間呼叫都是通過介面完成的，可以像下面這樣呼叫介面地址並附帶上需要的引數：
salt-run http.query http://somelink.com/ method=POST params='key1=val1&key2=val2'
使用salt-run呼叫salt.cmd模組執行幾個系統管理方面的命令
# salt-run salt.cmd test.ping
True
# salt-run salt.cmd cmd.run "hostname"
sleeper-VirtualBox
- 以上系統命令的執行目標僅有Salt Master節點
在Salt Master上執行一個HTTP訪問請求，獲取指定URL返回響應的HTTP狀態碼
# salt-run salt.cmd cmd.run "curl -I -m 10 -o /dev/null -s -w %{http_code} http://192.168.81.7:8080/"
200
使用salt-run呼叫jobs模組完成各種jobs管理任務
檢視當前正在執行中的jobs：
# salt-run jobs.active
20180918103622717011:
----------
Arguments:
Function:
saltutil.running
Returned:
......
執行一條管理命令用於演示jobs管理方法：
[[email protected] ~]# salt testserver test.ping
testserver:
True
按執行的功能函式查詢最後執行的一次job的資訊：
# salt-run jobs.last_run function='test.ping'
20180918104254437160:
----------
Arguments:
Function:
test.ping
Minions:
-testserver
Result:
----------
testserver:
----------
return:
True
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
或者可以按執行的功能函式查詢jobs列表資訊：
# salt-run jobs.list_jobs search_function='test.ping'
20180918104254437160:
----------
Arguments:
Function:
test.ping
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
或者只查詢指定目標target主機上指定功能函式的jobs列表資訊：
# salt-run jobs.list_jobs search_target='["testserver"]' search_function='test.ping'
20180918104254437160:
----------
Arguments:
Function:
test.ping
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
如果需要指定一個查詢的時間段，需要確認安裝了python-dateutil依賴包：
pip install python-dateutil
# salt-run jobs.list_jobs search_target=testserver start_time='2018, Sep 18 10:00' end_time='2018, Sep 18 13:00'
20180918104254437160:
----------
Arguments:
Function:
test.ping
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
當然了，上面的命令很簡單，迅速就執行完畢了，但會有一些場景下的管理命令是不會這麼快返回結果的，此時可以使用下面方法查詢指定job是否已經執行完畢併成功得退出了：
# salt-run jobs.exit_success 20180918104254437160
testserver:
True
如果還需要獲取下job的返回資料：
# salt-run jobs.lookup_jid 20180918104254437160
testserver:
True
檢視指定job的完整任務資訊：
# salt-run jobs.print_job 20180918104254437160
20180918104254437160:
----------
Arguments:
Function:
test.ping
Minions:
-testserver
Result:
----------
testserver:
----------
return:
True
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
如有不明之處，請參見官網資料：
https://docs.saltstack.com/en/latest/ref/runners/all/salt.runners.jobs.html#module-salt.runners.jobs
RunnerClient API的使用方法
class salt.runner.RunnerClient(opts)，Salt Master上salt-run CLI工具使用的底層介面。
它在Salt Master上執行支援的runner程式模組。
匯入和使用RunnerClient必須在與Salt Master相同的機器上完成，並且必須使用與執行Salt Master相同的使用者執行。
Salt的external_auth功能可用於對呼叫請求進行驗證。 eauth使用者必須被授權可執行runner模組(@runner)。
external_auth是Salt auth模組所提供的，需要在Salt Master配置檔案中配置需要的使用授權。可參照下面的配置內容和連結。
external_auth:
pam:
fred:
- test.*
RunnerClient API提供了三個函式方法
- cmd(fun, arg=None, pub_data=None, kwarg=None, print_event=True, full_return=False)，執行一個runner函式
- cmd_async(low)，非同步執行一個runner函式
- cmd_sync(low, timeout=None, full_return=False)，同步方式執行一個runner函式
cmd_async(), cmd_sync()都需要有external_auth的授權支援，且在呼叫時需要參照下面方法提供認證資訊。
** 執行非同步函式前的認證：**
runner.eauth_async({
'fun': 'jobs.list_jobs',
'username': 'saltdev',
'password': 'saltdev',
'eauth': 'pam',})
執行同步函式前的認證：
runner.eauth_sync({
'fun': 'jobs.list_jobs',
'username': 'saltdev',
'password': 'saltdev',
'eauth': 'pam',})
RunnerClient API使用舉例
# python
Python 2.7.5 (default, Aug 4 2017, 00:39:18)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> import salt.config
>>> import salt.runner
>>> opts = salt.config.master_config('/etc/salt/master')
>>> runner = salt.runner.RunnerClient(opts)
>>> runner.cmd('salt.cmd', ['test.ping'])
True
True
>>> runner.cmd('salt.cmd', ['cmd.run', 'hostname'])
sleeper-VirtualBox
u'sleeper-VirtualBox'
>>> runner.cmd('salt.cmd', ['cmd.run', 'curl -I -m 10 -o /dev/null -s -w %{http_code} http://192.168.81.7:8080/'])
200
u'200'
>>>
我們可以看到上面幾個介面方法呼叫的輸出都是重複的兩份，這個只需要帶上print_event=False引數就可以減掉一個了：
>>> runner.cmd('salt.cmd', ['test.ping'], print_event=False)
True
>>>
通過API查詢一個job的執行結果
>>> runner.cmd('jobs.lookup_jid',['20180918104254437160'])
testserver:
True
{'testserver': True}
>>>
通過API查詢指定目標節點上近期執行過的jobs列表
>>> runner.cmd('jobs.list_jobs', ['search_target=testserver'])
20180918104254437160:
----------
Arguments:
Function:
test.ping
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
通過API查詢指定節點上在指定時間段內執行過的jobs資訊
>>> runner.cmd('jobs.list_jobs', ['search_target=testserver', "start_time='2018, Sep 18 10:00'", "end_time='2018, Sep 18 13:00'"])
20180918104254437160:
----------
Arguments:
Function:
test.ping
StartTime:
2018, Sep 18 10:42:54.437160
Target:
testserver
Target-type:
glob
User:
root
更加詳細的SALT.RUNNERS.JOBS使用方法請參見：
https://docs.saltstack.com/en/latest/ref/runners/all/salt.runners.jobs.html#module-salt.runners.jobs