Set Up Chef Workstation
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
- Set up Chef Credentials
- Verify Client-to-Server Communication
Prerequisites
- Download and install Chef Workstation
- A running instance of Chef Infra Server or Hosted Chef Server.
- 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.
Note
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
.
Set up 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
Set up 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 set up 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 orgClient 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
.
Set up 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:
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 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.