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

# 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

# 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
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

# 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

ENVIRONMENT VARIABLES

279       ·   $CHAKE_SSH_CONFIG:   Local  SSH  configuration  file.  Defaults  to
280           .ssh_config.
281
282       ·   $CHAKE_SSH_PREFIX: Command to prefix SSH (and rsync over SSH) calls
283           with.
284
285       ·   $CHAKE_RSYNC_OPTIONS:  extra  options  to  pass to rsync. Useful to
286           e.g. exclude large files from being upload to each server.
287
288       ·   $CHAKE_NODES: File containing the list of servers  to  be  managed.
289           Default: nodes.yaml.
290
291       ·   $CHAKE_NODES_D:  Directory containing node definition files servers
292           to be managed. Default: nodes.d.
293
294       ·   $CHAKE_TMPDIR: Directory  used  to  store  temporary  cache  files.
295           Default: tmp/chake.
296
297       ·   $CHAKE_CHEF_CONFIG:  Chef  configuration file, relative to the root
298           of the repository. Default: config.rb.
299

SEE ALSO

301       ·   rake(1), chef-solo(1)
302
303       ·   Chef documentation: <https://docs.chef.io/>
304
305
306
307                                  2019-02-02                          CHAKE(1)
Impressum