github.com/ctdk/schob

Schob

Schob is a client for "shovey", a mechanism for pushing jobs to client nodes. Currently it's specific to goiardi, but a more general implementation is planned.

Dependencies

Running schob requires a goiardi server (both to send jobs to the schob client, and for the schob client to send reports to) and serf running with the goiardi server and on every client node that will run shovey jobs.

The knife-shove plugin from https://github.com/ctdk/knife-shove or rubygems is required to submit and administer shovey jobs.

Schob has the following golang dependencies outside of the standard library: go-flags, toml, logger, the go-chef chef library, serf, go-uuid, and the chefcrypto library from goiardi (only for tests). The easiest way to install these dependencies is to include the -t flag when using go get to install schob.

Installation

The easiest way to install schob is with the shovey-jobs cookbook, located at https://github.com/ctdk/shovey-jobs. At the moment it only supports Debian, though, so for now installing on non-Debian platforms will have to install schob by hand. If you already have a binary you can skip to number 2.

1. Set up go and configure go. (http://golang.org/doc/install.html)
2. Download schob and its dependencies.

   go get -t github.com/ctdk/schob

3. Install the schob binary.

   go install github.com/ctdk/schob Alternately, if you downloaded a precompiled binary, put that binary somewhere in your PATH.

4. Make sure goiardi is running on its server, along with serf, and that it's configured to use serf and shovey. You will also need to make the RSA public/private key pair for signing and verifying shovey jobs.
5. Start up serf on the node, making sure that it joins the same serf cluster goairdi's serf is running in.
6. Make sure the shovey signing public RSA key is installed on the node.
7. Create a whitelist.json file for the node, with whitelisted jobs that are allowed to run on the node. See the example whitelist.json file in test/whitelist.json for guidance.
8. Run schob. Schob can take a configuration file (an example is provided in test/schob-example.conf, or it can use the following command line options:

  -v, --version          Print version info.
  -V, --verbose          Show verbose debug information. Repeat for more
                         verbosity.
  -c, --config=          Specify a configuration file.
  -L, --log-file=        Log to this file.
  -s, --syslog           Use syslog for logging. Incompatible with
                         -L/--log-file.
  -e, --endpoint=        Server endpoint
  -n, --node-name=       This node's name
  -k, --key-file=        Path to node client private key
  -m, --time-slew=       Time difference allowed between the node's clock and
                         the time sent in the serf command from the server.
                         Formatted like 5m, 150s, etc. Defaults to 15m.
  -w, --whitelist=       Path to JSON file containing whitelisted commands
  -t, --run-timeout=     The time, in minutes, to wait before stopping a job.
                         Separate from the timeout set from the server, this is
                         a fallback. Defaults to 45 minutes.
  -p, --sign-pub-key=    Path to public key used to verify signed requests from
                         the server.
      --serf-addr=       IP anddress and port to use for RPC communication with
                         the serf agent. Defaults to 127.0.0.1:7373.
  -q, --queue-save-file= File to save running job status to recover jobs that
                         didn't finish if schob is suddenly shut down without a
                         chance to clean up.

Options specified on the command line override options in the config file. A typical command line invocation of schob looks like schob -VVVV -e http://chef-server.local:4545 -n node-name.local -k /path/to/node.key -w /path/to/schob/test/whitelist.json -p /path/to/public.key --serf-addr=127.0.0.1:7373.

Usage

Once schob is running on a node, run jobs on it with the knife-shove plugin. The full documentation for that can be found at https://github.com/ctdk/knife-shove, but here's a cheat sheet:

• To start a job:

  knife goiardi start node1, node2,...

• To start a job on all nodes in the webapp role, where 90% of the nodes must be up:

  knife goiardi job start -quorum 90% 'chef-client' --search 'role:webapp'

• To see a job's status:

  knife goiardi job status

• To get detailed information on a job on one node:

  knife goiardi job info

• To stream a running job:

  knife goiardi job stream

• To cancel a job:

  knife goiardi job cancel

• To get a node's status:

  knife goiardi node status

Contributing

1. Fork the repository on Github
2. Create a named feature branch (like add_component_x)
3. Write your change
4. Write tests for your change (if applicable)
5. Run the tests, ensuring they all pass
6. Submit a Pull Request using Github

See Also

• goiardi (https://github.com/ctdk/goiardi)
• knife-shove (https://github.com/ctdk/knife-shove)
• shovey-jobs cookbook (https://github.com/ctdk/shovey-jobs)
• Goiardi's shovey documentation (http://goiardi.readthedocs.org/en/latest/features/serf_and_shovey.html#shovey)
• Shovey API documentation (http://goiardi.readthedocs.org/en/latest/features/shovey_api.html)

Author

Jeremy Bingham ([e-mail])

Copyright

Copyright 2014, Jeremy Bingham

License

Schob is licensed under the Apache 2.0 License. See the LICENSE file for details.

"Schob" is German for "shoved".