Ubuntu Manpage: chake - serverless configuration management tool

NAME

       chake - serverless configuration management tool

SYNOPSIS

       chake init

       chake [rake arguments]

DESCRIPTION

       chake is a tool that helps you manage multiple hosts without the need for a central server. Configuration
       is  managed in a local directory, which should (but doesn't need to) be under version control with git(1)
       or any other version control system.

       Configuration is deployed to managed hosts remotely, either by invoking a configuration  management  tool
       that  will connect to them, or by first uploading the necessary configuration and them remotely running a
       tool on the hosts.

SUPPORTED CONFIGURATION MANAGERS.

       chake supports the following configuration management tools:

       •   itamae: configuration is applied by running the itamae command line tool on the management  host;  no
           configuration needs to be uploaded to the managed hosts. See chake-itamae(7) for details.

       •   shell:  the  local  repository  is  copied  to the host, and the shell commands specified in the node
           configuration is executed from the directory where that copy is. See chake-shell(7) for details.

       •   chef: the local repository is copied to the host, and chef-solo is executed remotely on  the  managed
           host. See chake-chef(7) for details.

       Beyond applying configuration management recipes on the hosts, chake also provides useful tools to manage
       multiple hosts, such as listing nodes, running commands against all of them simultaneously, logging in to
       interactive shells, and others.

CREATING THE REPOSITORY

       $ chake init[:configmanager]

       This  will  create  an  initial  directory  structure. Some of the files are specific to your your chosen
       configmanager, which can be one of [SUPPORTED CONFIGURATION MANAGERS]. The following files, though,  will
       be common to any usage of chake:

       •   nodes.yaml:  where you will list the hosts you will be managing, and what recipes to apply to each of
           them.

       •   nodes.d: a directory with multiple files in the same format as nodes.yaml. All files matching  *.yaml
           in it will be added to the list of nodes.

       •   Rakefile:  Contains  just  the  require 'chake' line. You can augment it with other tasks specific to
           your intrastructure.

       If you omit configmanager, itamae will be used by default.

       After the repository is created, you can call either chake or rake, as they are completely equivalent.

MANAGING NODES

       Just after you created your repository, the contents of nodes.yaml is the following:

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

       The exact contents depends on the chosen configuration management tool.

       You can list your hosts with rake nodes:

           $ rake nodes
           host1.mycompany.com                      ssh

       To add more nodes, just append to nodes.yaml:

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

       And chake now knows about your new node:

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

PREPARINGS NODES TO BE MANAGED

       Nodes have very few initial requirements to be managed with chake:

       •   The node must be accessible via SSH.

       •   The user you connect to the node must either be root, or be allowed to run sudo (in which  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 require  to  type  in  your  password.  For
       managing  one or two nodes this is probably fine, but for larger numbers of nodes it is not practical. To
       avoid password prompts, you can:

       •   Configure SSH key-based authentication. This is more secure than using passwords. While  you  are  at
           it,  you  also  probably  want  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 hosts are correctly configured, you can use the check task:

           $ rake check

       That will run the the sudo true command on each host. If  that  pass  without  you  having  to  type  any
       passwords, it means that:

       •   you have SSH access to each host; and

       •   the user you are connecting as has password-less sudo correctly setup.

APPLYING CONFIGURATION

       Note  that  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. Note that by default rake will only run N+4 tasks in parallel, where N is the number of cores
       on  the machine you are running it. If you have more than N+4 hosts and want all of them to be 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.

       To apply the configuration to all nodes, run

           $ rake converge

       To apply the configuration to a single node, run

           $ rake converge:$NODE

       To apply a single recipe on all nodes, run

           $ rake apply[myrecipe]

       What recipe is depends on the 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 will 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 in the command line, use the following syntax:

           $ rake run[command]

       If  the  command  you want to run contains spaces, or other characters that are special do the shell, you
       have to quote them, for example:

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

       To run a shell command on a specific node, run

           $ rake run:$NODE[command]

       As before, if you run just rake run:$NODE, you will be prompted for the command.

       To list all existing tasks, run:

           $ rake -T

WRITING CONFIGURATION MANAGEMENT CODE

       As chake supports different configuration management tools, the  specifics  of  configuration  management
       code depends on the the tool you choose. See the corresponding documentation.

THE NODE BOOTSTRAPPING PROCESS

       Some  of  the  configuration management tools require some software to be installed on the managed hosts.
       When that's the case, chake acts on a node for the first time, 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 is represented in nodes.yaml is a node URL. All components of the URL but the
       hostname are optional, so just listing hostnames is the simplest 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: user name to connect with (default: the username on your local workstation)

       •   hostname: the hostname to connect to (default: none)

       •   port: port number to connect to (default: 22)

       •   /path: where to store the cookbooks at the node (default: /var/tmp/chef.$USERNAME)

EXTRA FEATURES

HOOKS
You can define rake tasks that will be executed before bootstrapping nodes, before uploading
configuration management content to nodes, and before converging. To do this, you just need to enhance
the corresponding tasks:

• bootstrap_common: executed before bootstrapping nodes (even if nodes have already been bootstrapped)

• upload_common: executed before uploading content to the node

• converge_common: executed before converging (i.e. running chef)

• connect_common: executed before doing any action that connects to any of the hosts. This can be used
for example to generate a ssh configuration file based on the contents of the nodes definition files.

• connect:HOSTNAME: executed before doing any action that connects to HOSTNAME.

Example:

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 specicying
per-host encrypted files:

1. listing them in the encrypted attribute in the node configuration file. Example:

host1.mycompany.com:
itamae:
- roles/basic.rb
encrypted:
- foo.txt.asc

2. (deprecated) any files matching \*\*/files/{default,host-#{node}}/\*.{asc,gpg} and
\*\*/files/\*.{asc,gpg}, if encrypted is not defined in the node configuration.

They will be decrypted with GnuPG before being sent to the node (for the configuration management tools
that required files to be sent), without the \*.asc or \*.gpg extension. You can use them to store
passwords and other sensitive information (SSL keys, etc) in the repository together with the rest of the
configuration.

For configuration managers that don't require uploading files to the managed node, this decryption will
happen right before converging or applying single recipes, and the decrypted files will be wiped right
after that.

If you use this feature, make sure that you have the wipe program installed. This way chake will be able
to delete the decrypted files in a slightly more secure way, after being done with them.

REPOSITORY-LOCAL SSH CONFIGURATION
If you need special SSH configuration parameters, you can create a file called .ssh_config (or whatever
file name you have in the $CHAKE_SSH_CONFIG environment variable, see below for details) in at the root
of your repository, and chake will use it when calling ssh.

LOGGING IN TO A HOST
To easily login to one of your host, just run rake login:$HOSTNAME. This will automatically use the
repository-local SSH configuration as above so you don't have to type -F .ssh_config all the time.

RUNNING ALL SSH INVOCATIONS WITH SOME PREFIX COMMAND
Some times, you will also want or need to prefix your SSH invocations with some prefix command in order
to e.g. tunnel it through some central exit node. You can do this by setting $CHAKE_SSH_PREFIX on your
environment. Example:

CHAKE_SSH_PREFIX=tsocks rake converge

The above will make all SSH invocations to all hosts be called as tsocks ssh [...]

CONVERGING LOCAL HOST
If you want to manage your local workstation with chake, you can 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, you can use the conventional rake converge:thunderbolt, or
the special target rake local.

When converging all nodes, chake will skip nodes that are declared with the local:// connection and 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 will be skipped, and vice-versa.

ACCESSING NODE DATA FROM YOUR OWN TASKS
It's often useful to be able to run arbitrary commands against the data you have about nodes. You can use
the Chake.nodes for that. For example, if you want to geolocate each of yours 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 e.g. exclude large  files  from  being  upload  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 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.