Salt-API, A Crash Course

The salt-api docs do a great job but it's a bit unclear on what it takes to get a barebones salt-api proof of concept up and running. No official deployment, no top cover from a web server. Just a Salt master with salt-api running on top of it. We'll cover that here.

I (heavily) referenced the rest_cherrypy section of the docs to put this together.

This post assumes that you already have a Salt master and at least one Minion connected to it.

Install salt-api
The docs seem to mention that Pip is the best method. Also, we're going the CherryPy route so:

pip install salt-api cherrypy

Configure CherryPy
Very simple. In your master config file:
 

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

Notice the SSL lines. We can create a self-signed keypair very easily with Salt:

salt-call tls.create_self_signed_cert

Configure External Auth
Salt-api leans on the eauth system for authentication. For our quick and dirty, we can just allow our user to do everything. Back in the master config file:

external_auth:
  pam:
    saltuser:
      - .*

Turn On the Awesome
We're done configuring! With the Salt master & minion running, start salt-api:

salt-api 

You can optionally pass salt-api the -d option to put it into daemon mode.

With salt-api runnig. Test it out:

curl -k https://localhost:8000

{"status": "401 Unauthorized", "return": "Please log in"}

Success!

We'll need to log in. That looks like this:

 curl -ksi https://localhost:8000/login \
> -H "Accept: application/json" \
> -d username='saltuser' \
> -d password='password' \
> -d eauth='pam'

{"return": [{"perms": [".*"], "start": 1388722947.535586,
"token": "f72309d0ee425193bc8b763a0092470bbabab6bc",
"expire": 1388766147.535588,
"user": "saltuser",
"eauth": "pam"}]}

This gives us a token. In this example the token is  f72309d0ee425193bc8b763a0092470bbabab6bc. Let's use it to run a test.ping.

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

HTTP/1.1 200 OK
Content-Length: 25
Vary: Accept-Encoding
Server: CherryPy/3.2.4
Allow: GET, HEAD, POST
Cache-Control: private
Date: Fri, 03 Jan 2014 04:31:13 GMT
Access-Control-Allow-Origin: *
Content-Type: application/x-yaml
Set-Cookie: session_id=f72309d0ee425193bc8b763a0092470bbabab6bc; expires=Fri, 03 Jan 2014 14:31:13 GMT; Path=/

return:
- salt-api: true

Not bad. Let's try making it actually do something.

curl -ksi https://localhost:8000 \
-H "Accept: application/x-yaml" \
-H "X-Auth-Token: f72309d0ee425193bc8b763a0092470bbabab6bc" \
-d client='local' \
-d tgt='*' \
-d fun='cmd.run' \
-d arg='echo "hi salt-api!"'

HTTP/1.1 200 OK
Content-Length: 33
Vary: Accept-Encoding
Server: CherryPy/3.2.4
Allow: GET, HEAD, POST
Cache-Control: private
Date: Fri, 03 Jan 2014 04:34:19 GMT
Access-Control-Allow-Origin: *
Content-Type: application/x-yaml
Set-Cookie: session_id=f72309d0ee425193bc8b763a0092470bbabab6bc; expires=Fri, 03 Jan 2014 14:34:19 GMT; Path=/

return:
- salt-api: hi salt-api!

Neat!

You can see where we can go from here. Once you've got a RESTful interface to your Salt master, your creativity is the only limit from what you can do from there.