This rest_wsgi module provides a no-frills REST interface to a running Salt master. There are no dependencies.
Please read this introductory section in entirety before deploying this module.
configuration: | All authentication is done through Salt's external auth system. Be sure that it is enabled and the user you are authenticating as has permissions for all the functions you will be running. The configuration options for this module resides in the Salt master config file. All available options are detailed below.
Example configuration: rest_wsgi:
port: 8001
|
---|
This API is not very "RESTful"; please note the following:
See also
The rest_cherrypy module is more full-featured, production-ready, and has builtin security features.
The rest_wsgi netapi module is a standard Python WSGI app. It can be deployed one of two ways.
If run directly via salt-api it uses the wsgiref.simple_server() that ships in the Python standard library. This is a single-threaded server that is intended for testing and development. This server does not use encryption; please note that raw Salt authentication credentials must be sent with every HTTP request.
Running this module via salt-api is not recommended for most use!
This module may be run via any WSGI-compliant production server such as Apache with mod_wsgi or Nginx with FastCGI.
It is highly recommended that this app be used with a server that supports HTTPS encryption since raw Salt authentication credentials must be sent with every request. Any apps that access Salt through this interface will need to manually manage authentication credentials (either username and password or a Salt token). Tread carefully.
Example request for a basic test.ping:
% curl -sS -i \
-H 'Content-Type: application/json' \
-d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local","tgt":"*","fun":"test.ping"}]' localhost:8001
Example response:
HTTP/1.0 200 OK
Content-Length: 89
Content-Type: application/json
{"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}
Example request for an asyncronous test.ping:
% curl -sS -i \
-H 'Content-Type: application/json' \
-d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local_async","tgt":"*","fun":"test.ping"}]' localhost:8001
Example response:
HTTP/1.0 200 OK
Content-Length: 103
Content-Type: application/json
{"return": [{"jid": "20130412192112593739", "minions": ["ms--4", "ms--3", "ms--2", "ms--1", "ms--0"]}]}
Example request for looking up a job ID:
% curl -sS -i \
-H 'Content-Type: application/json' \
-d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"runner","fun":"jobs.lookup_jid","jid":"20130412192112593739"}]' localhost:8001
Example response:
HTTP/1.0 200 OK
Content-Length: 89
Content-Type: application/json
{"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}
form lowstate: | A list of lowstate data appropriate for the client interface you are calling. |
---|---|
status 200: | success |
status 401: | authentication required |