Chef Policies: Why, What, and How

On Wednesday, September 30th, software engineer Joshua Timberman presented a webinar on Chef Policies, a new feature of Chef. Policies combine the best parts of roles, environments, and client-side dependency resolvers such as Berkshelf into a single, easy-to-use workflow. By using policies, you can apply a specific set of cookbooks to a node or nodes with a single document. You can first  apply the policies in development, where they can be tested, and then promote them to production safely and reliably. Chef DK now includes a number of new commands to work with policies. In all, you’ll find that policies provide a much more delightful way to manage infrastructure with Chef.

A recording of the webinar is available below. Q&A from the live webinar, including the questions we didn’t have time to answer live is available at the end of this post.


Are Chef Policies stable? Can I use them in production?

We’re still putting the finishing touches on Chef, Chef Server, and ChefDK for a “1.0” release. The internal API is considered stable barring any extreme changes being required. The chef command-line interface is stable and will only add new commands. We know of some large organizations using Policyfiles for their cookbook development workflow.

Do we have to update every policy when a common cookbook is updated?

Yes, and we understand that is rather arduous right now since there isn’t a way to have hierarchy, nesting, layering, or otherwise including policyfiles in others. However, it does help against the case where a new version of a common cookbook totally breaks when combined with another one.

Can more than one policy name be assigned to a node?

No. Policy names are assigned through client.rb configuration, and will be a specific property on the node object in Chef 12.5/Chef Server 12.3. Named run lists will allow running chef with a different run list, though the cookbook locks will be identical. The goal is to enable use cases like override run lists for one-off tasks such as doing an application deployment, without a “base” run list that might take a long time.

Can policyfiles include other policyfiles?

Is there inheritance, hierarchy, or, how do you reduce duplication?

Not at this time. We are working on the design for this kind of feature, and it’s not clear what the best approach is. We want to get it right, and we want there to be a single, clear way to do it.

I have created an item on the feedback forum to implement something like this. Please add votes and comments about it.

Does Chef Manage (Chef Server Web UI) support Policyfiles?

Not at this time. We have an open item in the feedback forum about this.

Are all dependency cookbooks included?

When using chef install, it resolves the entire dependency graph of the cookbooks required to fulfill the run_list. If it cannot, it will return an error. The graph will contain transitive dependencies as well, and everything is written to the lock file and all cookbooks are cached.

What features / tools do Chef Policies and Policyfiles replace?

We consider that Chef Policies replace the following features or tools in the Chef ecosystem:

Roles. Chef Policies provide both run lists and attributes that can replace roles in most users’ workflows. The policy_name most closely resembles a role name for most use cases. Attributes can be specified in policyfiles, which will be applied at the “role” level.

Environments. Chef Policies provide cookbook version constraints that support the same operators as environments. They also have attributes that we believe will make “environment” attributes unnecessary, since changes will follow new policyfile revisions. The policy_group most closely resembles an environment for most use cases.

Node run lists. Nodes will have a configuration option that specifies the policy to use, and the run list is set by the policy.

Existing client-side dependency solvers. We have taken the best of breed features and implemented them in Chef Policies, and a cookbook-fetching library. Besides the default of using, users can specify custom locations for their cookbooks, such as from filesystem locations or git repositories just as with the other tools.

Chef Policies are a new, first class component of the Chef Server API. There is not integration with other parts of Chef with Policies, such as between environments, or roles. That kind of integration is up to end users to implement themselves if necessary.

Are those features / tools deprecated?

We recommend that users migrate to policyfiles for their workflows involving these features and tools. The whole point is to provide a cohesive, integrated workflow per the accepted RFC. We do not have a timeline on official deprecation or removal, as that creates backwards incompatibility that is hostile to users who are happy with their current workflow and existing tools.

What versions of Chef products do I need?

We recommend updating to:

  • ChefDK 0.8.0 for development workstations
  • Chef 12.4.3 for managed nodes
  • Chef Server 12.2

There are good improvements with Chef Server 12.3 and Chef Client 12.5. We recommend upgrading to those when they become available.

To upgrade your Chef Server, see or contact [email protected].

Do you have examples of Policyfiles in action?

For now, the best reference is Dan DeLeo’s “Policyfiles: A Guided Tour” blog post from August 18, 2015.

As this is still a new feature, we haven’t started adopting it widely internally yet. Some Chef employees plan to update their personal cookbooks, and we’ll have resources for them in Learn Chef, our Skills Library, and the Chef Docs. We also plan to integrate Policies into our formal training courses.

What are the available cookbook sources? Can I add more?

The default_source can refer to:

The cookbook statements can refer to:

  • :path, a filesystem path to the directory where a cookbook is located
  • :git, a git URI to the cookbook’s repository
  • :github, a “” organization/repo; hardcodes git:// in the URI; to use GitHub Enterprise, use a :git URI

To add custom sources, you would have to write that code yourself, and we don’t have any reference material on how to do it. Post to the chef-dev mailing list though, and we can lend a hand.

Jamie Bright

Former Chef employee