Getting Started

This guide walks your 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

Download and install Chef Workstation
A running instance of Chef Infra Server or Hosted Chef Server and access to the USER.pem.

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.

Note

These instructions are intended for macOS and Linux users. On Windows, Chef Workstation includes a desktop shortcut to a PowerShell prompt already configured for use.

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.

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

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 certificate that corresponds to a client on the Chef Infra Server that your server administrator creates for you. The client certificate is an RSA private key in the .pem format.

Save your client certificate in the .chef directory using the same name as the client created by your server administrator.

Configure Your User Credentials File

Your .chef directory contains an example client credentials file, which you can modify to setup communication with your Chef Infra Server.

At a minimum, you must update the following settings with the appropriate values:

client_name: the client name your server administrator created for you
client_key: the path to the client key in your .chef directory
chef_server_url: the full URL to your Chef Infra Server including the org

Chef Infra Server / Automate
Hosted Chef / Manage

The sample credentials file at ~/.chef/credentials:

# This is the Chef Infra credentials file used by the knife CLI and other tools
# This file supports defining multiple credentials profiles, to allow you to switch between users, orgs, and Chef Infra Servers.

# Example credentials file configuration:
# [default]
# client_name = 'MY_USERNAME'
# client_key = '/Users/USERNAME/.chef/MY_USERNAME.pem'
# chef_server_url = 'https://api.chef.io/organizations/MY_ORG'

Your Chef administrator will provide you with the information you need to configure your credentials file. The completed credentials file should look similar to this:

[default]
client_name = 'hshefu'
client_key = '/Users/harishefu/.chef/hshefu.pem'
chef_server_url = 'https://chef-server.4thcafe.com/organizations/web-team'

Hosted Chef and Chef Manage provide a Starter Kit file with your credentials information. 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"]

Copy the values for node_name, client_key, and chef_server_url and use them to complete the credentials file at ~/.chef/credentials. Use the value for node_name in the client_key field of the credentials file and make sure to use the complete path to the client_key in your .chef directory.

The completed credentials file should look similar to this:

[default]
client_name = 'hshefu'
client_key = '/Users/harishefu/.chef/hshefu.pem'
chef_server_url = 'https://api.chef.io/organizations/4thcafe-web-team'

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

Your Chef administrator will provide you with your client.pem file. Copy this file to the ~/.chef directory.

On macOS and Linux systems this looks something like:

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

On Windows systems this will look something like this:

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

The client key file is located in the Starter Kit at .chef/MY_NAME.pem. Copy the .pem file to the ~/.chef directory.

On macOS and Linux systems this looks something like:

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

On Windows systems this will look something like this:

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.

Was this page helpful?