Install the Chef DK

The omnibus installer is used to set up the Chef development kit on a workstation, including the chef-client itself, an embedded version of Ruby, RubyGems, OpenSSL, key-value stores, parsers, libraries, command line utilities, and community tools such as Kitchen, Berkshelf, and ChefSpec. The omnibus installer puts everything into a unique directory (opt/chefdk/) so that these components will not interfere with other applications that may be running on the target machine. Once installed, the chef-client requires a few more configuration steps before it can be run as a workstation.

Install on a Workstation

The following sections describe how to install the Chef development kit on a workstation:

1. Identify the Chef server type: hosted or on-premises
2. Review the prerequisites
3. Select the omnibus installer for the desired platform
4. Run the omnibus installer
5. Set the system Ruby
6. Install git
7. Set up the chef-repo
8. Create the .chef directory
9. Get the .pem files and knife.rb files
10. Move files to the .chef directory
11. Add omnibus Ruby to the $PATH environment variable
12. Get SSL certificates from the Chef server
13. Verify the chef-client install

See the following sections for more information about each step.

Review prerequisites

Ensure that the workstation meets all of the software prerequisites and that it has access to a Chef server and to a machine that can host a node.

The following items are prerequisites for installing the chef-client on a workstation:

• A computer running UNIX, Linux, Mac OS X or Microsoft Windows
• Apple XCode is installed on machines running Mac OS X; this application can be downloaded from Apple for free
• A GitHub account; the chef-repo must be downloaded and/or cloned from GitHub
• Access to a Chef server: a hosted Chef server account or an on-premises Chef server. If you have a proxy, information on configuring chef-client to work with it is here
• Access to a machine (physical or virtual) that can be used as the first node; the FQDN or IP address for a machine is required by the knife bootstrap subcommand during a bootstrap operation

Get Package, Run Installer

To install the Chef development kit:

1. Visit this page: http://downloads.chef.io/chef-dk/. The Chef development kit supports Mac OS X, Red Hat Enterprise Linux, Ubuntu, and Microsoft Windows.

2. Select a platform, and then a package. (chef-docs uses the Mac OS X setup within the documentation.)

3. Click the download button.

4. Follow the steps in the installer and install the Chef development kit to your machine. The Chef development kit is installed to /opt/chefdk/ on UNIX and Linux systems.

5. When finished, open a command window and enter the following:

   $ chef verify

   This will verify the main components of the Chef development kit: the chef-client, the Chef development kit library, and the tools that are built into the Chef development kit. The output should be similar to:

   Running verification for component '...'
   ..........
   ---------------------------------------------
   Verification of component '...' succeeded.

6. Optional. Set the default shell. On Microsoft Windows it is strongly recommended to use Windows PowerShell and cmd.exe.

Set System Ruby

For many users of Chef, the Chef development kit version of Ruby that is included in the Chef development kit should be configured as the default version of Ruby.

1. Open a command window and enter the following:

   $ which ruby

   which will return something like /usr/bin/ruby.

2. To use the Chef development kit version of Ruby as the default Ruby, edit the $PATH and GEM environment variables to include paths to the Chef development kit. For example, on a machine that runs Bash, run:

   echo 'eval "$(chef shell-init bash)"' >> ~/.bash_profile

   where bash and ~/.bash_profile represents the name of the shell.

   If zsh is your preferred shell then run the following:

   echo 'eval "$(chef shell-init zsh)"' >> ~/.zshrc

3. Run which ruby again. It should return /opt/chefdk/embedded/bin/ruby.

PowerShell

You can use chef shell-init with Windows PowerShell.

To try it in your current session:

chef shell-init powershell | Invoke-Expression

To enable it permanently:

"chef shell-init powershell | Invoke-Expression" >> $PROFILE

Set the execution policy on new machines

For new Microsoft Windows machines, Windows PowerShell scripts will not work until an administrator runs the following command:

Set-ExecutionPolicy RemoteSigned

Create a $PROFILE on new machines

For new Microsoft Windows machines, commands cannot be appended to $PROFILE if the folder does not exist or if there is a new user profile, an error similar to the following may be returned:

PS C:\Users\Stuart> "chef shell-init powershell | Invoke-Expression" >> $PROFILE
out-file : Could not find a part of the path
'C:\Users\Stuart\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1'.
At line:1 char:1
+ "chef shell-init powershell | Invoke-Expression" >> $PROFILE
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OpenError: (:) [Out-File], DirectoryNotFoundException
    + FullyQualifiedErrorId : FileOpenFailure,Microsoft.PowerShell.Commands.OutFileCommand

In this situation, run the following chef shell-init command instead:

if(Test-Path $PROFILE){ chef shell-init powershell | Add-Content $PROFILE } else { New-Item -Force -ItemType File $PROFILE; chef shell-init powershell | Add-Content $PROFILE }

Microsoft Windows

To set the system Ruby for the Microsoft Windows platform the steps described for all platforms are true, but then require the following manual edits to the chef shell-init bash output for the Microsoft Windows platform:

1. Add quotes around the variable assignment strings.
2. Convert C:/ to /c/.
3. Save those changes.

Install git

An open source distributed version control system called git must be installed before the chef-repo can be cloned to the workstation from GitHub.

To install git:

1. Go to the following URL: https://help.github.com/articles/set-up-git.
2. Follow the directions, install git (http://git-scm.com/downloads), and then complete the remaining configuration steps on that page.

Set up the chef-repo

There are two ways to create the chef-repo:

• Use the starter kit built into the Chef server web user interface
• Manually, by using the chef generate app subcommand in the chef command-line tool that is packaged in the Chef development kit

Starter Kit

If you have access to Chef server (hosted or on premises), you can download the starter kit. The starter kit will create the necessary configuration files—the .chef directory, knife.rb, the ORGANIZATION-validator.pem, and USER.pem files) with the correct information that is required to interact with the Chef server. Simply download the starter kit and then move it to the desired location on your workstation.

Manually (w/ Webui)

Use the following steps to manually set up the chef-repo and to use the Chef management console to get the .pem and knife.rb files.

Create the chef-repo

Use the chef generate app command to create the chef-repo.

Create .chef Directory

The .chef directory is used to store three files:

• knife.rb
• ORGANIZATION-validator.pem
• USER.pem

Where ORGANIZATION and USER represent strings that are unique to each organization. These files must be present in the .chef directory in order for a workstation to be able to connect to a Chef server.

To create the .chef directory:

1. In a command window, enter the following:

   mkdir -p ~/chef-repo/.chef

2. After the .chef directory has been created, the following folder structure will be present on the local machine:

   chef-repo/
      .chef/        << the hidden directory
      certificates/
      config/
      cookbooks/
      data_bags
      environments/
      roles/

3. Add .chef to the .gitignore file to prevent uploading the contents of the .chef folder to GitHub. For example:

   $ echo '.chef' >> ~/chef-repo/.gitignore

Get Config Files

For a workstation that will interact with the Chef server (including the hosted Chef server), log on and download the following files:

• knife.rb. This configuration file can be downloaded from the Organizations page.
• ORGANIZATION-validator.pem. This private key can be downloaded from the Organizations page.
• USER.pem. This private key an be downloaded from the Change Password section of the Account Management page.

Move Config Files

The knife.rb, ORGANIZATION-validator.pem, and USER.pem files must be moved to the .chef directory after they are downloaded from the Chef server.

To move files to the .chef directory:

1. In a command window, enter each of the following:

   cp /path/to/knife.rb ~/chef-repo/.chef

   and:

   cp /path/to/ORGANIZATION-validator.pem ~/chef-repo/.chef

   and:

   cp /path/to/USERNAME.pem ~/chef-repo/.chef

   where /path/to/ represents the path to the location in which these three files were placed after they were downloaded.

2. Verify that the files are in the .chef folder.

Manually (w/o Webui)

Use the following steps to manually set up the chef-repo, create the ORGANIZATION-validator.pem and USER.pem files with the chef-server-ctl command line tool, and then create the knife.rb file.

Create the chef-repo

Use the chef generate app command to create the chef-repo.

Create .chef Directory

The .chef directory is used to store three files:

• knife.rb
• ORGANIZATION-validator.pem
• USER.pem

Where ORGANIZATION and USER represent strings that are unique to each organization. These files must be present in the .chef directory in order for a workstation to be able to connect to a Chef server.

To create the .chef directory:

1. In a command window, enter the following:

   mkdir -p ~/chef-repo/.chef

2. After the .chef directory has been created, the following folder structure will be present on the local machine:

   chef-repo/
      .chef/        << the hidden directory
      certificates/
      config/
      cookbooks/
      data_bags
      environments/
      roles/

3. Add .chef to the .gitignore file to prevent uploading the contents of the .chef folder to GitHub. For example:

   $ echo '.chef' >> ~/chef-repo/.gitignore

Create an Organization

On the Chef server machine create the ORGANIZATION-validator.pem from the command line using chef-server-ctl. Run the following command:

$ chef-server-ctl org-create ORG_NAME ORG_FULL_NAME -f FILE_NAME

where

• The name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example: chef
• The full name must begin with a non-white space character and must be between 1 and 1023 characters. For example: "Chef Software, Inc."
• -f FILE_NAME: Write the ORGANIZATION-validator.pem to FILE_NAME instead of printing it to STDOUT. For example: /tmp/chef.key.

For example, an organization named chef, with a full name of Chef Software, Inc., and with the ORGANIZATION-validator.pem file saved to /tmp/chef.key:

$ chef-server-ctl org-create chef "Chef Software, Inc." -f /tmp/chef.key

Create a User

On the Chef server machine create the USER.pem from the command line using chef-server-ctl. Run the following command:

$ chef-server-ctl user-create USER_NAME FIRST_NAME LAST_NAME EMAIL PASSWORD -f FILE_NAME

where

• Write the USER.pem to a file instead of STDOUT. For example: /tmp/grantmc.key.

For example, a user named grantmc, with a first and last name of Grant McLennan, an email address of [email protected], a poorly-chosen password, and with the USER.pem file saved to /tmp/grantmc.key:

$ chef-server-ctl user-create grantmc Grant McLennan [email protected] p@s5w0rD! -f /tmp/grantmc.key

Move .pem Files

The ORGANIZATION-validator.pem and USER.pem files must be moved to the .chef directory after they are downloaded from the Chef server.

To move files to the .chef directory:

1. In a command window, enter each of the following:

   cp /path/to/ORGANIZATION-validator.pem ~/chef-repo/.chef

   and:

   cp /path/to/USERNAME.pem ~/chef-repo/.chef

   where /path/to/ represents the path to the location in which these three files were placed after they were downloaded.

2. Verify that the files are in the .chef folder.

Create the knife.rb File

The knife.rb file must be created in the .chef folder. It should look similar to:

current_dir = File.dirname(__FILE__)
log_level                :info
log_location             STDOUT
node_name                'node_name'
client_key               "#{current_dir}/USER.pem"
validation_client_name   'chef-validator'
validation_key           "#{current_dir}/ORGANIZATION-validator.pem"
chef_server_url          'https://api.chef.io/organizations/ORG_NAME'
cache_type               'BasicFile'
cache_options( :path => "#{ENV['HOME']}/.chef/checksums" )
cookbook_path            ["#{current_dir}/../cookbooks"]

Add Ruby to $PATH

The chef-client includes a stable version of Ruby as part of the omnibus installer. The path to this version of Ruby must be added to the $PATH environment variable and saved in the configuration file for the command shell (Bash, csh, and so on) that is used on the workstation. In a command window, type the following:

echo 'export PATH="/opt/chefdk/embedded/bin:$PATH"' >> ~/.configuration_file && source ~/.configuration_file

where configuration_file is the name of the configuration file for the specific command shell. For example, if Bash were the command shell and the configuration file were named bash_profile, the command would look something like the following:

echo 'export PATH="/opt/chefdk/embedded/bin:$PATH"' >> ~/.bash_profile && source ~/.bash_profile

Get SSL Certificates

Chef server 12 enables SSL verification by default for all requests made to the server, such as those made by knife and the chef-client. The certificate that is generated during the installation of the Chef server is self-signed, which means there isn’t a signing certificate authority (CA) to verify. In addition, this certificate must be downloaded to any machine from which knife and/or the chef-client will make requests to the Chef server.

Use the knife ssl fetch subcommand to pull the SSL certificate down from the Chef server:

knife ssl fetch

See SSL Certificates for more information about how knife and the chef-client use SSL certificates generated by the Chef server.

Verify Install

A workstation is installed correctly when it is able to use knife to communicate with the Chef server.

To verify that a workstation can connect to the Chef server:

1. In a command window, navigate to the chef-repo:

   cd ~/chef-repo

2. In a command window, enter the following:

   knife client list

   to return a list of clients (registered nodes and workstations) that have access to the Chef server. For example:

   workstation
   registered_node

Chef DK and Windows

The following sections describe issues that are known to users of the Chef development kit on the Microsoft Windows platform.

Spaces and Directories

Directories that are used by Chef on the Microsoft Windows platform cannot have spaces. For example, /c/Users/Steven Danno will not work, but /c/Users/StevenDanno will.

A different issue exists with the knife command line tool that is also related to spaces and directories. The knife cookbook site install subcommand will fail when the Microsoft Windows directory contains a space.

Top-level Directory Names

Paths can be longer in UNIX and Linux environments than they can be in Microsoft Windows. Microsoft Windows will throw errors when path name lengths are too long. For this reason, it’s often helpful to use a very short top-level directory in Microsoft Windows, much like what is done in UNIX and Linux. For example, Chef uses /opt/ to install the Chef development kit on Mac OS X. A similar approach can be done on Microsoft Windows, by creating a top-level directory with a short name. For example: c:\chef.

Uninstall

The Chef development kit can be uninstalled using the steps below that are appropriate for the platform on which the Chef development kit is installed.

Debian

Use the following command to remove the Chef development kit on Debian-based platforms:

$ dpkg -P chefdk

Mac OS X

Use the following commands to remove the Chef development kit on Mac OS X.

To remove installed files:

$ sudo rm -rf /opt/chefdk

To remove the system installation entry:

$ sudo pkgutil --forget com.getchef.pkg.chefdk

To remove symlinks:

• For chef-client version 12.x, under /usr/local/bin:

  $ sudo find /usr/local/bin -lname '/opt/chefdk/*' -delete

• For chef-client version 11.x, under /usr/bin:

  $ sudo find /usr/bin -lname '/opt/chefdk/*' -delete

Red Hat Enterprise Linux

Use the following commands to remove the Chef development kit on Red Hat Enterprise Linux-based platforms:

$ rpm -qa *chefdk*
$ sudo yum remove -y <package>

Microsoft Windows

Use Add / Remove Programs to remove the Chef development kit on the Microsoft Windows platform.