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.
