Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


chef_client_updater (62) Versions 3.2.1

Upgrades chef-client to specified releases

cookbook 'chef_client_updater', '= 3.2.1', :supermarket
cookbook 'chef_client_updater', '= 3.2.1'
knife supermarket install chef_client_updater
knife supermarket download chef_client_updater
Quality 100%


Build Status Cookbook Version

This cookbook updates the chef-client



  • All platforms with a chef-client package on


  • Chef 11.6.2+


This cookbook provides both a custom resource and a default recipe. The default recipe simply uses the custom resource with a set of attributes. You can add chef_client_updater::default to your run list or use the custom resource in a wrapper cookbook.

Init System Caveats

When Chef runs as a service under a system init daemon such as Sys-V or systemd each chef run forks off from the main chef-client process being managed by the init system. For a chef-client upgrade to occur the running chef-client as well as the parent process must be killed, and a new chef-client must start using the updated binaries. This cookbook handles killing the chef-client, but your init system must properly handle starting the service back up. For systemd and upstart this can be handled via configuration, and chef-client cookbook 8.1.1 or later handles this by default. This functionality is not available in sys-v (RHEL 6, Debian 7, and others), so you will need to employ a secondary process such as a monitoring system to start the chef-client service.

Updating Windows Nodes

There are a couple of considerations on Windows that have to be dealt with. The Chef Client installer uses a custom component to speed up the installation. This component does not gracefully handle open file handles the way the MSI installer does. To work around this, the resource moves the currently installed Chef Client to a staging directory and that clears the way for the newer installer to run. At the end of that installation process though, that Chef Client run must exit or it will fail trying to find files that do not exist in their expected locations. The next run of the Chef Client will use the newly installed version.

Running Chef Client as a Scheduled Task

If you run as a scheduled task, then this will work smoothly. The path to the newly installed Chef Client will be the same and the scheduled task will launch it. Part of this resource's job on the next run is to make sure the staging directory with the older client is removed.

Running Chef Client As A Windows Service

If you run Chef Client as a service, things get a tiny bit more complicated. When the new installer runs, the service is removed. This isn't a big deal if you've got the chef-client cookbook set to configure the Windows service. If that is the case, we can register a scheduled task to run shortly after the chef_client_updater terminates the current chef run. An example recipe might look like:

if Chef::VERSION < node['my_update_cookbook']['desired_version']
  run_chef_task_in_ten_minutes = + 600

  windows_task 'chef-client-upgrade' do
    cwd 'C:\\opscode\\chef\\bin'
    command 'chef-client'
    run_level :highest
    frequency :once
    start_time "#{run_chef_task_in_ten_minutes.strftime('%H:%M')}"
    action :create
  windows_task 'chef-client-upgrade' do
    cwd 'C:\\opscode\\chef\\bin'
    command 'chef-client'
    run_level :highest
    frequency :once
    start_time "#{run_chef_task_in_ten_minutes.strftime('%H:%M')}"
    action :delete

chef_client_updater 'Install latest Chef' do
  post_install_action 'kill'

Upgrading from Chef 11

Moving from Chef 11 has a few challenges when we are dealing with public update sources. Chef 11 ships with a very old cacert.pem. To work through this, we need to get a more current cacert.pem file and point OpenSSL to it. Unfortunately, for this to work consistently on Windows, we'll need to reboot. Chef 11 does not have the reboot resource, so this isn't a graceful process. However, on the next Chef run after the reboot, things will be back on track and the upgrade will perform as on other platforms.

Below is an example of a recipe that can set up Chef 11 to work using public update sources.

if platform_family?('windows') && (Chef::VERSION < '12')
  new_cert_file = File.join(ENV['USERPROFILE'], 'cacert.pem')

  remote_file new_cert_file do
    source ''
    action :create

  powershell_script 'restart' do
    code <<-EOH
    restart-computer -force
    action :nothing

  env 'SSL_CERT_FILE' do
    value new_cert_file
    notifies :run, 'powershell_script[restart]', :immediately

chef_client_updater 'Install latest Chef' do
  post_install_action 'kill'



Installs the mixlib-install/mixlib-install gems and upgrades the chef-client.


  • channel - The chef channel you fetch the chef client from. stable contains all officially released chef-client builds where as current contains unreleased builds. Default: stable
  • prevent_downgrade - Don't allow this cookbook to downgrade the chef-client version. Default: false
  • version - The version of the chef-client to install. Default :latest
  • post_install_action - After installing the chef-client what should we do. exec to exec the new client or kill to kill the client and rely on the init system to start up the new version. Default: kill
  • exec_command - The chef-client command. default: $PROGRAM_NAME.split(' ').first
  • exec_args - An array of arguments to exec the chef-client with. default: ARGV
  • download_url_override - The direct URL for the chef-client package.
  • checksum - The SHA-256 checksum of the chef-client package from the direct URL.


chef_client_updater 'Install latest'
chef_client_updater 'Install latest Chef 13.x' do
  version '13'
chef_client_updater 'Install 12.13.36 and kill' do
  version '12.13.36'
  post_install_action 'kill'

Test Kitchen Testing

In order to test this cookbook it will be necessary to change the post_install_action to exec from kill. While kill is better in most actual production use cases
as it terminates the chef-client run along with cleaning up the parent process, the use of kill under test kitchen will fail the chef-client run and fail the
test-kitchen run. The use of exec allows test-kitchen to complete and then re-runs the recipe to validate that the cookbook does not attempt to re-update the chef-client
and will succeed with the new chef-client. This, however, means that it is not possible to exactly test the config which will be running in production. The best practice
advice for this cookbook will be to ignore common best practices and not worry about that. If you change your production config to use exec in order to run what you test
in test-kitchen, then you will find sharp edge cases where your production upgrades will hang and/or fail, which testing will not replicate. In order to test you should
most likely test upgrades on your full-scale integration environment (not under test-kitchen) before rolling out to production and not use test-kitchen at all. If you
think that there's a rule that you must test absolutely everything you run under test-kitchen, you should probably
read this or this.

In order to test that your recipes work under the new chef-client codebase, you should simply test your cookbooks against the new version of chef-client that you wish
to deploy in "isolation" from the upgrade process. If your recipes all work on the old client, and all work on the new client, and the upgrader works, then the sum
of the parts should work as well (and again, if you really deeply care about the edge conditions where that might not work -- then test on real production-like images and
not with test-kitchen).

Use of 'exec' in production

This is highly discouraged since the exec will not clean up the supervising process. You're very likely to see it upgrade successfully and then see the old chef-client
process continue to run and fork off copies of the old chef-client to run again. Or for the upgrade process to hang, or for other issues to occur causing failed

You can use 'exec' in production if you are running from cron or some other process manager and firing off single-shot --no-fork chef-client processes without
using the --interval option. This will have the advantage that the new chef-client kicks off immediately after the upgrade giving fast feedback on any failures under
the new chef-client. The utility of this approach is most likely is not enough to justify the hassle.


This cookbook is maintained by Chef's Community Cookbook Engineering team. Our goal is to improve cookbook quality and to aid the community in contributing to cookbooks. To learn more about our team, process, and design goals see our team documentation. To learn more about contributing to cookbooks like this see our contributing documentation, or if you have general questions about this cookbook come chat with us in #cookbok-engineering on the Chef Community Slack


Copyright:: 2016-2017, Chef Software, Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

chef_client_updater Cookbook CHANGELOG

This file is used to list changes made in each version of the chef_client_updater cookbook.

3.2.1 (2018-01-25)

  • Added new attribute 'upgrade_delay' that defines delay in seconds before upgrading Chef client.

3.2.0 (2018-01-22)

  • Require mixlib-install 3.9 which includes initial support for proxies and support for Amazon Linux 2.0
  • Add additional debug logging for the installation
  • If the user provides an X.Y.Z format version don't contact Chef Inc's servers to validate the version
  • error out chef run if shell update fails

3.1.3 (2017-12-20)

  • Support custom paths to chef-client

3.1.2 (2017-11-22)

  • Windows: Support for downgrading the Chef client

3.1.1 (2017-11-14)

  • Windows: Bypass Powershell Execution Policy for upgrade scheduled task

3.1.0 (2017-11-01)

  • Raise if download_url_override is set but checksum isn't
  • Require a mixin-install that supports proxies
  • Improve how we perform the cleanup of the previous install directory on Windows
  • Remove a hardcoded path to the chef-client on Windows
  • Improve how we perform the Windows upgrade by using a scheduled task to avoid failures during the upgrade

3.0.4 (2017-08-17)

  • Fix gem install to actually install mixlib-install 3.3.4
  • Fix :latest resulting in chef installing on every run

3.0.3 (2017-08-10)

  • Add accurate logging for the rubygems upgrade to reflect that we're actually upgrading to the latest release.
  • Require mixlib-install 3.3.4 to prevent failures on Windows nodes due to architecture detection failing within mixlib-install
  • Add debug logging for the desired version logic
  • Improve logging of the version we're upgrading to in situations where the user provides either :latest or a partial version like '12'. Show the version we're upgrading to instead of what the user passed

3.0.2 (2017-08-08)

  • Improve logging to actually log when the upgrade occurs before we kill or exec the current chef-client run

3.0.1 (2017-07-14)

  • adding check for gem.cmd on chef-client 13 windows

3.0.0 (2017-07-14)

Breaking Changes

  • The default post install action for the resource has been switched from exec to kill. We believe that kill is the most likely default that users would expect as this allows a chef-client daemon running under a modern init system to cleanly upgrade. We highly recommend you check the readme and understand the exec and kill functions to determine which makes the most sense for how you run chef-client and how you execute the upgrade.
  • The prevent downgrade attribute for the default recipe has been changes from true to false as this is the default for the resource.

Other Changes

  • If chef-client is forked and the user specifies an 'exec' post install action we will now warn and then kill as exec will not worked in a forked run
  • Updated the windows task example in the readme to properly set the start time
  • Updated the minimum version of mixlib-install to download 3.3.1 which includes many fixes for windows clientsA
  • The resource now works around situations where mixlib-install may return an Array of versions

2.0.3 (2017-06-27)

  • Fix #31 detect centos platform correctly

2.0.2 (2017-06-22)

  • Fix air-gapped installation regression introduced by support for partial versions

2.0.1 (2017-06-16)

  • Add information on upgrading Windows nodes and upgrading from Chef 11 to the readme

2.0.0 (2017-06-15)

  • The custom resource has been converted to a LWRP so that we can support Chef Client updates from chef-client 11.6.2 to current. This also removes the need for the compat_resource cookbook.
  • Support for upgrading Windows clients has been added
  • A potential infinite loop in the upgrade process has been fixed
  • The existing /opt/chef directory will now be cleaned up before the reinstall so leftover files will not carry over during upgrades
  • Full Travis testing of the cookbook has been added

1.1.1 (2017-05-11)

  • Fix the initial load of mixlib-install failing

1.1.0 (2017-05-10)

  • Add support for download URL overrides via new properties on the resource and attributes for the default recipe. This requires mixlib-install 3.2.1, which we now ensure we install in the updater resource.
  • Update the default post_install action in the recipe to match the resource (exec).
  • Remove usage of class_eval in the resource since we use compat_resource and class_eval causes issues with some later Chef 12 releases.
  • Fix the solaris platform name in the metadata.rb.
  • Remove disabling FC016 and FC023 Foodcritic rules as these no longer alert.
  • Avoid infinite loops if trying to install the latest chef-client version from any channel.
  • Add a true test recipe and remove unused inspec tests
  • Add debug logging of the current vs. desired versions to help troubleshooting
  • Added a blurb in the readme outlining init system issues surrounding kill and the chef-client starting back up

1.0.2 (2017-04-07)

  • Fix Chef 13 compatibility by using Kernel.exec not exec

1.0.1 (2017-04-07)

  • point the URLs at the new project repo
  • Add ChefSpec matcher


  • Initial release of chef_client_updater

Collaborator Number Metric

3.2.1 passed this metric

Contributing File Metric

3.2.1 passed this metric

Foodcritic Metric

3.2.1 passed this metric

License Metric

3.2.1 passed this metric

No Binaries Metric

3.2.1 passed this metric

Testing File Metric

3.2.1 passed this metric

Version Tag Metric

3.2.1 passed this metric