Switch branches/tags
818-check 953-ce 997-ce 1010-ce 1012-ce 1015-ce 1050-ce 1050.ce 1062-ce 1092-ce 1104-ce 1110-ce 1113-ce 1114-ce 1122-ce 1149-ce 1157-ce 1178-ce 1194-reopen 1238-ce 1250-ce 1251-ce 1252-ce 1257-ce 1308-ce SUSTAIN-788/reaper-config TheLunaticScripter-patch-1 ap/compliance-migration ap/update-automate-api-docs ascii aws-example-backups backend-failure-recovery btm/audit_mode cdn/automate-upgrade-nopostun chef-12-eol chef-13-resource-cloning chef-14-more-resources chef-14-resources chef-14-updated-resources chef-14-windows-resources chef-server-file chef-server-full-path chef-zero chefdk-install-restructure compliance-ga cookbook-s3-external-url credentials-mgmt ctl-automate-fix-typo data-collector debian-eol-policy deprecation-chocolatey-uninstall deprecation-deploy dw/automate_rel_note_updates dw/automate_1.7_bug_fix dw/less_verbose dw/update_jquery edit-resource-syntax enable-request-logging-version-tags eol-links es-and-ls-tunables fips-chef-client fix-buildkite-failures fix-chef-overview fix-data-retention-edit-link fix-plural-reporting-install fix-typo habitat-prism-removal install-dk-dpkg-rpm jcd/rewrite-support-policy jdm/include_policy jjasghar/centos7_install jjasghar/erchef jjasghar/sudo jjh/data_bag_item_example_use_abstraction jm/chefdk_3_4_release_notes kagarmoe-patch-1 kagarmoe-patch-2 kg/API-reporting kg/AWS-Auto kg/Visibility-more kg/audit-tables kg/auto-notes kg/auto17x-sidebar kg/automate_compliance kg/automate18 kg/azureportal kg/callitchef kg/compliance-api-update kg/compliance-latest kg/compliance-update kg/data-summary kg/dc-stubs kg/es-data-coll kg/fix-redirects kg/github kg/gitignore kg/kibana kg/merge-conficts kg/node-visibility kg/omnibus-list kg/privacy_policy kg/redirect3 kg/redirects kg/redirects2 kg/release_automate_18x kg/release_notes_17 kg/rename-client-page kg/resource-nav kg/sidebar-edit kg/two-guides kg/update-compliance kg/visibility kg/workstaion-shell kg/17x-automate-ctl kg/17xAdmin-Setup kgarmoe/number9 knife-environment-create lcg/deprecate-run-command lcg/namespace_collisions link-cleanup manage-symlink-source master mj/deprec mj/warning1 mjdkfixin multi-servers-automate mwrock-2016-1 mwrock-2016 nb/before-notification-example nb/bookshelf-sql nb/chef-airgap nb/chefdk-1-5-release-notes nb/client-13-2-release-notes nb/knife-links nb/knife-node-status nb/next-steps-automate nb/release-notes-server-12-16-9 nb/release-notes-title-updates nb/removing-for nb/rhel-system-z-support nb/server-backup nb/sphinx-build-updates nginx-welcome-page ohai-7 openstack-redirect pdf_builder platforms-table-width-adjustment praj/SUSTAIN-600 praj/delete_runner private-supermarket-install pwm/adroll rel-notes-automate-1-8-38 rel-notes-automate-dec-17 rel-notes-chef-14-update rel-notes-client-12-22-3 rel-notes-client-13-7-16 rel-notes-client-13-8 rel-notes-dk-1-6-11 rel-notes-dk-2-4-17 rel-notes-server-12-17-15 rel-notes-server-12-17-33 release-notes-chef-14 release-notes-chef-dk-2-2-1 release-notes-client-12-21-31 release-notes-dk-2-3-3 release-notes-dk-2-3-4 release-notes-server-12-16-14 relnotes-client-13-6-4 relnotes-client-various relnotes-dk-2-5 remove-compliance-release-notes remove-knife-sort remove-prism remove-ref-links2 remove-selinux-note remove-sphinx-links-pt-2 remove-vsphere resource_cleanup_v6 resource_cleanup_v9 resource_hostname resource_macos_userdefaults resource_ohai_hint resource_openssl_dhparam resource_openssl_rsa_private_key resource_openssl_rsa_public_key resource_rhsm_errata revert-948-kg/redirects revert-950-kg/redirects2 revert-1053-documentation-ip revert-1075-kg/node-visibility revert-1194-dh/update_doc_windows_service revert-1302-revert-windows-service-chef-14 revert-chef-14-stuff revert-windows-service-chef-14 robb/add-more-details-to-supermarket-reqs schisamo/automate-updates server-security sh/clarify-FIPS-statement sh/clarify-attr-file-load sh/deprecate-hide-healthy sh/document-veil-data-collector sh/example-auto-attribs sh/reindex-w-option-note sh/remove-obsolete-type sh/resize-volumes-online sh/update-fips-mode-support sh/webui-IE-issue shain/fix_bk_code shain/terraform sidebar-removals sp/windows-2019 ssd/SUSTAIN-751-2 ssd/SUSTAIN-751 ssd/chef-backend-1.4-setting ssd/chef-backend-upgrade-directions ssd/es-stale-lock-option ssd/sustain-751 stuart/windows-8-eol supermarket-contribute supermarket-options supermarket-s3 syntax-fix-relnotes-1-8-3 systemd-unit-example template-cookstyle template-copy test-provider-rebase thomascate-add-node-cleanup tm/policyfiles tm/solo_updates trevorghess-patch-1 troubleshooting-syntax true-false-class use-runners-not-build-nodes web windows-dism-fix windows-task-copy-edits workstation-syntax-fix
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
300 lines (177 sloc) 12.5 KB

Configuring ChefDK

[edit on GitHub]

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.


These instructions are intended for macOS and Linux users. For instructions on setting up your Ruby environment on Windows, see ChefDK on Windows.

  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.


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


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:

  1. Go to the following URL:
  2. Follow the directions, install Git (, and then complete the remaining configuration steps on that page.


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:

  1. 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.

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

       .chef/        << the hidden directory
  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

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:

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

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


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


    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.

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


  • 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:



  • -f FILE_NAME writes 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, a poorly-chosen password, and a USER.pem file saved to /tmp/grantmc.key:

$ chef-server-ctl user-create grantmc Grant McLennan 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:

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

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


    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 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          ''
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:

  1. In a command window, navigate to the Chef repository:

    cd ~/chef-repo
  2. 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: