minor clarifications and notes

slides/cookbooks-recipes-resources/01_slide.md

@@ -163,6 +163,12 @@ This run list can include recipes that also include other recipes.
 
 These are applied to the node in the order listed.
 
+    @@@javascript
+    "run_list": [
+      "recipe[apache2]",
+      "recipe[webserver]"
+    ]
+
 # Chef Recipes
 
 Recipes are processed in the order they are written.
@@ -323,6 +329,9 @@ Are equivalent. To use a different recipe, specify it by name:
 
     recipe[webserver::different-recipe]
 
+.notes Chef deduplicates recipes, but there's a bug about using
+webserver and webserver::default and both being included
+
 # Add Recipe to a Node
 
 Use knife to add a recipe to an existing node's run list on the Chef

slides/getting-started/01_slide.md

@@ -142,6 +142,8 @@ Installation on Windows is done by downloading the MSI and installing it.
 
 Server versions are directly tested, but the MSI is known to install and work fine on desktop versions of Windows such as Vista and 7.
 
+.notes Do this now. Download the MSI and install it.
+
 # What You Get: Linux/Unix
 
 Chef binaries are in `/opt/opscode/bin`. The package installation symlinks them in `/usr/bin` so they are in the default `$PATH`.
@@ -182,6 +184,11 @@ Non-Chef tools:
 * Version control systems (Git, Subversion, Perforce)
 * Ruby programming language
 
+.notes Coverage of these tools is outside the scope of the class.
+Students are assumed to have knowledge and familiarity with the shell,
+text editor and version control system of their choice sufficient for
+working in the hands on exercises.
+
 # Chef Tools
 
 Each of the tools bundled with the Chef Full package share some common traits.
@@ -295,7 +302,7 @@ The default configuration file for Knife is `.chef/knife.rb`; knife looks for it
     $PWD/".."/.chef/knife.rb
     ~/.chef/knife.rb
 
-Opscode Hosted Chef provides a pregenerated `knife.rb` you can use.
+Opscode Hosted/Private Chef provides a pregenerated `knife.rb` you can use.
 
 # Knife Configuration Options
 
@@ -511,6 +518,9 @@ The default configuration file is `/etc/chef/solo.rb`.
 
 These are similar to `chef-client`, with the addition of `-r`.
 
+.notes This concludes the material that covers chef-solo, we're going
+to work with a Chef Server for the remainder of the course.
+
 # Shef
 
 Shef is an interactive Ruby console that supports attribute and recipe contexts, as well as interactive debugging features.

slides/more-cookbooks/01_slide.md

@@ -33,16 +33,6 @@ example, "`apache2-1.0.8.tar.gz`".
     > tar -zxvf apache2-1.0.8.tar.gz -C cookbooks/
     > ls cookbooks/apache2
 
-# Use Your VCS
-
-Knife currently integrates with Git in the "cookbook site install"
-command.
-
-You can use any version control system you like.
-
-There will be additional steps required to untar cookbooks,
-branch/merge, etc, depending on your tool.
-
 # Examine the Cookbooks
 
 Remember, you're probably going to run Chef on the nodes as a
@@ -88,11 +78,12 @@ Included recipes from other cookbooks require metadata dependency.
 
 # Cookbook Dependencies
 
-Remember, cookbook dependencies are assumed when using part(s) of one
-cookbook in another, such as recipe inclusion.
+Remember, cookbook dependencies are *assumed* when using part(s) of one
+cookbook in another, such as recipe inclusion, but they are not
+created automatically.
 
 Cookbook dependencies are explicitly defined in metadata. Use the
-"depends" keyword. This will cause Chef to download the dependency
+"`depends`" keyword. This will cause Chef to download the dependency
 cookbook from the server.
 
 Downloading a cookbook as a dependency from another does not cause it
@@ -137,6 +128,9 @@ For example, the default action in the `fail2ban` package resource is
 upgrade, so apt will ensure we always have the latest version
 including security fixes.
 
+.notes Other platforms (e.g. RHEL family) might have a yum-related
+recipe instead of apt. Like yum::epel
+
 # Apply Role to Node
 
 Applying the role to the node can be done with knife.
@@ -154,7 +148,8 @@ The `$EDITOR` environment variable must be set, or specified with
     > knife node edit NODE -e vi
 
 .notes On Windows, use cmd.exe not powershell, else an erroneous entry
-will be made (e.g., recipe[roles]).
+will be made (e.g., recipe[roles]). The %EDITOR% variable can be set
+to, e.g. set EDITOR="C:\Program Files\Windows NT\Accessories\wordpad.exe"
 
 # Apply role to Node
 
@@ -187,6 +182,9 @@ Many things automated with Chef follow a pattern:
 
 Let's walk through another example of this pattern.
 
+.notes The haproxy cookbook is used to follow the *pattern*; the
+implementation details are moot.
+
 # haproxy Cookbook
 
 Download the haproxy cookbook.
@@ -197,6 +195,10 @@ Download the haproxy cookbook.
 We will explore the haproxy cookbook for this pattern because we'll
 revisit it in the next section on search.
 
+.notes In the next section on search we'll look at the parts of the
+haproxy cookbook that are modified to adapt the recipe for this
+flexibility.
+
 # haproxy default recipe
 
 The default recipe follows the pattern.
@@ -221,7 +223,7 @@ many platforms.
       action :install
     end
 
-.notes On RHEL, it is available from EPEL.
+.notes On RHEL, it is available from EPEL, use yum::epel in the base role.
 
 # haproxy default template
 
@@ -236,7 +238,9 @@ On Debian/Ubuntu, the service is controlled by a config file
       mode 0644
     end
 
-.notes Due to this specific file, the recipe won't work on RHEL systems.
+.notes Due to this specific file, the recipe won't work on RHEL
+systems. If the exercises are done on RHEL systems, then we can
+comment this out when it is used.
 
 # haproxy default template
 
@@ -321,6 +325,8 @@ set by the cookbook. Excerpts from the template:
     default['haproxy']['enable_admin'] = true
     default['haproxy']['balance_algorithm'] = "roundrobin"
 
+.notes This syntax is because we access the attributes *like* a Hash.
+
 # haproxy modifying attributes
 
 We can modify the attributes directly editing the cookbook, or even
@@ -339,6 +345,9 @@ better, by applying them with a role appropriate to the task.
       }
     )
 
+.notes This syntax is because we are creating the attributes *as* a
+Hash.
+
 # Summary
 
 * Download additional cookbooks with knife

slides/multiple-nodes-and-search/01_slide.md

@@ -28,8 +28,6 @@ Four search indexes are created on the Chef Server by default.
 * role
 * environment
 
-# Search Indexes
-
 When data bags are created, a search index is also created, and the
 index is the same name as the bag.
 
@@ -49,6 +47,7 @@ is abbreviated.
 # Knife Search
 
     knife search node "platform:ubuntu"
+    knife search node "platform:centos"
     knife search node "platform:ubuntu" -r
     knife search node "role:webserver"
 
@@ -313,6 +312,10 @@ bootstrap" command.
 
 The `haproxy::app_lb` recipe will perform a search for web servers.
 
+.notes Modify the app_lb recipe to remove
+template[/etc/default/haproxy] resource if the exercise is on RHEL or
+CentOS platforms.
+
 # Bootstrap Load Balancer
 
     knife bootstrap IPADDRESS -r 'role[lb]' -x ubuntu --sudo

slides/resources-in-depth/01_slide.md

@@ -3,6 +3,7 @@
 Section Objectives:
 
 * Understand the components of resources.
+* Know the commonly used resources in Chef.
 * Write recipes using common resources.
 
 .notes These course materials are Copyright © 2010-2012 Opscode, Inc. All rights reserved.
@@ -21,6 +22,9 @@ Students should be logged into the provided remote target instance
 rather than their local workstation. `shef` should be started as a
 privileged user (e.g., `sudo shef`).
 
+.notes Shef in Windows powershell or cmd.exe, backspace doesn't behave
+precisely as expected.
+
 # Shef
 
 `shef`, the Chef Shell (or Console) operates under different execution
@@ -167,6 +171,10 @@ Type this into your Shef session (recipe context):
 * mode - octal mode of the file, specify as a number with a leading 0,
   or as a string, default is the umask of the chef process
 
+.notes owner, group, mode on Windows do not work on Windows before
+Chef 0.10.10, and full inheritance and ACL support will be available
+after that release.
+
 # file parameters
 
 * content - a string to write to the file, overwrites existing content
@@ -183,6 +191,9 @@ Use `cookbook_file` to transfer files from the cookbook to the node.
 * small binary files
 * inherits from `file`, so permission parameters can be used.
 
+.notes Do not store and transfer large files in the cookbook, this is
+for static content like scripts (e.g. plugins)
+
 # cookbook_file example
 
     @@@ruby
@@ -401,6 +412,8 @@ The default action is to install the named package.
 
 # package examples
 
+Type this into Shef (recipe context):
+
     @@@ruby
     package "apache2"
 
@@ -486,6 +499,8 @@ The default action for both resources is to create the named group or user.
 
 # group example
 
+Type this into Shef (recipe context):
+
     @@@ruby
     group "admins" do
       gid 999
@@ -519,6 +534,8 @@ The default action for both resources is to create the named group or user.
 
 # system user example
 
+Type this into Shef (recipe context):
+
     @@@ruby
     user "myapp" do
       system true
@@ -571,6 +588,8 @@ of what it means to say you have a service resource to manage.
 
 # service example
 
+Type this into Shef (recipe context):
+
     @@@ruby
     service "apache2" do
       supports :status => true
@@ -702,6 +721,8 @@ The default action for execute and script resources is to run the command/script
 
 # execute examples
 
+Type this into Shef (recipe context):
+
     @@@ruby
     execute "apt-get update"
 
@@ -843,11 +864,12 @@ source files for some of the templates and cookbook_files.
 
 Chef will halt execution when it encounters an unhandled exception.
 
-.notes the `shef` command to enter the execution phase is `run-chef`.
+.notes the `shef` command to enter the execution phase is `run_chef`.
 
 # Summary
 
 * Understand the components of resources.
+* Know the commonly used resources in Chef.
 * Write recipes using common resources.
 
 # Questions

slides/troubleshooting/01_slide.md

@@ -95,7 +95,7 @@ It doesn't know if the error is something serious that can cause state issues th
 
 It is up to you to fix the error and re-run Chef.
 
-Stack traces are left behind in a file, by default
+Stack traces are written to a file, by default
 `/var/chef/cache/chef-stacktrace.out`. The directory location is
 `file_cache_path` in `/etc/chef/client.rb`.
 
@@ -167,13 +167,6 @@ What template is this from?
 
 # Template Error
 
-The last part of the stack trace comes from dumping the exception from
-the exception handler.
-
-We need to scroll up in the output to find what template and where.
-
-# Template Error
-
 The output from the run before the exception handler dumped the stack
 trace. This shows the offending line ("ode" instead of "node").
 
@@ -273,14 +266,6 @@ If there's a syntax error, we'll see a 500 from the server.
 
 To find where the query is in the recipe, look for the line above.
 
-# Invalid Search
-
-    % sudo sed -n 25p cookbooks/getting-started/recipes/default.rb
-
-We can view the specific line in the cookbook on the node with sed.
-
-Or just view it in your local repository with your favorite editor.
-
 # Fixing Recipe Errors
 
 Fixing recipes errors is relatively straightforward after they have
@@ -398,7 +383,7 @@ Recipes are "just Ruby".
 
 Normally we can use a begin/rescue block to handle errors.
 
-We can also cause Chef to bail out.
+We can also tell Chef explicitly to exit the run.
 
 # begin..rescue