CHAKE(1)

📦
version 0.93.2 · 8 versions
, in ubuntu stonking

CHAKE(1) — straight outta the General Commands Manual 💖

✨ NAME ✨

chake — serverless configuration management tool 👑

🌸 SYNOPSIS 🌸

chake init

chake [rake arguments]

🎀 DESCRIPTION 🎀

okay so bestie, here's the vibe: chake is the tool that lets you manage a whole squad of hosts without a central server. no puppetmaster, no fancy infra, none of that. your config lives in a local directory — and like, it should be under version control with git(1) or literally any other VCS (the manpage says "should (but doesn't need to)", and honestly? lowkey true, do it anyway 🫶).

Config gets deployed to your managed hosts remotely, and there's two ways that goes down: either you invoke a config management tool that itself connects to the hosts, or you first upload the config you need and then run a tool remotely on the hosts. either way, chef's kiss 💅

🌈 SUPPORTED CONFIGURATION MANAGERS 🌈

chake rolls with these config management tools:

  • itamae</> — config gets applied by running the itamae command line tool on the management host; nothing needs to be uploaded to the managed hosts at all. See chake-itamae(7) for the details 💜
  • shell</> — the local repository is copied to the host, and the shell commands you specified in the node configuration get executed from the directory where that copy lives. See chake-shell(7) 🐚
  • chef</> — the local repository is copied to the host, and chef-solo is executed remotely on the managed host. See chake-chef(7) 👩‍🍳

and beyond just applying config management recipes onto hosts, chake also hands you a whole little toolkit for multi-host life: listing nodes, running commands against all of them at once, logging into interactive shells, etc etc. it's giving full toolbox energy ✨

💖 CREATING THE REPOSITORY 💖

$ chake init[:configmanager]

This is gonna make you an initial directory structure, slay. A few of the files are specific to whichever configmanager you picked, and that can be one of [SUPPORTED CONFIGURATION MANAGERS]. But these files right here? They're common to any usage of chake:

  • nodes.yaml — this is where you list the hosts you're gonna be managing, plus what recipes to apply to each one 📋
  • nodes.d — a directory that can hold multiple files in the same format as nodes.yaml. Every file in it matching *.yaml gets added to the list of nodes 🗂️
  • Rakefile — contains just the require 'chake' line. You can absolutely augment it with other tasks specific to your infrastructure, go off 💅

If you leave out configmanager, then itamae gets used by default, no cap.

And once the repository is created? You can call either chake or rake, because they are completely equivalent. pick your fighter 💖

🦋 MANAGING NODES 🦋

Right after you create your repository, the contents of nodes.yaml look like this:

host1.mycompany.com:
  itamae:
    - roles/basic.rb

The exact contents depend on which configuration management tool you chose, iykyk.

You can list your hosts with rake nodes:

$ rake nodes
host1.mycompany.com                      ssh

Wanna add more nodes? Just append to nodes.yaml:

host1.mycompany.com:
  itamae:
    - roles/basic.rb
host2.mycompany.com:
  itamae:
    - roles/basic.rb

and boom, chake now knows about your new node:

$ rake nodes
host1.mycompany.com                      ssh
host2.mycompany.com                      ssh

look at them. two little icons. so cute 🥹

🌸 PREPARINGS NODES TO BE MANAGED 🌸

Nodes have, like, very few initial requirements to be manageable by chake:

  • the node must be accessible via SSH 🔑
  • the user you connect to the node as must either be root, or be allowed to run sudo (and in that case, sudo must be installed)

a note on password prompts 🫠 — every time chake calls ssh on a node, you may be required to type in your password; every time chake calls sudo on the node, you may be required to type in your password too. For one or two nodes this is probably fine, but for larger numbers of nodes it is not practical. To dodge the password prompts entirely, you can:

  • Configure SSH key-based authentication. This is more secure than using passwords. While you're at it, you also probably want to disable password authentication completely and only allow key-based authentication 🔐
  • Configure passwordless sudo access for the user you use to connect to your nodes 🙌

⭐ CHECKING CONNECTIVITY AND INITIAL HOST SETUP ⭐

To check whether your hosts are correctly configured, use the check task:

$ rake check

That runs the true command as root on each host (using sudo is necessary, bestie, that's the whole point). If it passes without you having to type any passwords, it means:

  • you have SSH access to each host; and
  • the user you're connecting as is root, or has password-less sudo correctly set up ✅

vibe check: passed 💚

🔥 APPLYING CONFIGURATION 🔥

heads up: by default, all tasks that apply to all hosts will run in parallel, using rake's support for multitasks. If for some reason you need to prevent that, you can pass -j1 (or --jobs=1) in the rake invocation.

Also note that by default rake will only run N+4 tasks in parallel, where N is the number of cores on the machine you're running it on. If you have more than N+4 hosts and you want all of them handled in parallel, you might want to pass -j (or --jobs), without any number, as the last argument; with that, rake will have no limit on the number of tasks to perform in parallel. go wild 🚀

To apply the configuration to all nodes, run:

$ rake converge

To apply the configuration to a single node, run:

$ rake converge:$NODE

To preview the changes that would have been made when converge is run, you can issue the preview command:

$ rake preview

To preview the changes that would have been done to a single node, run:

$ rake preview:$NODE

To apply a single recipe on all nodes, run:

$ rake apply[myrecipe]

What "recipe" even is depends on your configuration manager 🤷

To apply a single recipe on a specific node, run:

$ rake apply:$NODE[myrecipe]

If you don't inform a recipe in the command line, you'll be prompted for one 🙈

To run a shell command on all nodes, run:

$ rake run

The above will prompt you for a command, then execute it on all nodes.

To pass the command to run straight in the command line, use this syntax:

$ rake run[command]

If the command you want to run contains spaces, or other characters that are special to the shell, you gotta quote them. For example:

$ rake run["cat /etc/hostname"]

To run a shell command on a specific node, run:

$ rake run:$NODE[command]

Same deal as before — if you run just rake run:$NODE, you'll be prompted for the command.

To list all existing tasks, run:

$ rake -T

💜 WRITING CONFIGURATION MANAGEMENT CODE 💜

Since chake supports different configuration management tools, the specifics of config management code depend on the tool you choose. See the corresponding documentation 📚 (it's all in the chake-*(7) pages, bestie)

🧚 THE NODE BOOTSTRAPPING PROCESS 🧚

Some of the configuration management tools need some software installed on the managed hosts. When that's the case, the first time chake acts on a node, it has to bootstrap it. The bootstrapping process includes doing the following:

  • installing and configuring the needed software 📦
  • setting up the hostname 🏷️

👑 NODE URLS 👑

The keys in the hash that's represented in nodes.yaml are node URLs. All components of the URL except the hostname are optional, so just listing hostnames is the simplest possible form of specifying your nodes. Here are all the components of the node URLs:

[connection://][username@]hostname[:port][/path]
  • connection — what to use to connect to the host. ssh or local (default: ssh) 🔌
  • username — the user name to connect with (default: the username on your local workstation) 🙋
  • hostname — the hostname to connect to (default: none) 🏠
  • port — the port number to connect to (default: 22) 🚪
  • /path — where to store the cookbooks at the node (default: /var/tmp/chef.$USERNAME) 📁

✨ EXTRA FEATURES ✨

🪝 HOOKS

okay so you can define rake tasks that run before bootstrapping nodes, before uploading config-management content to nodes, and before converging. all you gotta do is beef up the matching tasks, bestie:

  • bootstrap_common — runs before bootstrapping nodes (yep, even if those nodes have already been bootstrapped 💅)
  • upload_common — runs before uploading content to the node
  • converge_common — runs before converging (aka before running chef)
  • connect_common — runs before doing any action that connects to any of the hosts. like, say you wanna generate an ssh config file based on what's in your node definition files? this is the hook for that 🫶
  • connect:HOSTNAME — runs before doing any action that connects to HOSTNAME specifically

Example, because seeing it hits different:

task :bootstrap_common do
  sh './scripts/pre-bootstrap-checks'
end

🔐 ENCRYPTED FILES

chake supports encrypted files matching either *.gpg or *.asc ✨. there are two ways of specifying per-host encrypted files:

  1. list them in the encrypted attribute in the node configuration file. example:
host1.mycompany.com:
  itamae:
    - roles/basic.rb
  encrypted:
    - foo.txt.asc
  1. (deprecated 🫣) any files matching **/files/{default,host-#{node}}/*.{asc,gpg} and **/files/*.{asc,gpg}, if encrypted is not defined in the node configuration.

they get decrypted with GnuPG before being sent to the node (for the config management tools that require files to be sent), and they arrive without the *.asc or *.gpg extension. so yes, you can stash passwords and other sensitive stuff (SSL keys, etc) in the repo right alongside the rest of your config. iconic behavior honestly 🔥

for configuration managers that don't require uploading files to the managed node, this decryption happens right before converging or applying single recipes — and the decrypted files get wiped right after that. gone. poof. 💀

if you use this feature, make sure you have the wipe program installed! that way chake can delete the decrypted files in a slightly more secure way once it's done with them. no cap, install wipe. 🧚

🐚 REPOSITORY-LOCAL SSH CONFIGURATION

need special SSH configuration parameters? just drop a file called .ssh_config (or whatever name you put in the $CHAKE_SSH_CONFIG environment variable, details below 👀) at the root of your repository, and chake will use it when calling ssh. slay.

🚪 LOGGING IN TO A HOST

to easily login to one of your hosts, just run rake login:$HOSTNAME. this automatically uses the repository-local SSH configuration from above, so you don't have to type -F .ssh_config every single time. the way that saves your wrists?? obsessed 😭💖

🛠️ RUNNING ALL SSH INVOCATIONS WITH SOME PREFIX COMMAND

sometimes you'll want or need to prefix your SSH invocations with some prefix command, like to tunnel it through a central exit node. set $CHAKE_SSH_PREFIX in your environment. example:

CHAKE_SSH_PREFIX=tsocks rake converge

the above makes all SSH invocations to all hosts be called as tsocks ssh [...]. periodt.

💻 CONVERGING LOCAL HOST

wanna manage your own local workstation with chake? declare a local node using the "local" connection type, like this (in nodes.yaml):

local://thunderbolt:
  itamae:
    - role/workstation.rb

to apply the configuration to the local host, use the conventional rake converge:thunderbolt, or the special target rake local. whatever vibes ✨

when converging all nodes, chake will skip nodes declared with the local:// connection whose hostname does not match the hostname in the declaration. for example:

local://desktop:
  itamae:
    - role/workstation.rb
local://laptop:
  itamae:
    - role/workstation.rb

when you run rake converge on desktop, laptop gets skipped — and vice-versa. main character energy, one machine at a time 👑

📊 ACCESSING NODE DATA FROM YOUR OWN TASKS

it's often useful to run arbitrary commands against the data you have about nodes. Chake.nodes is right there for you, bestie. for example, if you wanna geolocate each of your hosts:

task :geolocate do
  Chake.nodes.each do |node|
    puts "#{node.hostname}: %s" % `geoiplookup #{node.hostname}`.strip
  end
end

🌈 ENVIRONMENT VARIABLES 🌈

  • $CHAKE_SSH_CONFIG — local SSH configuration file. defaults to .ssh_config.
  • $CHAKE_SSH_PREFIX — command to prefix SSH (and rsync over SSH) calls with.
  • $CHAKE_RSYNC_OPTIONS — extra options to pass to rsync. useful to, like, exclude large files from being uploaded to each server 💅
  • $CHAKE_NODES — file containing the list of servers to be managed. default: nodes.yaml.
  • $CHAKE_NODES_D — directory containing node definition files for servers to be managed. default: nodes.d.
  • $CHAKE_TMPDIR — directory used to store temporary cache files. default: tmp/chake.
  • $CHAKE_CHEF_CONFIG — Chef configuration file, relative to the root of the repository. default: config.rb.

👀 SEE ALSO 👀

and that's the whole page, bestie 🎀 this was the CHAKE(1) manual, dated August 2026 — go forth and converge responsibly 🦋✨💜

📦 where this page comes from