When the time comes to upgrade Chef Client (for example from Chef 14 to Chef 15), operators need to be mindful of the associated changes and code refactoring that may be required. It's important to be proactive about these issues where possible and scope as much available time to the testing to ensure that no unforeseen issues arise as a result of upgrading.

In the event that proactive testing is not possible, the following issues may arise:

• Cookbooks become outdated, resources don't work as expected. Integration tests begin to catch errors in cookbooks which silently fail upon testing
• Client runs do not converge or break when they encounter legacy cookbooks which worked with a previous release of Chef Client

Update: We've released an in-depth blog post specific to upgrades at https://blog.chef.io/upgrading-your-cookbooks-for-compatibility-with-chef-infra-client-16/. The below is also a great supplement to have to hand and we recommend investing in both if considering coobook/client upgrades.

• First, head over to the following links and ensure that the combination of components in your environment are compatible and supported. Chef Client is backwards compatible and we maintain supported lists for platform/version of our products:
  https://docs.chef.io/platforms/
  https://docs.chef.io/versions/
• If you are considering a large migration of both server and client, please see the newly added Chef Upgrade Lab. This is designed to specifically ease the upgrade of Chef Client across nodes and is a worthwhile testing pattern to ensure stability and compatibility of your choice of client/server combination.
• The best plan is to move incrementally between each major release. Upgrading one major release at a time (e.g. 13 to 14, then 14 to 15) and ensuring that all deprecations are resolved with respect to the documentation provided to the version at the time. See the list of deprecations for Chef Client for further information.
• To begin the upgrade journey, we'd suggest you ensure that you are on the latest stable version of the existing Chef Client release, setting the client.rb in kitchen.yml as so:

client_rb: 
  treat_deprecation_warnings_as_errors: true 
  resource_cloning: false

This will catch all deprecations and make it clear as to whether anything is broken/deprecated and treated in a consistent manner in the runs.

• The next step is to upgrade (or update the version of Chef Cient you're running in test kitchen) to the release you'd like to test cookbooks against and observe any errors/issues that present themselves, matching them to the deprecation list previously described above.

• A Chef Client upgrade will also present a good opportunity to refactor cookbooks based on best practice and conformity to good Chef syntax. This can be aided with the use of Cookstyle, which not only validates the format/syntax of cookbooks, but also has the capacity to remediate the errors/mistakes. Please see Automatically Updating Cookbooks with Cookstyle

Further Reading

• Upgrading your Cookbooks for Compatibility with Chef Infra Client 16
• Chef Client list of deprecations
• Automatically Updating Cookbooks with Cookstyle
• Preparing for Chef 14 and Chef 12 End-of-Life
• Chef 101: The Road to Best Practices
• Chef Upgrade Lab