Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Roles, Environments and Policyfiles

Policyfiles and Dependency Locking

Learn how Chef Policyfiles replace roles, environments and Berkshelf with one versioned, locked artifact, and build a dependency resolver and lock file in Ruby.

Roles and environments work, but they live on the server, change globally and are tested separately from the cookbooks they select. A Policyfile takes a different approach. You write one file that says "this is the run list, these are the cookbook sources and constraints". Chef resolves it once, on your workstation or CI server, and writes a lock file that pins every cookbook to an exact version and content hash. The lock file is the thing you test and deploy. What you tested is exactly what runs.

This lesson explains the Policyfile format, the lock file, policy groups (the new "environments"), and the workflow. You will also run a small dependency resolver that produces a lock file, so the idea of "solve once, lock, ship" becomes concrete.

The chef CLI and a Chef Server are not available on this site. Policyfile code and commands are read-only. The resolver below is a plain Ruby stand-in that shows what solving and locking mean.

A Policyfile

A file named Policyfile.rb:

Ruby
name 'webapp'

default_source :supermarket
default_source :chef_repo, 'cookbooks'

run_list 'base::default', 'nginx::default', 'myapp::default'

cookbook 'base',  path: 'cookbooks/base'
cookbook 'nginx', '~> 12.0'
cookbook 'myapp', git: 'https://git.example.com/chef/myapp.git', tag: 'v2.5.0'

default['myapp']['replicas'] = 2
override['nginx']['gzip'] = 'on'
  • name is the policy name.
  • default_source tells Chef where to look for cookbooks (the public Supermarket, a Git repo, or a local directory).
  • run_list lists recipes only, no roles, in order.
  • cookbook lines add constraints or custom sources.
  • Attributes set in the Policyfile apply at the default and override levels for the whole policy.

Policyfiles replace roles (the run list and attributes), environments (version constraints), and Berkshelf (dependency resolution) with one artifact.

Solve, lock, ship

Terminal
chef install            # resolve dependencies, write Policyfile.lock.json
chef update             # re-resolve to newer versions within constraints
chef push production    # upload the locked policy to policy group "production"
chef diff               # compare lock files or groups

chef install finds a set of cookbook versions that satisfies all constraints and writes Policyfile.lock.json: every cookbook with its exact version, source and an identifier (a content hash). Commit the lock file. chef push uploads the policy and its cookbooks to the server under a policy group.

flowchart LR
  P["Policyfile.rb"] -->|"chef install"| L["Policyfile.lock.json"]
  L -->|"chef push dev"| D["policy group: dev"]
  L -->|"chef push staging"| S["policy group: staging"]
  L -->|"chef push production"| R["policy group: production"]
  D --> N1["node A runs the locked policy"]

One locked artifact is pushed through the groups; the content never changes in between.

The lock file

A trimmed lock file looks like this:

JSON
{
  "name": "webapp",
  "revision_id": "5f1c...e9",
  "run_list": ["recipe[base::default]", "recipe[nginx::default]", "recipe[myapp::default]"],
  "cookbook_locks": {
    "base":  { "version": "1.4.2", "identifier": "a1b2...", "source": "cookbooks/base" },
    "nginx": { "version": "12.1.3", "identifier": "c3d4...", "source_options": { "artifactserver": "https://supermarket.chef.io/..." } }
  },
  "default_attributes": { "myapp": { "replicas": 2 } },
  "override_attributes": { "nginx": { "gzip": "on" } }
}

The revision_id is a hash over the whole policy, so any change to a cookbook or an attribute gives a new revision. Two nodes with the same revision are guaranteed to have the same code.

Stand-in: resolve and lock

Ruby Resolve constraints and write a lock file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

You can see how ~> 12.0 selects nginx 12.1.3 and pulls in ohai 6.1.0 because 12.1.3 only needs >= 5.0 and the newest satisfying version is taken. The second call fails: nginx 13 needs ohai >= 6.0, but another constraint wants < 6.0. A real solver backtracks and reports the conflict the same way.

Policy groups replace environments

A node is assigned to a policy name and a policy group, in client.rb or at bootstrap:

Ruby
policy_name 'webapp'
policy_group 'production'

Chef then downloads exactly the revision pushed to webapp in group production. To promote, you push the same lock file to the next group. There are no cookbook version constraints to evaluate at run time, no dependency solving on the server, and no surprise from someone uploading a new cookbook version.

Policyfiles versus roles and environments

Need Roles and environments Policyfiles
What runs Run list on the node and role on the server run_list in the Policyfile
Version control Constraints in environments, edited live Exact versions in the lock file
Test equals production Not guaranteed Guaranteed, same revision
Dependency solving On the server, per run On your machine, once
Rollback Edit constraints Push the previous lock file

Practical tips

  • Commit both Policyfile.rb and Policyfile.lock.json.
  • Use one Policyfile per kind of server, with shared base cookbooks.
  • Run chef update deliberately and review the diff of the lock file.
  • Wrapper cookbooks (a "role cookbook" that includes others) fit nicely into a Policyfile run list.
  • Policyfiles cannot use roles or environments; with a Policyfile node they are ignored.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does chef install produce?

    chef install resolves constraints and writes the lock file, which records exact versions and identifiers.
  2. 2. What replaces environments in a Policyfile workflow?

    You push a locked policy to a policy group such as dev, staging or production, and nodes belong to one group.
  3. 3. Why is a lock file useful for testing?

    The revision hash identifies the full policy. The same revision means the same cookbook code everywhere.
  4. 4. Which entries may appear in a Policyfile run_list?

    Policyfile run lists contain recipes only; the policy itself takes over the job of roles.

Summary

  • A Policyfile defines the run list, cookbook sources and constraints, and attributes in one file.
  • chef install resolves versions once and writes Policyfile.lock.json; chef push uploads it to a policy group.
  • Policy groups replace environments, and nodes get exactly the pushed revision.
  • Compared with roles and environments, Policyfiles give reproducible, testable, reversible deployments.

Next: Test Kitchen: Testing on Real Machines