Permalink
Browse files

Modded docs to include new functionality in 0.2.0

  • Loading branch information...
1 parent 4431cd4 commit df2bc15934bd33e5255b734d0d41929da715728a J.B. Zimmerman committed Oct 7, 2011
Showing with 16 additions and 4 deletions.
  1. +16 −4 README.md
View
20 README.md
@@ -1,15 +1,15 @@
knife-audit
========
A knife plugin for determining which cookbooks are in use on which nodes of your Chef server or Opscode organization.
-Allows you to safely maintain a chef cookbook set by determining which cookbooks are currently in use by nodes (included in node runlists).
+Allows you to safely maintain a chef cookbook set by determining which cookbooks are currently in use by nodes - either solely via inclusion in node runlists (available from every node) or via runlist *or* include_recipes (for nodes with knife_audit helper cookbook installed).
Installing knife-audit
-------------------
#### Script install
-Copy the knife-audit script from https://github.com/jbz/knife-audit/blob/master/lib/chef/knife/audit.rb to your .chef/plugins/knife directory.
+Copy the knife-audit script from https://github.com/jbz/knife-audit/blob/master/lib/chef/knife/audit.rb to your .chef/plugins/knife directory. Note that script-installed knife audit will be unable to install the knife_audit helper cookbook for you.
#### Gem install
@@ -25,19 +25,31 @@ knife-audit is available on rubygems.org - if you have that source in your gemrc
Usage
---------------
- knife audit [-s] <COOKBOOK COOKBOOK ...>
+ knife audit [-a|-t] [-s] [-i] <COOKBOOK COOKBOOK ...>
If no cookbooks are specified, knife-audit will return a list of *all* cookbooks available on the currently configured Chef server or Opscode Platform organization, along with a count for each of how many nodes in the current Chef server or Opscode Platform organization explicitly reference that cookbook in their expanded runlist.
-Note that this does *not* include nodes that call the cookbook via 'include' and/or 'depends' statements. The 'complete runlist' for nodes, which includes all cookbooks pulled in due to includes, is kept in Node.run_state.seen_recipes, but this is an ephemeral attribute and is only populated locally on the node during a client run. It is not saved to the Chef server, therefore knife-audit cannot 'see' it.
+Note that this does *not* include nodes that call the cookbook via 'include' and/or 'depends' statements. The 'complete runlist' for nodes, which includes all cookbooks pulled in due to includes, is kept in Node.run_state.seen_recipes, but this is an ephemeral attribute and is only populated locally on the node during a client run. It is not saved to the Chef server, therefore knife-audit cannot 'see' it 'unless' you have installed the knife_audit helper cookbook to your nodes (see 'Helper Cookbook' below).
If one or more cookbook names are specified on the command line, knife-audit will return a list of only those cookbooks and their counts. Specifying a cookbook which is not available on the Chef server will result in an error.
+The '-a' or '--all-cookbooks' option will cause knife-audit to check on each node for the attribute [:knife_audit][:seen_recipes] (which the helper cookbook saves there). If it is present, it will use the contents of that attribute to determine which recipes the node is calling. If it is not present, it will fall back (for that node) to the regular expanded runlist. The output of knife-audit will, in this case, be in two parts: The first will be identical to the default output and will display totals for all those nodes which do *not* have the seen_recipes attribute available. The second part will be totals for all those nodes which *do* have the attribute available. They are separated so that if the '-s' option is used, the nodes can be differentiated.
+
+The '-t' or '--totals' option will cause knife-audit to present a single output section containing the merged totals of all nodes with and without the helper cookbook. This is less accurate, but still useful and easier to read.
+
The '-s' or '--show-nodelist' option will cause knife-audit to include in its output a list of all nodes which reference each cookbook.
+The '-i' or '--install-cookbook' option will cause knife-audit to copy the knife_audit helper cookbook into the currently configured Chef cookbook_path. If there is already a directory or file there with that name, it will abort. Note that you will need to 'knife cookbook upload knife_audit' once you have done this in order to push the cookbook to your Chef server; in addition, you will need to add the knife_audit cookbook to your node runlists. See 'Helper Cookbook' below for more information.
+
**NOTE** knife-audit retrieves an array of *all* nodes present on your chef server for each run. As a result, it is relatively slow; if you have many ( >= 16) nodes, it will take noticeable wallclock time to complete its run. In addition. it may use lots of memory to hold those node objects.
+Helper Cookbook
+---------------
+
+The helper cookbook (knife_audit) consists of a single recipe (default) with a single resource in it - a ruby_block which saves node.run_state.seen_recipes to the attribute node[:knife_audit][:seen_recipes]. This preserves the *complete* runlist information from seen_recipes, which chef-client does not save to the chef server after constructing it in the compile phase. Since the helper cookbook performs this attribute copy in a ruby_block, it will occur during the execute phase, guaranteeing that seen_recipes is complete (unless your runlist contains a cookbook which modifies the node's runlist!) As a result, knife_audit can be called at any point in your runlist without affecting its function (again, unless your runlist modifies itself; in this case, best to call it first).
+
+
Disclaimer
----------

0 comments on commit df2bc15

Please sign in to comment.