Configuring ChefDK¶
This guide contains common configuration options used when setting up a new ChefDK installation. If you do not have ChefDK installed, see its installation guide before proceeding further.
Configure Ruby Environment¶
For many users of Chef, the version of Ruby that is included in the Chef development kit should be configured as the default version of Ruby.
Note
These instructions are intended for macOS and Linux users. For instructions on setting up your Ruby environment on Windows, see ChefDK on Windows.
Open a command window and enter the following:
$ which ruby
which will return something like
/usr/bin/ruby
.To use the Chef development kit version of Ruby as the default Ruby, edit the
$PATH
andGEM
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
Run
which ruby
again. It should return/opt/chefdk/embedded/bin/ruby
.
Note
Using the Chef development kit-provided Ruby as your system Ruby is optional. For many users, Ruby is primarily used for authoring Chef cookbooks and recipes. If that’s true for you, then using the Chef Development Kit-provided Ruby is recommended.
Add Ruby to $PATH¶
The Chef Client includes a stable version of Ruby as part of its 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 machine running ChefDK. 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
Warning
On Microsoft Windows, C:/opscode/chefdk/bin
must be before C:/opscode/chefdk/embedded/bin
in the PATH
.
Install Git¶
An open source distributed version control system called Git must be installed before the chef-repo can be cloned to ChefDK machine from GitHub.
To install Git:
- Go to the following URL: https://help.github.com/articles/set-up-git.
- Follow the directions, install Git (https://git-scm.com/downloads), and then complete the remaining configuration steps on that page.
Note
It is not necessary to create or fork a repository in order to clone the chef-repo from GitHub.
Create the Chef repository¶
Use the chef generate repo to create the Chef repository. For example, to create a repository called chef-repo
:
chef generate repo chef-repo
Create .chef Directory¶
The .chef
directory is used to store three files:
config.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 ChefDK to be able to connect to a Chef server.
To create the .chef
directory:
In a command window, enter the following:
mkdir -p ~/chef-repo/.chef
Note that you’ll need to replace
chef-repo
with the name of the repository you created previously.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/
Add
.chef
to the.gitignore
file to prevent uploading the contents of the.chef
folder to GitHub. For example:$ echo '.chef' >> ~/chef-repo/.gitignore
Starter Kit¶
If you have access to Chef server through Automate or Chef Manage, you can download the starter kit. The starter kit will create the necessary configuration files: the .chef
directory, config.rb
, ORGANIZATION-validator.pem
, and USER.pem
. Simply download the starter kit and then move it to the desired location on your ChefDK machine.
Configure the Chef Repository¶
With WebUI¶
Use the following steps to manually set up the chef-repo and to use the Chef management console to get the .pem
and config.rb
files.
Get Config Files¶
For a ChefDK installation that will interact with the Chef server (including the hosted Chef server), log on and download the following files:
config.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 can be downloaded from the Change Password section of the Account Management page.
Move Config Files¶
The config.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:
In a command window, enter each of the following:
cp /path/to/config.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.Verify that the files are in the
.chef
folder.
Without WebUI¶
Use the following steps to manually set up the Chef repository: On your Chef server, create the ORGANIZATION-validator.pem
and USER.pem
files with the chef-server-ctl
command line tool. Then, on your workstation create the config.rb
file with the knife
tool.
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 theORGANIZATION-validator.pem
toFILE_NAME
instead of printing it toSTDOUT
. 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
-f FILE_NAME
writes theUSER.pem
to a file instead ofSTDOUT
. For example:/tmp/grantmc.key
.
For example: a user named grantmc
, with a first and last name of Grant McLennan
, an email address of grantmc@chef.io
, a poorly-chosen password, and a USER.pem
file saved to /tmp/grantmc.key
:
$ chef-server-ctl user-create grantmc Grant McLennan grantmc@chef.io p@s5w0rD! -f /tmp/grantmc.key
Move .pem Files¶
Download the ORGANIZATION-validator.pem
and USER.pem
files from the Chef Server and move them to the .chef
directory.
To move files to the .chef directory:
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.Verify that the files are in the
.chef
folder.
Create the config.rb File¶
Navigate to the ~/chef-repo/.chef
directory and create the config.rb
using the knife configure
tool. The 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 'ORG_NAME-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"]
At a minimum, you must update the following settings with the appropriate values:
client_key
should point to the location of the Chef server user’s.pem
file on your ChefDK machine.validation_client_name
should be updated with the name of the desired organization that was created on the Chef server.validation_key
should point to the location of your organization’s.pem
file on your ChefDK machine.chef_server_url
must be updated with the domain or IP address used to access the Chef server.
See the knife config.rb documentation for more details.
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¶
The ChefDK is installed correctly when it is able to use knife
to communicate with the Chef server.
To verify that ChefDK can connect to the Chef server:
In a command window, navigate to the Chef repository:
cd ~/chef-repo
In a command window, enter the following:
knife client list
to return a list of clients (registered nodes and ChefDK installations) that have access to the Chef server. For example:
chefdk_machine registered_node