1CHAKE(1)                                                              CHAKE(1)
2
3
4

NAME

6       chake - serverless configuration with chef
7

INTRODUCTION

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

CREATING THE REPOSITORY

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
25       A brief explanation of the created files:
26
27       •   nodes.yaml: where you will list the hosts you will be managing, and
28           what recipes to apply to each of them.
29
30       •   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
34       •   config.rb: contains the chef-solo configuration. You can modify it,
35           but usually you won’t need to.
36
37       •   config/roles: directory is where you can put your role definitions.
38
39       •   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
43       •   Rakefile: Contains just the require 'chake' line. You can augment
44           it with other tasks specific to your intrastructure.
45
46       After the repository is created, you can call either chake or rake, as
47       they are completely equivalent.
48

MANAGING NODES

50       Just after you created your repository, the contents of nodes.yaml is
51       the following:
52
53           host1.mycompany.com:
54             run_list:
55               - recipe[basics]
56
57       You can list your hosts with rake nodes:
58
59           $ rake nodes
60           host1.mycompany.com                      ssh
61
62       To add more nodes, just append to nodes.yaml:
63
64           host1.mycompany.com:
65             run_list:
66               - recipe[basics]
67           host2.mycompany.com:
68             run_list:
69               - recipes[basics]
70
71       And chake now knows about your new node:
72
73           $ rake nodes
74           host1.mycompany.com                      ssh
75           host2.mycompany.com                      ssh
76

PREPARINGS NODES TO BE MANAGED

78       Nodes have very few initial requirements to be managed with chake:
79
80       •   The node must be accessible via SSH.
81
82       •   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
85       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
91       •   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
96       •   Configure passwordless sudo access for the user you use to connect
97           to your nodes.
98

CHECKING CONNECTIVITY AND INITIAL HOST SETUP

100       To check whether hosts are correcly configured, you can use the check
101       task:
102
103           $ rake check
104
105       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
108       •   you have SSH access to each host; and
109
110       •   the user you are connecting as has password-less sudo correctly
111           setup.
112
113           $ rake check
114

APPLYING COOKBOOKS

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
126       To apply the configuration to all nodes, run
127
128           $ rake converge
129
130       To apply the configuration to a single node, run
131
132           $ rake converge:$NODE
133
134       To apply a single recipe on all nodes, run
135
136           $ rake apply[myrecipe]
137
138       To apply a single recipe on a specific node, run
139
140           $ rake apply:$NODE[myrecipe]
141
142       If you don’t inform a recipe in the command line, you will be prompted
143       for one.
144
145       To run a shell command on all nodes, run
146
147           $ rake run[command]
148
149       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
152       To run a shell command on a specific node, run
153
154           $ rake run:$NODE[command]
155
156       If you don’t inform a command in the command line, you will be prompted
157       for one.
158
159       To check the existing tasks, run
160
161           $ rake -T
162

WRITING COOKBOOKS

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

THE NODE BOOTSTRAPPING PROCESS

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
172       •   installing chef and rsync
173
174       •   disabling the chef client daemon
175
176       •   setting up the hostname
177

NODE URLS

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
184           [backend://][username@]hostname[:port][/path]
185
186       •   backend: backend to use to connect to the host. ssh or local
187           (default: ssh)
188
189       •   username: user name to connect with (default: the username on your
190           local workstation)
191
192       •   hostname: the hostname to connect to (default: none)
193
194       •   port: port number to connect to (default: 22)
195
196       •   /path:  where to store the cookbooks at the node (default:
197           /var/tmp/chef.$USERNAME)
198

EXTRA FEATURES

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
206       •   bootstrap_common: executed before bootstrapping nodes (even if
207           nodes have already been bootstrapped)
208
209       •   upload_common: executed before uploading content to the node
210
211       •   converge_common: executed before converging (i.e. running chef)
212
213       •   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
218       Example:
219
220           task :bootstrap_common do
221             sh './scripts/pre-bootstrap-checks'
222           end
223
224   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
230   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
236   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
241   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
247           CHAKE_SSH_PREFIX=tsocks rake converge
248
249       The above will make all SSH invocations to all hosts be called as
250       tsocks ssh [...]
251
252   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
256           local://thunderbolt:
257             run_list:
258               - role[workstation]
259
260       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
264       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
268           local://desktop:
269             run_list:
270               - role[workstation]
271           local://laptop:
272             run_list:
273               - role[workstation]
274
275       When you run rake converge on desktop, laptop will be skipped, and
276       vice-versa.
277
278   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
283           task :geolocate do
284             Chake.nodes.each do |node|
285               puts "#{node.hostname}: %s" % `geoiplookup #{node.hostname}`.strip
286             end
287           end
288

ENVIRONMENT VARIABLES

290       •   $CHAKE_SSH_CONFIG: Local SSH configuration file. Defaults to
291           .ssh_config.
292
293       •   $CHAKE_SSH_PREFIX: Command to prefix SSH (and rsync over SSH) calls
294           with.
295
296       •   $CHAKE_RSYNC_OPTIONS: extra options to pass to rsync. Useful to
297           e.g. exclude large files from being upload to each server.
298
299       •   $CHAKE_NODES: File containing the list of servers to be managed.
300           Default: nodes.yaml.
301
302       •   $CHAKE_NODES_D: Directory containing node definition files servers
303           to be managed. Default: nodes.d.
304
305       •   $CHAKE_TMPDIR: Directory used to store temporary cache files.
306           Default: tmp/chake.
307
308       •   $CHAKE_CHEF_CONFIG: Chef configuration file, relative to the root
309           of the repository. Default: config.rb.
310

SEE ALSO

312rake(1), chef-solo(1)
313
314       •   Chef documentation: https://docs.chef.io/
315
316
317
318                                  2022-07-23                          CHAKE(1)
Impressum