salt-api(7) - Linux man page

Name

salt-api - salt-api Documentation

salt-api is a modular interface on top of Salt that can provide a variety of entry points into a running Salt system. It can start and manage multiple interfaces allowing a REST API to coexist with XMLRPC or even a Websocket API.

Getting Started

Running salt-api will automatically start any netapi modules that have been configured in your Salt master config file. Consult the documentation for each netapi module for what options are required. salt-api must be run on the same machine as your Salt master.

Netapi Modules

The core functionality for salt-api lies in pluggable netapi modules that adhere to the simple interface of binding to a port and starting a service.

Introduction to netapi modules

netapi modules simply bind to a port and start a service. They are enabled by specifying the name of a netapi module and the port to bind in the master config file.

Communication with Salt and Salt satelite projects is done by passing a list of low-data dictionaries to a client interface. Low-data is a dictionary that specifies the client, the function inside that client to execute, and any additional arguments or parameters.

Client interfaces

class saltapi.APIClient(opts)

Provide a uniform method of accessing the various client interfaces in Salt in the form of low-data data structures. For example:

>>> client = APIClient(__opts__)
>>> lowdata = {'client': 'local', 'tgt': '*', 'fun': 'test.ping', 'arg': ''}
>>> client.run(lowdata)

local(*args, **kwargs)

Wrap LocalClient for running execution modules

runner(fun, **kwargs)

Wrap RunnerClient for executing runner modules

wheel(fun, **kwargs)

Wrap Wheel to enable executing wheel modules

Writing netapi modules

netapi modules, put simply, bind a port and start a service. They are purposefully open-ended and can be used to present a variety of external interfaces to Salt, and even present multiple interfaces at once.

See also

The full list of netapi modules

Configuration

All netapi configuration is done in the Salt master config and takes a form similar to the following:

rest_cherrypy:
  port: 8000
  debug: True
  ssl_crt: /etc/pki/tls/certs/localhost.crt
  ssl_key: /etc/pki/tls/certs/localhost.key

The __virtual__ function

Like all module types in Salt, netapi modules go through Salt's loader interface to determine if they should be loaded into memory and then executed.

The __virtual__ function in the module makes this determination and should return False or a string that will serve as the name of the module. If the module raises an ImportError or any other errors, it will not be loaded.

The start function

The start() function will be called for each netapi module that is loaded. This function should contain the server loop that actually starts the service. This is started in a multiprocess.

Inline documentation

As with the rest of Salt, it is a best-practice to include liberal inline documentation in the form of a module docstring and docstrings on any classes, methods, and functions in your netapi module.

Loader "magic" methods

The loader makes the __opts__ datastructure available to any function in a netapi module.

Full list of netapi modules

Full list of netapi modules

rest_cherrypy

A hypermedia REST API for Salt using the CherryPy framework

depends

• CherryPy Python module

configuration

The master config may contain the following options:

port

Required

debug

False Used during development; does not use SSL

ssl_crt

Required when debug is False

ssl_key

Required when debug is False

static

A filesystem path to static

HTML/JavaScript/CSS/image assets. If this directory contains a index.html file, it will be served at the root URL when HTML is requested by a client via the Accept header.

This directory may point to a clone of the salt-ui project to bootstrap a graphical interface for interacting with Salt.

For example:

rest_cherrypy:
  port: 8000
  ssl_crt: /etc/pki/tls/certs/localhost.crt
  ssl_key: /etc/pki/tls/certs/localhost.key

The REST interface requires a secure HTTPS connection. You must provide an SSL certificate to use. If you don't already have a certificate and don't wish to buy one, you can generate a self-signed certificate using the create_self_signed_cert() function in Salt (note the dependencies for this module):

% salt-call tls.create_self_signed_cert

Content negotiation

You may request various output formats by sending the appropriate Accept header. You may also send various formats in POST and PUT requests by specifying the Content-Type.

class saltapi.netapi.rest_cherrypy.LowDataAdapter(opts)

The primary purpose of this handler is to provide a RESTful API to execute Salt client commands and return the response as a data structure.

Parameters

opts -- A dictionary of options from Salt's master config (e.g. Salt's, __opts__)

GET()

The API entry point

GET /

An explanation of the API with links of where to go next.

Example request:

% curl -i localhost:8000

GET / HTTP/1.1
Host: localhost:8000
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

success

Status 401

authentication required

Status 406

requested Content-Type not available

POST(**kwargs)

The primary execution vector for the rest of the API

POST /

You must pass low-data in the requst body either from an HTML form or as JSON or YAML.

Example request:

% curl -si https://localhost:8000 \
        -H "Accept: application/x-yaml" \
        -H "X-Auth-Token: d40d1e1e" \
        -d client=local \
        -d tgt='*' \
        -d fun='test.ping' \
        -d arg

POST / HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml
X-Auth-Token: d40d1e1e
Content-Length: 36
Content-Type: application/x-www-form-urlencoded

fun=test.ping&arg&client=local&tgt=*

HTTP/1.1 200 OK
Content-Length: 200
Allow: GET, HEAD, POST
Content-Type: application/x-yaml

return:
- ms-0: true
  ms-1: true
  ms-2: true
  ms-3: true
  ms-4: true

lowstate data appropriate for the client interface you are calling.

Lowstate may be supplied in any supported format by specifying the Content-Type header in the request. Supported formats are listed in the Alternates response header.

Status 200

success

Status 401

authentication required

Status 406

requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Login(opts)

All interactions with this REST API must be authenticated. Authentication is performed through Salt's eauth system. You must set the eauth backend and allowed users by editing the external_auth section in your master config.

Authentication credentials are passed to the REST API via a session id in one of two ways:

If the request is initiated from a browser it must pass a session id via a cookie and that session must be valid and active.

If the request is initiated programmatically, the request must contain a X-Auth-Token header with valid and active session id.

GET()

Present the login interface

GET /login

An explanation of how to log in.

Example request:

% curl -i localhost:8000/login

GET /login HTTP/1.1
Host: localhost:8000
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html

authentication required

Status 406

requested Content-Type not available

POST(**kwargs)

Authenticate against Salt's eauth system. Returns a session id and redirects on success.

POST /login

Example request:

% curl -si localhost:8000/login \
        -H "Accept: application/json" \
        -d username='saltuser' \
        -d password='saltpass' \
        -d eauth='pam'

POST / HTTP/1.1
Host: localhost:8000
Content-Length: 97
Content-Type: application/x-www-form-urlencoded

username=saltuser&password=saltpass&eauth=pam

HTTP/1.1 302 Found
Content-Length: 97
Location: http://localhost:8000/
X-Auth-Token: 6d1b722e
Set-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/

the eauth backend configured in your master config

Form username

username

Form password

password

Status 302

success

Status 406

requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Minions(opts)

GET(mid=None)

A convenience URL for getting lists of minions or getting minion details

GET /minions/(mid)

Get grains, modules, functions, and inline function documentation for all minions or a single minion

Example request:

% curl -i localhost:8000/minions/ms-3

GET /minions/ms-3 HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

HTTP/1.1 200 OK
Content-Length: 129005
Content-Type: application/x-yaml

return:
- ms-3:
    grains.items:
      ...

mid -- (optional) a minion id

Status 200

success

Status 401

authentication required

Status 406

requested Content-Type not available

POST(**kwargs)

Start an execution command and immediately return the job id

POST /minions

You must pass low-data in the requst body either from an HTML form or as JSON or YAML. The client option is pre-set to local_async.

Example request:

% curl -sSi localhost:8000/minions \
    -H "Accept: application/x-yaml" \
    -d tgt='*' \
    -d fun='status.diskusage'

POST /minions HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml
Content-Length: 26
Content-Type: application/x-www-form-urlencoded

tgt=*&fun=status.diskusage

HTTP/1.1 202 Accepted
Content-Length: 86
Content-Type: application/x-yaml

- return:
    jid: '20130118105423694155'
    minions: [ms-4, ms-3, ms-2, ms-1, ms-0]

lowstate data for the LocalClient; the client parameter will be set to local_async

Lowstate may be supplied in any supported format by specifying the Content-Type header in the request. Supported formats are listed in the Alternates response header.

Status 202

success

Status 401

authentication required

Status 406

requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Jobs(opts)

GET(jid=None)

A convenience URL for getting lists of previously run jobs or getting the return from a single job

GET /jobs/(jid)

Get grains, modules, functions, and inline function documentation for all minions or a single minion

Example request:

% curl -i localhost:8000/jobs

GET /jobs HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

HTTP/1.1 200 OK
Content-Length: 165
Content-Type: application/x-yaml

return:
- '20121130104633606931':
    Arguments:
    - '3'
    Function: test.fib
    Start Time: 2012, Nov 30 10:46:33.606931
    Target: ms-3
    Target-type: glob

% curl -i localhost:8000/jobs/20121130104633606931

GET /jobs/20121130104633606931 HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

HTTP/1.1 200 OK
Content-Length: 73
Content-Type: application/x-yaml

return:
- ms-3:
  - - 0
    - 1
    - 1
    - 2
  - 9.059906005859375e-06

mid -- (optional) a minion id

Status 200

success

Status 401

authentication required

Status 406

requested Content-Type not available

Releases

Release notes

salt-api 0.5.0

salt-api is gearing up for the initial public release with 0.5.0. Although this release ships with working basic functionality it is awaiting the authentication backend that will be introduced in Salt 0.10.4 before it can be considered ready for testing at large.

REST API

This release presents the flagship netapi module which provides a RESTful interface to a running Salt system. It allows for viewing minions, runners, and jobs as well as running execution modules and runners of a running Salt system through a REST API that returns JSON.

Participation

salt-api is just getting off the ground so feedback, questions, and ideas are critical as we solidify how this project fits into the overall Salt infrastructure management stack. Please get involved by filing issues on GitHub, discussing on the mailing list, and chatting in #salt on Freenode.

salt-api 0.6.0

salt-api inches closer to prime-time with 0.6.0. This release adds the beginnings of a universal interface for accessing Salt components via the tried and true method of passing low-data to functions (a core component of Salt's remote execution and state management).

Low-data interface

A new view accepts :http:post: requests at the root URL that accepts raw low-data as :http:post: data and passes that low-data along to a client interface in Salt. Currently only LocalClient and RunnerClient interfaces have been implemented in Salt with more coming in the next Salt release.

External authentication

Raw low-data can contain authentication credentials that make use of Salt's new external_auth system.

The following is a proof-of-concept of a working eauth call. (It bears repeating this is a pre-alpha release and this should not be used by anyone for anything real.)

% curl -si localhost:8000 \
    -d client=local \
    -d tgt='*' \
    -d fun='test.ping' \
    -d arg \
    -d eauth=pam \
    -d username=saltdev \
    -d password=saltdev

Participation

salt-api is just getting off the ground so feedback, questions, and ideas are critical as we solidify how this project fits into the overall Salt infrastructure management stack. Please get involved by filing issues on GitHub, discussing on the mailing list, and chatting in #salt-devel on Freenode.

salt-api 0.7.0

salt-api is ready for alpha-testing in the real world. This release solidifies how salt-api will communicate with the larger Salt ecosystem. In addition authentication and encryption (via SSL) have been added.

The first netapi module was a proof of concept written in Flask. It was quite useful to be able to quickly hammer out a URL structure and solidify on an interface for programmatically calling out to Salt components. As of this release that module has been deprecated and removed in favor of a netapi module written in CherryPy. CherryPy affords tremendous flexibility when composing a REST interface and will present a stable platform for building out a very adaptable and featureful REST API-also we're using the excellent and fast CherryPy webserver for securely serving the API.

Low-data interface

The last release introduced a proof-of-concept for how the various Salt components will communicate with each other. This is done by passing a data structure to a client interface. This release expands on that. There are currently three client interfaces in Salt.

See also

netapi-introduction

Encryption and authentication

Encryption has been added via SSL. You can supply an existing certificate or generate a self-signed certificate through Salt's tls module.

Authentication is performed through Salt's incredibly flexible external auth system and is maintained when accessing the API via session tokens.

Participation

salt-api is just getting off the ground so feedback, questions, and ideas are critical as we solidify how this project fits into the overall Salt infrastructure management stack. Please get involved by filing issues on GitHub, discussing on the mailing list, and chatting in #salt-devel on Freenode.

salt-api 0.7.5

This release is a mostly a minor release to pave a better path for salt-ui though there are some small feature additions and bugfixes.

Changes

• Convenience URLs /minions and /jobs have been added as well as a async client wrapper. This starts a job and immediately returns the job ID, allowing you to fetch the result of that job at a later time.

• The return format will now default to JSON if no specific format is requested.

• A new setting static has been added that will serve any static media from the directory specified. In addition if an index.html file is found in that directory and the Accept header in the request prefer HTML that file will be served.

• All HTML, including the login form, has been removed from salt-api and moved into the salt-ui project.

• Sessions now live as long as the Salt token.

Participation

salt-api is just getting off the ground so feedback, questions, and ideas are critical as we solidify how this project fits into the overall Salt infrastructure management stack. Please get involved by filing issues on GitHub, discussing on the mailing list, and chatting in #salt-devel on Freenode.

Reference

• genindex

• modindex

• search

• glossary

Author

Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file

Copyright

2012, Thomas S. Hatch

Referenced By