bke_chef-rundeck 2.2.2

data/changelog.md

@@ -0,0 +1,75 @@
+# Changelog 2.2.0
+## Release Summary
+### Deprecation Warning!
+If you have been relying on chef-rundeck squashing node environment, role and run list data into the 'tags' field, be aware that this is going to change.  Rundeck has supported custom resource attributes in node filters for quite some time now.  If you rely on the current behavior, please consider pinning against chef-rundeck 2.x.
+  * Better data validation on chef-rundeck.json.
+  * Expanded functional test coverage.
+  * Better documentation.
+
+# Changelog 2.1.0
+## Release Summary
+* As some of the others have mentioned partial search is the way to go. We have seen 80%-90% improvement in performance. In addition we have introduced caching via a tmp file, this allows large chef node data not to remain in memory and slow down responses. Sinatra also will now run in env 'production' by default.
+
+### New CLI params:
+
+  * --env (production/development) (default: production)
+  * --partial-search (true/false) - Only supported when using Chef Server 11 (default: false)
+* --timeout (cache timeout in seconds) (default: 30)
+
+# Changelog - 2.0.0
+## Release Summary
+  * Added support for search defined project resource definitions
+  * Added support for Rundeck 2.0 and custom attributes
+* Added support for Windows Systems in Rundeck node configuration (via overthere-winrm)
+  * Refactor xml node generation  
+# Changelog - 1.0.1
+## Release Summary
+  * Fixes to allow us to test Chef 11 and Chef 10 in Travis, based on the Chefspec way.
+# Changelog - 1.0.0
+## Release Summary
+  * chef-rundeck is under new management (GitHub org name is 'oswaldlabs').  We use it at work in production and we are serious about maintaining it.  If you have suggestions or code that you would like to contribute, particularly if it improves our test coverage, please send us a pull request or open a GitHub issue.
+  * A basic functioning test suite that builds under Travis-CI and Ruby 1.9.2/1.9.3, connects to a Hosted Chef organization and generates a simple Rundeck resource model.  ("rake spec" to test it for yourself!)
+  * chef-rundeck should now drop a pidfile at startup and remove it during normal shutdown.
+* Chef node tags now appear as tags in the generated Rundeck resource model.  (Thanks, giorgio-v!)
+
+## Detailed Changes
+  * [Tags from node](https://github.com/oswaldlabs/chef-rundeck/commit/d83373be4b903595d4db30d8c41a0a3bad340994) (giorgio-v)
+  * [Initial attempt at Travis-ification.](https://github.com/oswaldlabs/chef-rundeck/commit/f64bdfce1dd12368f8c2364dd29b8d8acc63c606) (Steven Wagner)
+  * [Slight refactoring for Ruby 1.9/RSpec + Travis ...](https://github.com/oswaldlabs/chef-rundeck/commit/89b1e22ebd7b611aa1ce8f28d1364a24cbddb814) (Steven Wagner)
+  * [Added jeweler dependency to make Travis happy.](https://github.com/oswaldlabs/chef-rundeck/commit/4cad7308687b4c2964474421b7f0028123bffad6) (Steven Wagner)
+  * [New fancy markdown README, ditch old busted RDoc README.](https://github.com/oswaldlabs/chef-rundeck/commit/df015dbd7771c331e76898c30e90102868793f28) (Steven Wagner)
+  * [Sorry, Travis, adding the development gems back in.](https://github.com/oswaldlabs/chef-rundeck/commit/659f413872c5923cf534aa964da92e9c2b0bda5b) (Steven Wagner)
+  * [Added new Authors](https://github.com/oswaldlabs/chef-rundeck/commit/de29b9c2c516a1bae1521a702b45233383a30231) (Brian Scott)
+  * [Update Bundle](https://github.com/oswaldlabs/chef-rundeck/commit/2f83030f879c47a638037f24de74f6b5e9a270a1) (Brian Scott)
+  * [Removed task check deps](https://github.com/oswaldlabs/chef-rundeck/commit/26c1599dc2fe0c3865e80ca55abffee50e648033) (Brian Scott)
+  * [Attempt at adding specs](https://github.com/oswaldlabs/chef-rundeck/commit/3d108b773ad0c34423060e508d275087693c0cb9) (Brian Scott)
+  * [Adding client.rb and client key for a test Chef org.](https://github.com/oswaldlabs/chef-rundeck/commit/27aae944b4cc8cc58ef6fbb34dbcba9eb375d2d1) (Steven Wagner)
+  * [Simple, stupid script for use in setting up a Travis worker.](https://github.com/oswaldlabs/chef-rundeck/commit/58b02ff7eb0378e7c20f412a85537625018a3131) (Steven Wagner)
+  * [Added Chef client configuration install script.](https://github.com/oswaldlabs/chef-rundeck/commit/5d9ede2bb5c2736b10ba5401636a100dac9e9416) (Steven Wagner)
+  * [Script didn't get executed at the proper time. Let's try after_install -> before_script ...](https://github.com/oswaldlabs/chef-rundeck/commit/d27eed173abc94469d83117999a31469af7500f2) (Steven Wagner)
+  * [rdoc -> markdown for README, new email.](https://github.com/oswaldlabs/chef-rundeck/commit/7d1b27844c9e8a2f74e456a1524cfabebc4d4f8b) (Steven Wagner)
+  * [Paths now relative to root of repo.](https://github.com/oswaldlabs/chef-rundeck/commit/92cf6ae73dd84ef0393dbf45a24ff9f2a5f3078c) (Steven Wagner)
+  * [We can sudo!](https://github.com/oswaldlabs/chef-rundeck/commit/74533fd4f2d0264ccd488a93ed9a746dc0d517c1) (Steven Wagner)
+  * [Ensuring that :node_name is set.](https://github.com/oswaldlabs/chef-rundeck/commit/de1e858d431492cc1a965a511ecd8f7c2a70b5ba) (Steven Wagner)
+  * [Debug output](https://github.com/oswaldlabs/chef-rundeck/commit/e1eac806cba0207415d41179ddab18b3f22ae5f3) (Steven Wagner)
+  * [Modifying stuff to work with Travis.](https://github.com/oswaldlabs/chef-rundeck/commit/9dbba97c7bd4d68f3b1413387217125fc7881f00) (Steven Wagner)
+  * [configure -> config_file, oops](https://github.com/oswaldlabs/chef-rundeck/commit/ecc076674236fbd806b8f4c749dcf80fea6834ae) (Steven Wagner)
+  * [Fixed failed spec in spec_helper](https://github.com/oswaldlabs/chef-rundeck/commit/5940e4fbeadc2fa486ce84d518fb538e7592b5c5) (Brian Scott)
+  * [Spec test](https://github.com/oswaldlabs/chef-rundeck/commit/9a5fc66deb0513889de53a372b73031c99d5a6b8) (Brian Scott)
+  * [Added default web UI value (Hosted Chef) to pass tests.](https://github.com/oswaldlabs/chef-rundeck/commit/6c49cd1b143283bb4637f66bcbcd0feec21e4575) (Steven Wagner)
+  * [Adding some chef-rundeck-specific config values.](https://github.com/oswaldlabs/chef-rundeck/commit/6d0ae6e81fd890dad9b5388a559dfd6bbcb2d56f) (Steven Wagner)
+  * [Drop a pidfile at startup. Should nuke it if the app stops.  Appends port number for multi-tenant deployments.](https://github.com/oswaldlabs/chef-rundeck/commit/af63dcf91260d0f2c3f4882d14f71f0cffb4f838) (Steven Wagner)
+  * [Merge pull request #21 from leftathome/manage_pidfile](https://github.com/oswaldlabs/chef-rundeck/commit/98f30ddf318f61a70c4a824c2896da96c7435473) (Brian Scott)
+  * [default node_name to fqdn. fixes #11](https://github.com/oswaldlabs/chef-rundeck/commit/efd6e1aec07b749dd7b288141dcf349bad49ced1) (Joseph Anthony Pasquale Holsten)
+  * [Load config in test](https://github.com/oswaldlabs/chef-rundeck/commit/83c2d9b6558f02877b5a86b1ff8419b3d3b118a5) (Joseph Anthony Pasquale Holsten)
+  * [Set ChefRundeck.username in test](https://github.com/oswaldlabs/chef-rundeck/commit/3e7e7632a1e39b95124221ba0fd9d7e69373dc5f) (Joseph Anthony Pasquale Holsten)
+  * [Set web_ui_url in test](https://github.com/oswaldlabs/chef-rundeck/commit/e1a24b232522dfda24d52b1701152fd3958c0ca5) (Joseph Anthony Pasquale Holsten)
+  * [Merge pull request #18 from simplymeasured/default-to-fqdn-for-node-name](https://github.com/oswaldlabs/chef-rundeck/commit/ecf4833ad067f983db24910485bfff0519dddc5c) (Brian Scott)
+  * [Added Nokogiri development dependency. Used for XML validation in testing.](https://github.com/oswaldlabs/chef-rundeck/commit/91dfff2dcaa431582155f8eab0217bcd1b49854d) (Steven Wagner)
+  * [Added simple test to validate XML output.](https://github.com/oswaldlabs/chef-rundeck/commit/eec5573c89dac33e1aea45f2f41319aa9218d4b5) (Steven Wagner)
+  * [Bump chef to 11.6.0.](https://github.com/oswaldlabs/chef-rundeck/commit/7c0146c72d46c033b20917a92eb9cee7214603eb) (Steven Wagner)
+  * [Merge pull request #17 from giorgio-v/chef-tags](https://github.com/oswaldlabs/chef-rundeck/commit/c1333410a4b9ea70c30574727d11557da5d71d7b) (Brian Scott)
+  * [Merge pull request #22 from leftathome/travis_fixes](https://github.com/oswaldlabs/chef-rundeck/commit/12a8c79ecfa25c012d98a6202c87369c1ca0dc55) (Brian Scott)
+  * [Use Chef REST API](https://github.com/oswaldlabs/chef-rundeck/commit/d122c213680b8c3ce3afa85a316d7849e72c5c48) (Joseph Martin)
+  * [Merge pull request #23 from hugespoon/rest-api](https://github.com/oswaldlabs/chef-rundeck/commit/aa4530cf765afdf01d108562a78961fc90dbe19d) (Brian Scott)
+  * [Fix spec target so that it works from command-line.](https://github.com/oswaldlabs/chef-rundeck/commit/aee31730f6f2520eda2ec6265a7c8bf0bd251879) (Steven Wagner)

data/chef-rundeck.gemspec

@@ -0,0 +1,68 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "bke_chef-rundeck"
+  s.version = "2.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Adam Jacob", "Brian Scott", "Steven Wagner", "Peter Crossley"]
+  s.date = "2011-11-07"
+  s.description = "Provides a resource endpoint for RunDeck from a Chef Server"
+  s.email = "brainscott@gmail.com"
+  s.executables = ["chef-rundeck"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+  s.license = 'Apache License 2.0 (Apache-2.0)'
+  s.files = [
+    ".document",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "Rakefile",
+    "bin/chef-rundeck",
+    "lib/chef-rundeck.rb",
+    "lib/partial_search.rb",
+    "spec/chef-rundeck_spec.rb",
+    "spec/spec.opts",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "http://github.com/oswaldlabs/chef-rundeck"
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Integrates Chef with RunDeck"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sinatra>, [">= 0"])
+      s.add_runtime_dependency(%q<chef>, [">= 0"])
+      s.add_runtime_dependency(%q<mixlib-cli>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<nokogiri>, [">= 0"])
+    else
+      s.add_dependency(%q<sinatra>, [">= 0"])
+      s.add_dependency(%q<chef>, [">= 0"])
+      s.add_dependency(%q<mixlib-cli>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<nokogiri>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, [">= 0"])
+    s.add_dependency(%q<chef>, [">= 0"])
+    s.add_dependency(%q<mixlib-cli>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<nokogiri>, [">= 0"])
+  end
+end

data/gemfiles/Gemfile.chef-10

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gem 'jeweler'
+gem 'chef', '~> 10'
+gemspec :path => '..'

data/gemfiles/Gemfile.chef-11

@@ -0,0 +1,5 @@
+source "https://rubygems.org/"
+
+gem 'jeweler'
+gem 'chef', '~> 11'
+gemspec :path => '..'

data/lib/bke_chef-rundeck.rb

@@ -0,0 +1,327 @@
+#
+# Copyright 2010, Opscode, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'sinatra/base'
+require 'chef'
+require 'chef/node'
+require 'chef/mixin/xml_escape'
+require 'chef/role'
+require 'chef/environment'
+require 'chef/data_bag'
+require 'chef/data_bag_item'
+require 'partial_search'
+
+REQUIRED_ATTRS = [ :kernel, :fqdn, :platform, :platform_version ]
+
+class MissingAttribute < StandardError
+  attr_reader :name
+  def initialize(name)
+    @name = name
+  end
+end
+
+class ChefRundeck < Sinatra::Base
+
+  include Chef::Mixin::XMLEscape
+
+  class << self
+    attr_accessor :config_file
+    attr_accessor :username
+    attr_accessor :web_ui_url
+    attr_accessor :api_url
+    attr_accessor :client_key
+    attr_accessor :project_config
+    attr_accessor :cache_timeout
+    attr_accessor :partial_search
+
+    def configure
+      Chef::Config.from_file(ChefRundeck.config_file)
+      Chef::Log.level = Chef::Config[:log_level]
+
+      unless ChefRundeck.api_url
+        ChefRundeck.api_url = Chef::Config[:chef_server_url]
+      end
+
+      unless ChefRundeck.client_key
+        ChefRundeck.client_key = Chef::Config[:client_key]
+      end
+
+
+      if (File.exists?(ChefRundeck.project_config)) then
+        Chef::Log.info("Using JSON project file #{ChefRundeck.project_config}")
+        projects = File.open(ChefRundeck.project_config, "r") { |f| JSON.parse(f.read) }
+        projects.keys.each do | project |
+          get "/#{project}" do
+            content_type 'text/xml'
+            Chef::Log.info("Loading nodes for /#{project}")
+            # TODO: Validate project data before rendering the document?
+            send_file build_project project, projects[project]['pattern'], (projects[project]['username'].nil? ? ChefRundeck.username : projects[project]['username']), (projects[project]['hostname'].nil? ? "fqdn" : projects[project]['hostname']), projects[project]['attributes']
+          end
+          cache_file = "#{Dir.tmpdir}/chef-rundeck-#{project}.xml"
+          at_exit { File.delete(cache_file) if File.exist?(cache_file) }
+        end
+      end
+      
+      get '/' do
+        content_type 'text/xml'
+        Chef::Log.info("Loading all nodes for /")
+        send_file build_project
+      end
+      
+      cache_file = "#{Dir.tmpdir}/chef-rundeck-default.xml"
+      at_exit { File.delete(cache_file) if File.exist?(cache_file) }
+    end
+  end
+
+  def build_project (project="default", pattern="*:*", username=ChefRundeck.username, hostname="fqdn", custom_attributes=nil)
+    response = nil
+    begin
+
+      # file is too new use it again
+      if (File.exists?("#{Dir.tmpdir}/chef-rundeck-#{project}.xml") && (Time.now - File.atime("#{Dir.tmpdir}/chef-rundeck-#{project}.xml") < ChefRundeck.cache_timeout)) then 
+        return "#{Dir.tmpdir}/chef-rundeck-#{project}.xml"
+      end
+
+      results = []
+      if ChefRundeck.partial_search then
+        keys = { 'name' => ['name'],
+                 'kernel_machine' => [ 'kernel', 'machine' ],
+                 'kernel_os' => [ 'kernel', 'os' ],
+                 'fqdn' => [ 'fqdn' ],
+                 'run_list' => [ 'run_list' ],
+                 'roles' => [ 'roles' ],
+                 'recipes' => [ 'recipes' ],
+                 'chef_environment' => [ 'chef_environment' ],
+                 'platform' => [ 'platform'],
+                 'platform_version' => [ 'platform_version' ],
+                 'tags' => [ 'tags' ],
+                 'hostname' => [hostname]
+               }  
+        if !custom_attributes.nil? then
+          custom_attributes.each do |attr|
+          attr_name = attr.gsub('.', '_')
+          attr_value = attr.split('.')
+          keys[attr_name] = attr_value
+          end
+        end
+        # do search
+        Chef::Log.info("partial search started (project: '#{project}')")
+        results = partial_search(:node,pattern, :keys => keys)
+        Chef::Log.info("partial search finshed (project: '#{project}', count: #{results.length})")
+      else 
+        q = Chef::Search::Query.new
+        Chef::Log.info("search started (project: '#{project}')")
+        results = q.search("node",pattern)[0]
+        Chef::Log.info("search finshed (project: '#{project}', count: #{results.length})")
+        results = convert_results(results, hostname, custom_attributes)
+      end
+      
+      response = File.open("#{Dir.tmpdir}/chef-rundeck-#{project}.xml", 'w')
+      response.write '<?xml version="1.0" encoding="UTF-8"?>'
+      response.write '<!DOCTYPE project PUBLIC "-//DTO Labs Inc.//DTD Resources Document 1.0//EN" "project.dtd">'
+      response.write '<project>'
+
+      Chef::Log.info("building nodes (project: '#{project}')")
+      failed = 0
+      results.each do |node|
+        begin
+          # validate the node
+          begin
+            node_is_valid? node
+          rescue ArgumentError => ae
+            Chef::Log.warn("invalid node element: #{ae}")
+            failed = failed + 1
+            next
+          end
+          
+          #write the node to the project
+          response.write build_node(node, username, hostname, custom_attributes)
+        rescue Exception => e
+          Chef::Log.error("=== could not generate xml for #{node}:  #{e.message}")
+          Chef::Log.debug(e.backtrace.join('\n'))
+        end
+      end
+      Chef::Log.info("nodes complete (project: '#{project}', total: #{results.length - failed}, failed: #{failed})")
+      
+      response.write "</project>"
+      Chef::Log.debug(response)
+    ensure
+      response.close unless response == nil
+    end
+    return response.path
+  end
+end
+
+def build_node (node, username, hostname, custom_attributes)
+      #--
+      # Certain features in Rundeck require the osFamily value to be set to 'unix' to work appropriately. - SRK
+      #++
+      data = ''
+      os_family = node['kernel_os'] =~ /winnt|windows/i ? 'winnt' : 'unix'
+      nodeexec = node['kernel_os'] =~ /winnt|windows/i ? "node-executor=\"overthere-winrm\"" : ''
+      data << <<-EOH
+<node name="#{xml_escape(node['fqdn'])}" #{nodeexec} 
+      type="Node" 
+      description="#{xml_escape(node['name'])}"
+      osArch="#{xml_escape(node['kernel_machine'])}"
+      osFamily="#{xml_escape(os_family)}"
+      osName="#{xml_escape(node['platform'])}"
+      osVersion="#{xml_escape(node['platform_version'])}"
+      roles="#{xml_escape(node['roles'].join(','))}"
+      recipes="#{xml_escape(node['recipes'].join(','))}"
+      tags="#{xml_escape([ node['roles'], node['recipes'], node['chef_environment'], node['tags']].flatten.join(","))}"
+      environment="#{xml_escape(node['chef_environment'])}"
+      username="#{xml_escape(username)}"
+      hostname="#{xml_escape(node['hostname'])}"
+      editUrl="#{xml_escape(ChefRundeck.web_ui_url)}/nodes/#{xml_escape(node['name'])}/edit" #{custom_attributes.nil? ? '/': ''}>
+EOH
+     if !custom_attributes.nil? then
+       custom_attributes.each do |attr|
+         attr_name = attr
+         attr_value = node[attr.gsub('.','_')]
+         data << <<-EOH
+      <attribute name="#{attr_name}"><![CDATA[#{attr_value}]]></attribute>
+EOH
+       end
+       data << "</node>"
+     end
+
+  return data
+end
+
+def get_custom_attr (obj, params)
+  value = obj
+  Chef::Log.debug("loading custom attributes for node: #{obj['name']} with #{params}")
+  params.each do |p|   
+    value = value[p.to_sym]
+    if value.nil? then
+      break
+    end
+  end
+  return value.nil? ? "" : value.to_s
+end
+
+# Convert results to be compatiable with Chef 11 format
+def convert_results(results, hostname, custom_attributes)
+ new_results = []
+ results.each do |node|
+   n = {}
+   n['name'] = node.name
+   n['chef_environment'] = node.chef_environment
+   n['run_list'] = node.run_list
+   n['recipes'] = !node.run_list.nil? ? node.run_list.recipes : nil
+   n['roles'] = !node.run_list.nil? ? node.run_list.roles : nil
+   n['fqdn'] = node['fqdn']
+   n['hostname'] = get_custom_attr(node, hostname.split('.'))
+   n['kernel_machine'] = !node['kernel'].nil? ? node['kernel']['machine'] : nil
+   n['kernel_os'] = !node['kernel'].nil? ? node['kernel']['os'] : nil
+   n['platform'] = node['platform']
+   n['platform_version'] = node['platform_version']
+   n['tags'] = node['tags']
+   
+   if !custom_attributes.nil? then
+     custom_attributes.each do |attr|
+       ps_name = attr.gsub('.','_')
+       n[ps_name] = get_custom_attr(node, attr.split('.'))
+     end
+   end
+   new_results << n
+ end 
+ return new_results
+end
+
+
+# Helper def to validate the node 
+def node_is_valid?(node)
+  raise ArgumentError, "#{node} missing 'name'" if !node['name']
+  raise ArgumentError, "#{node} missing 'chef_environment'" if !node['chef_environment']
+  raise ArgumentError, "#{node} missing 'run_list'" if !node['run_list']
+  raise ArgumentError, "#{node} missing 'recipes'" if !node['recipes']
+  raise ArgumentError, "#{node} missing 'roles'" if !node['roles']
+  raise ArgumentError, "#{node} missing 'fqdn'" if !node['fqdn']
+  raise ArgumentError, "#{node} missing 'hostname'" if !node['hostname']
+  raise ArgumentError, "#{node} missing 'kernel.machine'" if !node['kernel_machine']
+  raise ArgumentError, "#{node} missing 'kernel.os'" if !node['kernel_os']
+  raise ArgumentError, "#{node} missing 'platform'" if !node['platform']
+  raise ArgumentError, "#{node} missing 'platform_version'" if !node['platform_version']
+end
+
+
+# partial_search(type, query, options, &block)
+#
+# Searches for nodes, roles, etc. and returns the results.  This method may
+# perform more than one search request, if there are a large number of results.
+#
+# ==== Parameters
+# * +type+: index type (:role, :node, :client, :environment, data bag name)
+# * +query+: SOLR query.  "*:*", "role:blah", "not role:blah", etc.  Defaults to '*:*'
+# * +options+: hash with options:
+# ** +:start+: First row to return (:start => 50, :rows => 100 means "return the
+#               50th through 150th result")
+# ** +:rows+: Number of rows to return.  Defaults to 1000.
+# ** +:sort+: a SOLR sort specification.  Defaults to 'X_CHEF_id_CHEF_X asc'.
+# ** +:keys+: partial search keys.  If this is not specified, the search will
+#             not be partial.
+#
+# ==== Returns
+#
+# This method returns an array of search results.  Partial search results will
+# be JSON hashes with the structure specified in the +keys+ option.  Other
+# results include +Chef::Node+, +Chef::Role+, +Chef::Client+, +Chef::Environment+,
+# +Chef::DataBag+ and +Chef::DataBagItem+ objects, depending on the search type.
+#
+# If a block is specified, the block will be called with each result instead of
+# returning an array.  This method will not block if it returns
+#
+# If start or row is specified, and no block is given, the result will be a
+# triple containing the list, the start and total:
+#
+#     [ [ row1, row2, ... ], start, total ]
+#
+# ==== Example
+#
+#     partial_search(:node, 'role:webserver',
+#                    keys: {
+#                      name: [ 'name' ],
+#                      ip: [ 'amazon', 'ip', 'public' ]
+#                    }
+#     ).each do |node|
+#       puts "#{node[:name]}: #{node[:ip]}"
+#     end
+#
+def partial_search(type, query='*:*', *args, &block)
+  # Support both the old (positional args) and new (hash args) styles of calling
+  if args.length == 1 && args[0].is_a?(Hash)
+    args_hash = args[0]
+  else
+    args_hash = {}
+    args_hash[:sort] = args[0] if args.length >= 1
+    args_hash[:start] = args[1] if args.length >= 2
+    args_hash[:rows] = args[2] if args.length >= 3
+  end
+  # If you pass a block, or have the start or rows arguments, do raw result parsing
+  if Kernel.block_given? || args_hash[:start] || args_hash[:rows]
+    PartialSearch.new.search(type, query, args_hash, &block)
+ 
+  # Otherwise, do the iteration for the end user
+  else
+    results = Array.new
+    PartialSearch.new.search(type, query, args_hash) do |o|
+        results << o
+    end
+     results
+  end
+end