Setup Chef Workstation

[edit on GitHub]

This guide walks you through the four parts to set up Chef Workstation on your computer.

• Configure Ruby Environment
• Set up your chef-repo for storing your cookbooks
• Setup Chef Credentials
• Verify Client-to-Server Communication

Prerequisites

1. Download and install Chef Workstation
2. A running instance of Chef Infra Server or Hosted Chef Server.
3. Unless using Chef Manage or Hosted Chef, the CLIENT.PEM file supplied by your Chef administrator.

Configure Ruby Environment

For many users, Ruby is primarily used for developing Chef policy (for example, cookbooks, Policyfiles, and Chef InSpec profiles). If that’s true for you, then we recommend using the Chef Workstation Ruby as your default system Ruby. If you use Ruby for software development, you’ll want to skip this step.

1. Determine your default shell by running:

   echo $SHELL
   

   This will give you the path to your default shell such as /bin/zsh for the Zsh shell.

2. Add the Workstation initialization content to the appropriate shell rc file:

   For Bash shells run:

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

   For Zsh shells run:

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

   For Fish shells run:

   echo 'eval (chef shell-init fish)' >> ~/.config/fish/config.fish
   

3. Open a new shell window and run:

   which ruby
   

   The command should return /opt/chef-workstation/embedded/bin/ruby.

Setup Your Chef Repo

If you’re setting up Chef for the very first time in your organization, then you will need a Chef Infra repository for saving your cookbooks and other work.

The chef-repo is a directory on your workstation that stores everything you need to define your infrastructure with Chef Infra:

• Cookbooks (including recipes, attributes, custom resources, libraries, and templates)
• Data bags
• Policyfiles

The chef-repo directory should be synchronized with a version control system, such as git. All of the data in the chef-repo should be treated like source code.

You’ll use the chef and knife commands to upload data to the Chef Infra Server from the chef-repo directory. Once uploaded, Chef Infra Client uses that data to manage the nodes registered with the Chef Infra Server and to ensure that it applies the right cookbooks, policyfiles, and settings to the right nodes in the right order.

Use the chef generate repo command to create your Chef Infra repository. For example, to create a repository called chef-repo:

chef generate repo chef-repo

Setup Chef Credentials

The first time you run the Chef Workstation app, it creates a .chef directory in your user directory. The .chef directory is where you will store your Chef Workstation configuration and your client keys.

If you’re setting up Chef Workstation as a Chef Infra Server administrator, then you will need to manage users with the Chef Infra Server CLI or the Manage UI. When you create a new user, a user-specific RSA client key will be generated, which you then need to share securely with that user.

If you’re setting up Chef Workstation as a Chef user, then you will need to setup your unique client private key that corresponds to a client on the Chef Infra Server that your server administrator creates for you. The client private key is an RSA private key in the .pem format.

Configure Your User Credentials File

Your .chef directory contains a credentials file used to communicate with the Chef Infra Server. You can generate this file by running knife configure and following the prompts.

The knife configure command requires the following values:

• Chef Server URL: the full URL to your Chef Infra Server including the org
• Client Name: the client name your server administrator created for you

Your Chef administrator should provide this information. For Hosted Chef or Chef Manage, you can find this information in the Starter Kit file. Download the file on the Manage site by navigating to the Administration tab and selecting Starter Kit. (Manage > Administration > Starter Kit > Download Starter Kit)

Find the .chef/config.rb file in the Starter Kit. It should look like:

current_dir = File.dirname(__FILE__)
log_level                :info
log_location             STDOUT
node_name                "hshefu"
client_key               "#{current_dir}/hshefu.pem"
chef_server_url          "https://api.chef.io/organizations/4thcafe-web-team"
cookbook_path            ["#{current_dir}/../cookbooks"]

Use the chef_server_url and node_name values from this file when running knife configure.

Setup Your Client Private Key

All communication between Chef Workstation and the Chef Infra Server is authenticated using an RSA public/private key pair. This pair is generated on the Chef Infra Server and the private key must be copied to your local Chef Workstation installation for communication to function.

The steps for downloading or generating these files vary depending on how you interact with Chef Infra Server. Select the option that best describes how you interact with the server:

• Chef Infra Server / Automate
• Hosted Chef / Manage

cp ~/Downloads/MY_NAME.pem ~/.chef/

Copy-Item -Path C:\Users\MY_NAME\Downloads\MY_NAME.pem -Destination C:\Users\MY_NAME\.chef\

cp ~/Downloads/chef-repo/.chef/MY_NAME.pem ~/.chef/

Copy-Item -Path C:\Users\MY_NAME\Downloads\chef-repo\.chef\MY_NAME.pem -Destination C:\Users\MY_NAME\.chef\

Verify Client-to-Server Communication

To verify that Chef Workstation can connect to the Chef Infra Server:

Run the following command on the command line:

knife client list

Which should return a list of clients similar to:

chef_machine
registered_node

Fetch Self Signed Certificates

If the Chef Infra Server you’re configured to use has a self signed certificate, you’ll use the knife ssl fetch subcommand to download the the Chef Infra Server TLS/SSL certificate and save it in your .chef/trusted_certs.

Chef Infra verifies the security of all requests made to the server from tools such a knife and Chef Infra Client. The certificate that is generated during the installation of the Chef Infra 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 Chef Infra Client will make requests to the Chef Infra Server.

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

knife ssl fetch

See SSL Certificates for more information about how knife and Chef Infra Client use SSL certificates generated by the Chef Infra Server.