pocketknife 0.0.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.yardopts

@@ -0,0 +1 @@
+--main README.md --no-private --protected

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+gem "archive-tar-minitar", "~> 0.5.0"
+gem "rye", "~> 0.9.0"
+
+group :development do
+  gem "bluecloth", "~> 2.1.0"
+  gem "rspec", "~> 2.3.0"
+  gem "yard", "~> 0.6.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.0"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,52 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    annoy (0.5.6)
+      highline (>= 1.5.0)
+    archive-tar-minitar (0.5.2)
+    bluecloth (2.1.0)
+    diff-lcs (1.1.2)
+    drydock (0.6.9)
+    git (1.2.5)
+    highline (1.6.1)
+    jeweler (1.6.0)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    net-scp (1.0.4)
+      net-ssh (>= 1.99.1)
+    net-ssh (2.1.4)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    rye (0.9.4)
+      annoy
+      highline (>= 1.5.1)
+      net-scp (>= 1.0.2)
+      net-ssh (>= 2.0.13)
+      sysinfo (>= 0.7.3)
+    storable (0.8.7)
+    sysinfo (0.7.3)
+      drydock
+      storable
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  archive-tar-minitar (~> 0.5.0)
+  bluecloth (~> 2.1.0)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.0)
+  rcov
+  rspec (~> 2.3.0)
+  rye (~> 0.9.0)
+  yard (~> 0.6.0)

data/LICENSE.txt

@@ -0,0 +1,23 @@
+http://www.opensource.org/licenses/mit-license.php
+
+The MIT License
+
+Copyright (c) 2011 Igal Koshevoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+pocketknife
+===========
+
+`pocketknife` is a devops tool for managing computers running `chef-solo`, powered by [Opscode Chef](http://www.opscode.com/chef/).
+
+Using `pocketknife`, you create a project that describes the configuration of your computers and then deploy it to bring them to their intended state.
+
+With `pocketknife`, you don't need to setup or manage a specialized `chef-server` node or rely on an unreliable network connection to a distant hosted service whose security you don't control, deal with managing `chef`'s security keys, or deal with manually synchronizing data with the `chef-server` datastore.
+
+With `pocketknife`, all of your cookbooks, roles and nodes are stored in easy-to-use files that you can edit, share, backup and version control with tools you already have.
+
+Comparisons
+-----------
+
+Why create another tool?
+
+* `knife` is included with `chef` and is primarily used for managing client-server nodes. The `pocketknife` name plays off this by virtue that it's a smaller, more personal way of managing nodes.
+* `chef-client` is included with `chef`, but you typically need to install another node to act as a `chef-server`, which takes more resources and effort. Using `chef` in client-server mode provides benefits like network-wide databags and pull-based updates, but if you can live without these, `pocketknife` can save you a lot of effort.
+* `chef-solo` is included as part of `chef`, and `pocketknife` uses it. However, `chef-solo` is a low-level tool, and creating and deploying all the files it needs is a significant chore. It also provides no way of deploying or managing your shared and node-specific configuration files. `pocketknife` provides all the missing functionality for creating, managing and deploying, so you don't have to use `chef-solo` directly.
+* `littlechef` is the inspiration for `pocketknife`, it's a great project that I've contributed to and you should definitely [evaluate it](https://github.com/tobami/littlechef). I feel that `pocketknife` offers a more robust, repeatable and automated mechanism for deploying remote nodes; has better documentation, default behavior and command-line support; has good tests and a clearer, more maintainable design; and is written in Ruby so you use the same stack as `chef`.
+
+Usage
+-----
+
+Install the software on the machine you'll be running `pocketknife` on, this is a computer that will deploy configurations to other computers:
+
+* Install Ruby: http://www.ruby-lang.org/
+* Install Rubygems: http://rubygems.org/
+* Install `pocketknife`: `gem install pocketknife`
+
+Create a new *project*, a special directory that will contain your configuration files. For example, create the `swa` project directory by running:
+
+    pocketknife --create swa
+
+Go into your new *project* directory:
+
+    cd swa
+
+Create cookbooks in the `cookbooks` directory that describe how your computers should be configured. These are standard `chef` cookbooks, like the [opscode/cookbooks](https://github.com/opscode/cookbooks). For example, download a copy of [opscode/cookbooks/ntp](https://github.com/opscode/cookbooks/tree/master/ntp) as `cookbooks/ntp`.
+
+Override cookbooks in the `site-cookbooks` directory. This has the same structure as `cookbooks`, but any files you put here will override the contents of `cookbooks`. This is useful for storing the original code of a third-party cookbook in `cookbooks` and putting your customizations in `site-cookbooks`.
+
+Optionally define roles in the `roles` directory that describe common behavior and attributes of your computers using JSON syntax using [chef's documentation](http://wiki.opscode.com/display/chef/Roles#Roles-AsJSON). For example, define a role called `ntp_client` by creating a file called `roles/ntp_client.json` with this content:
+
+    {
+      "name": "ntp_client",
+      "chef_type": "role",
+      "json_class": "Chef::Role",
+      "run_list": [
+        "recipe[ntp]"
+      ],
+      "override_attributes": {
+        "ntp": {
+          "servers": ["0.pool.ntp.org", "1.pool.ntp.org", "2.pool.ntp.org", "3.pool.ntp.org"]
+        }
+      }
+    }
+
+Define a new node using the `chef` JSON syntax for [runlist](http://wiki.opscode.com/display/chef/Setting+the+run_list+in+JSON+during+run+time) and [attributes](http://wiki.opscode.com/display/chef/Attributes). For example, to define a node with the hostname `henrietta.swa.gov.it` create the `nodes/henrietta.swa.gov.it.json` file, and add the contents below so it uses the `ntp_client` role and overrides its attributes to use a local NTP server:
+
+    {
+      "run_list": [
+        "role[ntp_client]"
+      ],
+      "override_attributes": {
+        "ntp": {
+          "servers": ["0.it.pool.ntp.org", "1.it.pool.ntp.org", "2.it.pool.ntp.org", "3.it.pool.ntp.org"]
+        }
+      }
+    }
+
+Operations on remote nodes will be performed using SSH. You should consider [configuring ssh-agent](http://mah.everybody.org/docs/ssh) so you don't have to keep typing in your passwords.
+
+Finally, deploy your configuration to the remote machine and see the results. For example, lets deploy the above configuration to the `henrietta.swa.gov.it` host, which can be abbreviated as `henrietta` when calling `pocketknife`:
+
+    pocketknife henrietta
+
+When deploying a configuration to a node, `pocketknife` will check whether Chef and its dependencies are installed. It something is missing, it will prompt you for whether you'd like to have it install them automatically.
+
+To always install Chef and its dependencies when they're needed, without prompts, use the `-i` option, e.g. `pocketknife -i henrietta`. Or to never install Chef and its dependencies, use the `-I` option, which will cause the program to quit with an error rather than prompting if Chef or its dependencies aren't installed.
+
+If something goes wrong while deploying the configuration, you can display verbose logging from `pocketknife` and Chef by using the `-v` option. For example, deploy the configuration to `henrietta` with verbose logging:
+
+    pocketknife -v henrietta
+
+If you really need to debug on the remote machine, you may be interested about some of the commands and paths:
+
+* `chef-solo-apply` (/usr/local/sbin/chef-solo-apply) will apply the configuration to the machine. You can specify `-l debug` to make it more verbose. Run it with `-h` for help.
+* `csa` (/usr/local/sbin/csa) is a shortcut for `chef-solo-apply` and accepts the same arguments.
+* `/etc/chef/solo.rb` contains the `chef-solo` configuration settings.
+* `/etc/chef/node.json` contains the node-specific configuration, like the `runlist` and attributes.
+* `/var/local/pocketknife` contains the `cookbooks`, `site-cookbooks` and `roles` describing your configuration.
+
+Contributing
+------------
+
+This software is published as open source at https://github.com/igal/pocketknife
+
+You can view and file issues for this software at https://github.com/igal/pocketknife/issues
+
+If you'd like to contribute code or documentation:
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+* Submit a pull request using github, this makes it easy for me to incorporate your code.
+
+Copyright
+---------
+
+Copyright (c) 2011 Igal Koshevoy. See `LICENSE.txt` for further details.

data/Rakefile

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+load './lib/pocketknife/version.rb'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.version = Pocketknife::Version::STRING
+  gem.name = "pocketknife"
+  gem.homepage = "http://github.com/igal/pocketknife"
+  gem.license = "MIT"
+  gem.summary = %Q{pocketknife is a tool for managing chef-solo nodes.}
+  gem.description = %Q{pocketknife is a tool for managing chef-solo nodes.}
+  gem.email = "igal+pocketknife@pragmaticraft.com"
+  gem.authors = ["Igal Koshevoy"]
+  gem.executables += %w[
+    pocketknife
+  ]
+  gem.files += %w[
+    Gemfile
+    LICENSE.txt
+    README.md
+    Rakefile
+    lib/*
+    spec/*
+  ]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/bin/pocketknife

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'pathname'
+
+# Use local files if executed from a source code checkout directory, useful for development. 
+lib = Pathname.new($0).expand_path.dirname + '..' + 'lib' + 'pocketknife.rb'
+if lib.exist?
+  require 'rubygems'
+  $LOAD_PATH.unshift(lib.dirname)
+end
+
+require 'pocketknife'
+
+Pocketknife::cli(ARGV)

data/lib/pocketknife.rb

@@ -0,0 +1,252 @@
+# Standard libraries
+require "pathname"
+require "fileutils"
+
+# Gem libraries
+require "archive/tar/minitar"
+require "rye"
+
+# Related libraries
+require "pocketknife/errors"
+require "pocketknife/node"
+require "pocketknife/node_manager"
+require "pocketknife/version"
+
+# = Pocketknife
+#
+# == About
+#
+# Pocketknife is a devops tool for managing computers running <tt>chef-solo</tt>. Using Pocketknife, you create a project that describes the configuration of your computers and then apply it to bring them to the intended state.
+#
+# For information on using the +pocketknife+ tool, please see the {file:README.md README.md} file. The rest of this documentation is intended for those writing code using the Pocketknife API.
+#
+# == Important methods
+#
+# * {cli} runs the command-line interpreter, whichi in turn executes the methods below.
+# * {#initialize} creates a new Pocketknife instance.
+# * {#create} creates a new project.
+# * {#deploy} deploys configurations to nodes, which uploads and applies.
+# * {#upload} uploads configurations to nodes.
+# * {#apply} applies existing configurations to nodes.
+# * {#node} finds a node to upload or apply configurations.
+#
+# == Important classes
+#
+# * {Pocketknife::Node} describes how to upload and apply configurations to nodes, which are remote computers.
+# * {Pocketknife::NodeManager} finds, checks and manages nodes.
+# * {Pocketknife::NodeError} describes errors encountered when using nodes.
+class Pocketknife
+  # Runs the interpreter using arguments provided by the command-line. Run <tt>pocketknife -h</tt> or review the code below to see what command-line arguments are accepted.
+  #
+  # Example:
+  #   # Display command-line help:
+  #   Pocketknife.cli('-h')
+  #
+  # @param [Array<String>] args A list of arguments from the command-line, which may include options (e.g. <tt>-h</tt>).
+  def self.cli(args)
+    pocketknife = Pocketknife.new
+
+    OptionParser.new do |parser|
+      parser.banner = <<-HERE
+USAGE: pocketknife [options] [nodes]
+
+EXAMPLES:
+  # Create a new project called PROJECT
+  pocketknife -c PROJECT
+
+  # Apply configuration to a node called NODE
+  pocketknife NODE
+
+OPTIONS:
+      HERE
+
+      options = {}
+
+      parser.on("-c", "--create PROJECT", "Create project") do |name|
+        pocketknife.create(name)
+        return
+      end
+
+      parser.on("-V", "--version", "Display version number") do |name|
+        puts "Pocketknife #{Pocketknife::Version::STRING}"
+        return
+      end
+
+      parser.on("-v", "--verbose", "Display detailed status information") do |name|
+        pocketknife.verbosity = true
+      end
+
+      parser.on("-q", "--quiet", "Display minimal status information") do |v|
+        pocketknife.verbosity = false
+      end
+
+      parser.on("-u", "--upload", "Upload configuration, but don't apply it") do |v|
+        options[:upload] = true
+      end
+
+      parser.on("-a", "--apply", "Runs cheef to apply already-uploaded configuration") do |v|
+        options[:apply] = true
+      end
+
+      parser.on("-i", "--install", "Install Chef automatically") do |v|
+        pocketknife.can_install = true
+      end
+
+      parser.on("-I", "--noinstall", "Don't install Chef automatically") do |v|
+        pocketknife.can_install = false
+      end
+
+      begin
+        arguments = parser.parse!
+      rescue OptionParser::MissingArgument => e
+        puts parser
+        puts
+        puts "ERROR: #{e}"
+        exit -1
+      end
+
+      nodes = arguments
+
+      if nodes.empty?
+        puts parser
+        puts
+        puts "ERROR: No nodes specified."
+        exit -1
+      end
+
+      begin
+        if options[:upload]
+          pocketknife.upload(nodes)
+        end
+
+        if options[:apply]
+          pocketknife.apply(nodes)
+        end
+
+        if not options[:upload] and not options[:apply]
+          pocketknife.deploy(nodes)
+        end
+      rescue NodeError => e
+        puts "! #{e.node}: #{e}"
+        exit -1
+      end
+    end
+  end
+
+  # Returns the software's version.
+  #
+  # @return [String] A version string.
+  def self.version
+    return "0.0.1"
+  end
+
+  # Amount of detail to display? true means verbose, nil means normal, false means quiet.
+  attr_accessor :verbosity
+
+  # Can chef and its dependencies be installed automatically if not found? true means perform installation without prompting, false means quit if chef isn't available, and nil means prompt the user for input.
+  attr_accessor :can_install
+
+  # {Pocketknife::NodeManager} instance.
+  attr_accessor :node_manager
+
+  # Instantiate a new Pocketknife.
+  #
+  # @option [Boolean] verbosity Amount of detail to display. +true+ means verbose, +nil+ means normal, +false+ means quiet.
+  # @option [Boolean] install Install Chef and its dependencies if needed? +true+ means do so automatically, +false+ means don't, and +nil+ means display a prompt to ask the user what to do.
+  def initialize(opts={})
+    self.verbosity   = opts[:verbosity]
+    self.can_install = opts[:install]
+
+    self.node_manager = NodeManager.new(self)
+  end
+
+  # Display a message, but only if it's important enough
+  #
+  # @param [String] message The message to display.
+  # @param [Boolean] importance How important is this? +true+ means important, +nil+ means normal, +false+ means unimportant.
+  def say(message, importance=nil)
+    display = \
+      case self.verbosity
+      when true
+        true
+      when nil
+        importance != false
+      else
+        importance == true
+      end
+
+    if display
+      puts message
+    end
+  end
+
+  # Creates a new project directory.
+  #
+  # @param [String] project The name of the project directory to create.
+  # @yield [path] Yields status information to the optionally supplied block.
+  # @yieldparam [String] path The path of the file or directory created.
+  def create(project)
+    self.say("* Creating project in directory: #{project}")
+
+    dir = Pathname.new(project)
+
+    %w[
+      nodes
+      roles
+      cookbooks
+      site-cookbooks
+    ].each do |subdir|
+      target = (dir + subdir)
+      unless target.exist?
+        FileUtils.mkdir_p(target)
+        self.say("- #{target}/")
+      end
+    end
+
+    return true
+  end
+
+  # Returns a Node instance.
+  #
+  # @param[String] name The name of the node.
+  def node(name)
+    return node_manager.find(name)
+  end
+
+  # Deploys configuration to the nodes, calls {#upload} and {#apply}.
+  #
+  # @params[Array<String>] nodes A list of node names.
+  def deploy(nodes)
+    node_manager.assert_known(nodes)
+
+    Node.prepare_upload do
+      for node in nodes
+        node_manager.find(node).deploy
+      end
+    end
+  end
+
+  # Uploads configuration information to remote nodes.
+  #
+  # @param [Array<String>] nodes A list of node names.
+  def upload(nodes)
+    node_manager.assert_known(nodes)
+
+    Node.prepare_upload do
+      for node in nodes
+        node_manager.find(node).upload
+      end
+    end
+  end
+
+  # Applies configurations to remote nodes.
+  #
+  # @param [Array<String>] nodes A list of node names.
+  def apply(nodes)
+    node_manager.assert_known(nodes)
+
+    for node in nodes
+      node_manager.find(node).apply
+    end
+  end
+end