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.

       Example:

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

   ENCRYPTED FILES
       Any files ending matching *.gpg and *.asc will be decrypted with GnuPG before  being  sent
       to  the  node (for the configuration management tools that required files to be sent). 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.

NAME

SYNOPSIS

DESCRIPTION

SUPPORTED CONFIGURATION MANAGERS.

CREATING THE REPOSITORY

MANAGING NODES

PREPARINGS NODES TO BE MANAGED

CHECKING CONNECTIVITY AND INITIAL HOST SETUP

APPLYING CONFIGURATION

WRITING CONFIGURATION MANAGEMENT CODE

THE NODE BOOTSTRAPPING PROCESS

NODE URLS

EXTRA FEATURES

ENVIRONMENT VARIABLES

SEE ALSO