Project: Chef Infra (Provisioning / Automation & Configuration)
File: upgrading_from_chef_12.md

title: Upgrading From Chef 12 This is not a general guide on how to upgrade from Chef Infra 12. There already exists documentation on: This is strictly expert-level documentation on what the large scale focus should be and what kind of otherwise undocumented gotchas can occur. In order to see all deprecation warnings, users must upgrade through every major version and must run the last version of chef-client for each major version. That means that a user on Chef Infra 12.11.18 must first upgrade to Chef Infra 12.21.31, then to Chef Infra 13.12.14, then (as of this writing) to Chef Infra 14.13.11 before upgrading to the latest Chef Infra 15. It is always the rule that the prior minor version of Chef Infra Client has all the deprecation warnings that are necessary to be addressed for the next major version. Once we begin development on the next major version of the Client we delete all the code and all the deprecation warnings. Old cookbook code can no longer receive warnings, it will simply wind up on new code paths and fail hard. The old Chef Infra Client code which issued the deprecation warning has necessarily been removed as part of cleaning up and changing to the new behavior. This makes it impossible to skip versions from Chef Infra Client 12 directly to 14 and still address all the deprecations. It is not necessary to upgrade the entire production environment to those versions of Chef Infra Client, but test-kitchen must be run on those versions of Chef Infra Client, and the deprecations must be fixed in all the cookbooks. The `treatdeprecationwarningsaserrors` flag to the test-kitchen provisioner may be useful to accomplish this: ``` provisioner: name: chef_zero client.rb: treatdeprecationwarningsaserrors: true ``` An very notable exception to the above rule that all deprecation warnings must be addressed is the old CHEF-3694 deprecation warnings. Not all of these warnings must be fixed. It was not possible to determine in code which of them were important to fix and which of them could be ignored. In actual fact most of them can be ignored without any impact. The only way to test which ones need fixing, though, is to run the cookbooks through Chef Infra 13 or later and test the behavior. If the cookbooks work, then the warnings can be ignored. All the deprecation warnings do in this case are warn that there might some risk of behavior change on upgrade. The technical details of the issue is that with resource cloning the properties of resources that are declared multiple times is that the properties of the prior research are merged with the newly declared properties and that becomes the resource. That accumulated state goes away when upgrading from Chef Infra

The problem is that determining if that state was important or not to the specific resource being merged requires knowledge of the semantic meaning of the properties being merged. They may be important or they may not, and it requires the user to make that determination. In most cases the merged resources are fairly trivial and the merged properties do not substantially change any behavior that is meaningful and the cookbooks will still work correctly. To ignore these errors while still treating deprecations as error you can use the `silencedeprecationwarnings` config in test-kitchen: ``` provisioner: name: chef_zero client.rb: treatdeprecationwarningsaserrors: true silencedeprecationwarnings: chef-3694 ``` Chef Infra 15 largely supports the same resource styles as Chef Infra 11 did. It is not necessary to convert all providers files or all library-resources to the fused style with the actions declared directly in the resources file. That style is preferable to older ways of writing resources, but it should never be a blocker to getting off of unsupported Chef Infra 12. Upgrading should always take priority over code cleanup. There are a few necessary changes to resources which need to occur, but minimal changes should be required. Introduced in Chef Infra 11.0 this became the way to write providers in Chef Infra 13.0. Existing Chef Infra 12 code should always declare `useinlineresources` and should be run through test-kitchen and deployed in preparation for upgrading. The only problem with introducing this change would be resources which expect to be able to modify the resources declared in outer scopes. Another name for this is the `accumulator` pattern of writing chef resources. Those kinds of resources will break once they are placed in the sub-`runcontext` that `useinline_resources` creates. Those kinds of resources should use the `withruncontext :root` helper in order to access those resources in the outer `runcontext`. The use of the `resourcecollection` editing utilities `findresource` and `editresource` will also be useful for addressing those problems. Since the vast majority of chef resources do not do this kind of editing of the resource collection, the vast majority of chef resources will run successfully with `useinlineresources` declared. Once the entire infrastructure is off of Chef Infra 12 then the `useinlineresources` lines may be deleted. The automatic naming of classes after the DSL name of the resource was removed in Chef Infra 13.0, as a result in order to implement a `loadcurrentresource` function the construction of the `current_resource` must change. Old code: ```ruby def loadcurrentresource @currentresource = Chef::Resource::MyResource.new(@newresource.name) [ ... rest of implementation ... ] end ``` New code: ```ruby def loadcurrentresource @currentresource = newresource.class.new(@new_resource.name) [ ... rest of implementation ... ] end ``` Resources may be rewritten instead to use `loadcurrentvalue`, but that is not required to upgrade. The way to look up the class of a Resource: ```ruby @klass = Chef::Resource.resourcefornode(:package, node) ``` The way to get an instance of a Provider: ```ruby @klass = Chef::Resource.resourcefornode(:package, node) @provider = klass.providerforaction(:install) ``` Do not inject provider classes via the `provider` method on a

It should not be necessary to get the class of the provider for injecting in a `provider` method on a resource. This code is brittle as of Chef Infra 12 and becomes worse in Chef Infra 13 and beyond: ```ruby packageclass = if shoulddo_local? Chef::Provider::Package::Rpm else Chef::Provider::Package::Yum end package "lsof" do provider package_class action :upgrade end ``` This actually constructs a `Chef::Resource::YumPackage` resource wrapping a `Chef::Provider::Package::Rpm` object if `shoulddolocal?` is true, which is not a consistent set of objects and will ultimately cause bugs and problems. The correct way to accomplish this is by dynamically constructing the correct kind of resource (ultimately via the `Chef::ResourceResolver`) rather than manually trying to construct a hybrid object: ```ruby packageresource = if shoulddo_local? :rpm_package else :yum_package end declareresource(packageresource, "lsof") do action :upgrade end ``` This section is an uncommon need. Very few cookbooks should be dynamically declaring providers. The requirement to look up resource classes and provider instances would likely also only occur for sites which do roll-your-own `rspec` testing of resources (similar to the way resources are tested in core chef) instead of `chefspec` or `test-kitchen` testing. A behavior change which occurred in Chef Infra 12.21.3 which later was recognized to potentially be breaking is that custom resources now have their own delayed notification phase. If it is necessary to create a resource, like a service resource, in a custom resource and then send a delayed notification to it which is executed at the end of the entire chef client run (and not at the end of the execution of the custom resource's action) then the resource needs to be declared in the outer "root" or "recipe" run context. This code in Chef Infra before 12.21.3 would restart the service at the end of the run: ```ruby useinlineresources action :doit do service "whateverd" do action :nothing end file "/etc/whatever.d/whatever.conf" do contents "something" notifies :restart, "service[whateverd]", :delayed end end ``` To preserve this exact behavior in version of Chef Infra Client of 12.21.3 or later: ```ruby useinlineresources action :doit do withruncontext :root do find_resource(:service, "whateverd") do action :nothing end end file "/etc/whatever.d/whatever.conf" do contents "something" notifies :restart, "service[whateverd]", :delayed end end ``` This behavior is not backwards compatible, and the code which executes properly on 12.21.3 will not run properly on version before that, and vice versa. There are no deprecation warnings for this behavior, it was not anticipated at the time that this would produce any backwards incompatibility and by the time it was understood there was no way to retroactively change behavior or add any warnings. It is not a common issue. The new behavior is more typically preferable since it asserts that the once the configuration for the service is updated that the service is restarted by the delayed action which occurs at the end of the custom resource's action and then future recipes can rely on the service being in a correctly running state.