1CHAKE(1) CHAKE(1)
2
6 chake - serverless configuration with chef
7
9 chake is a tool that helps you manage multiple hosts with, without the
10 need for a chef server. Configuration is managed in a local directory,
11 which should probably be under version control with git(1) or anything
12 else. Configuration is usually deployed via rsync over SSH, and applied
13 by invoking chef-solo(1) over SSH on each host.
14
16 $ chake init
17 [create] nodes.yaml
18 [ mkdir] nodes.d/
19 [create] config.rb
20 [ mkdir] config/roles
21 [ mkdir] cookbooks/basics/recipes/
22 [create] cookbooks/basics/recipes/default.rb
23 [create] Rakefile
24 A brief explanation of the created files:
26 • nodes.yaml: where you will list the hosts you will be managing, and
28 what recipes to apply to each of them.
29 • nodes.d: a directory with multiple files in the same format as
31 nodes.yaml. All files matching *.yaml in it will be added to the
32 list of nodes.
33 • config.rb: contains the chef-solo configuration. You can modify it,
35 but usually you won’t need to.
36 • config/roles: directory is where you can put your role definitions.
38 • cookbooks: directory where you will store your cookbooks. A sample
40 cookbook called "basics" is created, but feel free to remove it and
41 add actual cookbooks.
42 • Rakefile: Contains just the require 'chake' line. You can augment
44 it with other tasks specific to your intrastructure.
45 After the repository is created, you can call either chake or rake, as
47 they are completely equivalent.
48
50 Just after you created your repository, the contents of nodes.yaml is
51 the following:
52 host1.mycompany.com:
54 run_list:
55 - recipe[basics]
56 You can list your hosts with rake nodes:
58 $ rake nodes
60 host1.mycompany.com ssh
61 To add more nodes, just append to nodes.yaml:
63 host1.mycompany.com:
65 run_list:
66 - recipe[basics]
67 host2.mycompany.com:
68 run_list:
69 - recipes[basics]
70 And chake now knows about your new node:
72 $ rake nodes
74 host1.mycompany.com ssh
75 host2.mycompany.com ssh
76
78 Nodes have very few initial requirements to be managed with chake:
79 • The node must be accessible via SSH.
81 • The user you connect to the node must either be root, or be allowed
83 to run sudo (in which case sudo must be installed).
84 A note on password prompts: every time chake calls ssh on a node, you
86 may be required to type in your password; every time chake calls sudo
87 on the node, you may be require to type in your password. For managing
88 one or two nodes this is probably fine, but for larger numbers of nodes
89 it is not practical. To avoid password prompts, you can:
90 • Configure SSH key-based authentication. This is more secure than
92 using passwords. While you are at it, you also probably want
93 disable password authentication completely, and only allow
94 key-based authentication
95 • Configure passwordless sudo access for the user you use to connect
97 to your nodes.
98
100 To check whether hosts are correcly configured, you can use the check
101 task:
102 $ rake check
104 That will run the the sudo true command on each host. If that pass
106 without you having to passwords, you are sure that
107 • you have SSH access to each host; and
109 • the user you are connecting as has password-less sudo correctly
111 setup.
112 $ rake check
114
116 Note that by default all tasks that apply to all hosts will run in
117 parallel, using rake’s support for multitasks. If for some reason you
118 need to prevent that, you can pass -j1 (or --jobs=1`) in the rake
119 invocation. Note that by default rake will only run N+4 tasks in
120 parallel, where N is the number of cores on the machine you are running
121 it. If you have more than N+4 hosts and want all of them to be handled
122 in parallel, you might want o pass -j (or --jobs), without any number,
123 as the last argument; with that rake will have no limit on the number
124 of tasks to perform in parallel.
125 To apply the configuration to all nodes, run
127 $ rake converge
129 To apply the configuration to a single node, run
131 $ rake converge:$NODE
133 To apply a single recipe on all nodes, run
135 $ rake apply[myrecipe]
137 To apply a single recipe on a specific node, run
139 $ rake apply:$NODE[myrecipe]
141 If you don’t inform a recipe in the command line, you will be prompted
143 for one.
144 To run a shell command on all nodes, run
146 $ rake run[command]
148 If the command you want to run contains spaces, or other characters
150 that are special do the shell, you have to quote them.
151 To run a shell command on a specific node, run
153 $ rake run:$NODE[command]
155 If you don’t inform a command in the command line, you will be prompted
157 for one.
158 To check the existing tasks, run
160 $ rake -T
162
164 Since chake is actually a wrapper for Chef Solo, you should read the
165 [chef documentation](https://docs.chef.io/). In special, look at the
166 [Chef Solo Documentation](https://docs.chef.io/chef_solo.html).
167
169 When chake acts on a node for the first time, it has to bootstrap it.
170 The bootstrapping process includes doing the following:
171 • installing chef and rsync
173 • disabling the chef client daemon
175 • setting up the hostname
177
179 The keys in the hash that is represented in nodes.yaml is a node URL.
180 All components of the URL but the hostname are optional, so just
181 listing hostnames is the simplest form of specifying your nodes. Here
182 are all the components of the node URLs:
183 [backend://][username@]hostname[:port][/path]
185 • backend: backend to use to connect to the host. ssh or local
187 (default: ssh)
188 • username: user name to connect with (default: the username on your
190 local workstation)
191 • hostname: the hostname to connect to (default: none)
193 • port: port number to connect to (default: 22)
195 • /path: where to store the cookbooks at the node (default:
197 /var/tmp/chef.$USERNAME)
198
200 HOOKS
201 You can define rake tasks that will be executed before bootstrapping
202 nodes, before uploading configuration management content to nodes, and
203 before converging. To do this, you just need to enhance the
204 corresponding tasks:
205 • bootstrap_common: executed before bootstrapping nodes (even if
207 nodes have already been bootstrapped)
208 • upload_common: executed before uploading content to the node
210 • converge_common: executed before converging (i.e. running chef)
212 • connect_common: executed before doing any action that connects to
214 any of the hosts. This can be used for example to generate a ssh
215 configuration file based on the contents of the nodes definition
216 files.
217 Example:
219 task :bootstrap_common do
221 sh './scripts/pre-bootstrap-checks'
222 end
223 ENCRYPTED FILES
225 Any files ending matching .gpg and .asc will be decrypted with GnuPG
226 before being sent to the node. You can use them to store passwords and
227 other sensitive information (SSL keys, etc) in the repository together
228 with the rest of the configuration.
229 REPOSITORY-LOCAL SSH CONFIGURATION
231 If you need special SSH configuration parameters, you can create a file
232 called .ssh_config (or whatever file name you have in the
233 $CHAKE_SSH_CONFIG environment variable, see below for details) in at
234 the root of your repository, and chake will use it when calling ssh.
235 LOGGING IN TO A HOST
237 To easily login to one of your host, just run rake login:$HOSTNAME.
238 This will automatically use the repository-local SSH configuration as
239 above so you don’t have to type -F .ssh_config all the time.
240 RUNNING ALL SSH INVOCATIONS WITH SOME PREFIX COMMAND
242 Some times, you will also want or need to prefix your SSH invocations
243 with some prefix command in order to e.g. tunnel it through some
244 central exit node. You can do this by setting $CHAKE_SSH_PREFIX on your
245 environment. Example:
246 CHAKE_SSH_PREFIX=tsocks rake converge
248 The above will make all SSH invocations to all hosts be called as
250 tsocks ssh [...]
251 CONVERGING LOCAL HOST
253 If you want to manage your local workstation with chake, you can
254 declare a local node like this in nodes.yaml:
255 local://thunderbolt:
257 run_list:
258 - role[workstation]
259 To apply the configuration to the local host, you can use the
261 conventional rake converge:thunderbolt, or the special target rake
262 local.
263 When converging all nodes, chake will skip nodes that are declared with
265 the local:// backend and whose hostname does not match the hostname in
266 the declaration. For example:
267 local://desktop:
269 run_list:
270 - role[workstation]
271 local://laptop:
272 run_list:
273 - role[workstation]
274 When you run rake converge on desktop, laptop will be skipped, and
276 vice-versa.
277 ACCESSING NODE DATA FROM YOUR OWN TASKS
279 It’s often useful to be able to run arbitrary commands against the data
280 you have about nodes. You can use the Chake.nodes for that. For
281 example, if you want to geolocate each of yours hosts:
282 task :geolocate do
284 Chake.nodes.each do |node|
285 puts "#{node.hostname}: %s" % `geoiplookup #{node.hostname}`.strip
286 end
287 end
288
290 • $CHAKE_SSH_CONFIG: Local SSH configuration file. Defaults to
291 .ssh_config.
292 • $CHAKE_SSH_PREFIX: Command to prefix SSH (and rsync over SSH) calls
294 with.
295 • $CHAKE_RSYNC_OPTIONS: extra options to pass to rsync. Useful to
297 e.g. exclude large files from being upload to each server.
298 • $CHAKE_NODES: File containing the list of servers to be managed.
300 Default: nodes.yaml.
301 • $CHAKE_NODES_D: Directory containing node definition files servers
303 to be managed. Default: nodes.d.
304 • $CHAKE_TMPDIR: Directory used to store temporary cache files.
306 Default: tmp/chake.
307 • $CHAKE_CHEF_CONFIG: Chef configuration file, relative to the root
309 of the repository. Default: config.rb.
310
312 • rake(1), chef-solo(1)
313 • Chef documentation: https://docs.chef.io/
315 2021-07-23 CHAKE(1)