Skip to content

Home

Jump to bottom
aerii edited this page Jul 14, 2015 · 11 revisions

Welcome to the chef-debug wiki!

Description

The Chef Zero shell can be used for debugging Chef code. This cookbook automatically provides the initial configurations necessary to get the shell running on temporary Linux-based and Windows-based virtual machines used in reproducible/repeatable environments for virtual boxes, such as VirtualBox.

The shell offers close inspection of the code, by loading specific recipes in the run list. The default recipe is recipe[chef_debug::default]. The breakpoint resource can be used to break in the recipe at specific locations. The syntax for a breakpoint resource is:

breakpoint 'name' do
  action :break
end

Problem Scenario

Solving a logical error on a Linux CentOS platform by stepping through the code line-by-line. The node["weather"] says that it is "Rain" when it should be "Sunny".

Solving step-by-step

  1. Enter vagrant through kitchen: kitchen login
  2. Change to root: sudo su -
  3. Initialize the debugging shell: debug.sh
  4. Inspect the platform: node["fqdn"]
    The output shows that it is CentOS => "default-centos-66".
  5. Inspect the weather node: node["weather"]
    The output shows that it is => "Rain".
  6. Initiate the chef-client: run_chef
    The program is run until the first breakpoint, at chef_debug::debug line 11.
  7. To step through the code: chef_run.step
    The program steps to the next breakpoint, at chef_debug::debug line 20.
    The output is => 6 because it skipped six lines.
  8. To resume the code: chef_run.resume
    The output shows that the node["weather"] was set twice.
    On line 18 it was set to "Sunny" but the value was overwritten on line 26 to "Rain".
  9. Comment out line 26 in chef_debug::debug.rb using: #
  10. To exit the debugging shell: exit
  11. Before exiting vagrant, check if chef-zero is still running: ps aux | grep chef-zero
    The first line in the output shows that chef-zero is still running:
    root 7025 ? Sl 01:29 0:00 /opt/chef/embedded/bin/ruby /opt/chef/embedded/bin/chef-zero -d
     root 7283 pts/0 S+ 01:36 0:00 grep chef-zero
  12. To stop chef-zero: stop_debug.sh
    This is necessary in order to re-converge kitchen for Linux platforms.
  13. Running the command again, shows that chef-zero daemon has stopped: ps aux | grep chef-zero
    root 7294 pts/0 S+ 01:39 0:00 grep chef-zero
  14. To exit root/vagrant: exit
  15. Re-converge kitchen to update changes: kitchen converge
  16. Repeat and then node["weather"] should now be => "Sunny".

Calling the Code

In Linux, to run the chef-zero shell as a daemon, run the bash command in root:

  debug.sh

In Linux, to see if the chef-zero shell is running as a daemon in the background:

  ps aux | grep chef

In Linux, to stop the chef-zero shell daemon, run the command:

  stop_debug.sh

In Windows, to run the chef-zero shell in the background, run the batch command:

  debug.ps1

In Windows, to stop the chef-zero shell, close the command prompt.

Demo

Configurations

knife.rb

The file is used to specify the chef-repo-specific configuration details for knife. It performs the same function as the command: knife configure --initial. The default location it is created in for Linux-based machines is: "/root/.chef/knife.rb". The default location it is created in for Windows-based machines is: "C:/Users/vagrant/.chef/knife.rb". The location can be changed in the platform's debug recipe, debug_rhel and debug_windows respectively.

client.rb

The file is used to specify the configuration details for the chef-client. The default location it is automatically created in when spinning up the virtual machine for Linux-based machines is: /root/tmp/kitchen/. The default location it is automatically created in when spinning up the virtual machine for Windows-based machines is: C:/Users/vagrant/AppData/Local/Temp/kitchen/. The client.rb file is configured to include the client.pem and validation.pem from the same folder, and this attribute can be changed in the file, attributes/default.rb.

debug.sh

In Linux, call to the bash file initiates the debugging shell. The default location it is created in for Linux-based machines is: /usr/local/bin/debug.sh. The corresponding template is in templates/rhel/debug.sh.erb.

stop_debug.sh

In Linux, call to the bash file terminates the running debugging shell. The default location it is created in for Linux-based machines is: /usr/local/bin/stop_debug.sh. The corresponding template is in templates/rhel/stop_debug.sh.erb.

debug.ps1

In Windows, call to the powershell file initiates the debugging shell. The default location it is created in for Windows-based machines is: C:/opscode/chef/bin/debug.ps1. The corresponding template is in templates/windows/debug.ps1.erb.

stop_debug.ps1

In Windows, call to the powershell file is optional and can be edited to terminate the debugging shell. The default location it is created in for Windows-based machines is: C:/opscode/chef/bin/stop_debug.ps1. The corresponding template is in templates/windows/stop_debug.ps1.erb.

debug.rb

The recipe is used to determine the platform-specific debug recipe to call, along with some debugging test code.

debug_rhel.rb

The recipe is customized for running the debugging shell for Linux-based platforms.

debug_windows.rb

The recipe is customized for running the debugging shell for Windows-based platforms.

Node Settings

Required node settings.

Reference to chef-zero.
  - node["chef_debug"]["debug"]["service_name"] = 'chef-zero'

Additional node settings can be configured in the 'attributes/default.rb' file.

To turn on or off debugging (default is true):
  - node["chef_debug"]["debug"]["enabled"] = true/false

The level of logging that will be stored in a log file. 
Possible levels: :auto (default), :debug, :info, :warn, :error, or :fatal. 
  - node["chef_debug"]["debug"]["log_level"] = ':info'

The location of the log file. Possible values: /path/to/log_location, STDOUT, STDERR, 
Chef::Log::WinEvt.new (Windows Event Logger, or Chef::Log::Syslog.new("chef-client", ::Syslog::LOG_DAEMON). 
Default value: STDOUT.
  - node["chef_debug"]["debug"]["log_location"] = 'STDOUT'

The name of the node. In general, leaving this setting blank and letting Ohai 
assign the FQDN of the node as the node_name during each chef-client run is 
the recommended approach. Default value: 'admin'.
  - node["chef_debug"]["debug"]["node_name"] = 'admin'

The name of the chef-validator key that is used by the chef-client to access the Chef 
server during the initial chef-client run. Default value: 'chef-validator'.
  - node["chef_debug"]["debug"]["validation_client_name"] = 'chef-validator'

The URL for the Chef server. Default value: local host.
  - node["chef_debug"]["debug"]["chef_server_url"] = 'http://127.0.0.1:8889'

Linux default locations for client_key and validation_key:
  - node["chef_debug"]["debug"]["client_key"] = '/tmp/kitchen/client.pem'
  - node["chef_debug"]["debug"]["validation_key"] = '/tmp/kitchen/validation.pem'

Windows default locations for client_key and validation_key:
  - node["chef_debug"]["debug"]["client_key"] = 'C:/Users/vagrant/AppData/Local/Temp/kitchen/client.pem'
  - node["chef_debug"]["debug"]["validation_key"] = 'C:/Users/vagrant/AppData/Local/Temp/kitchen/validation.pem'

Note: Windows platform and additional platforms

The Windows platform is disabled by default. In order to enable, comment in the code from the .kitchen.yml file. Additionally, the default Linux CentOS virtual image box can be changed to another platform in .kitchen.yml.

Clone this wiki locally