/
doc.go
159 lines (113 loc) · 6.08 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
/*
* Copyright (c) 2014, Jeremy Bingham (<jbingham@gmail.com>)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
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 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.
0. Set up go and configure go. (http://golang.org/doc/install.html)
1. Download schob and its dependencies.
go get -t github.com/ctdk/schob
2. Install the schob binary.
go install github.com/ctdk/schob
Alternately, if you downloaded a precompiled binary, put that binary somewhere in your PATH.
3. 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.
4. Start up serf on the node, making sure that it joins the same serf cluster goairdi's serf is running in.
5. Make sure the shovey signing public RSA key is installed on the node.
6. 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.
7. 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 <command> 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 <job id>
* To get detailed information on a job on one node:
knife goiardi job info <job id> <node name>
* To stream a running job:
knife goiardi job stream <job id> <node name>
* To cancel a job:
knife goiardi job cancel <job id> <node name>
* 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 (https://github.com/ctdk/goiardi/blob/serfing/README.md#shovey)
* Shovey API documentation (https://github.com/ctdk/goiardi/blob/serfing/shovey_api.md)
Author
Jeremy Bingham (<jbingham@gmail.com>)
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".
*/
package main