This article will provide examples of the chef commands that are used to manage Policyfiles.

For complete details on each of the commands, including options, and for changes to this list of commands, see the Policyfile command docs at https://docs.chef.io/policyfile/

chef Commands 

The following commands are built into the chef executable and support the use of Policyfile files.

chef clean-policy-cookbooks 

Use the chef clean-policy-cookbooks subcommand to delete cookbooks that are not used by Policyfile files. Cookbooks are considered unused when they are not referenced by any policy revisions on the Chef Infra Server.

Note

Cookbooks that are referenced by orphaned policy revisions are not removed. Use chef clean-policy-revisions to remove orphaned policies.

 

chef clean-policy-revisions 

Use the chef clean-policy-revisions subcommand to delete orphaned policy revisions to Policyfile files from the Chef Infra Server. An orphaned policy revision is not associated to any policy group and therefore is not in active use by any node. Use chef show-policy --orphans to view a list of orphaned policy revisions.

 

chef delete-policy 

Use the chef delete-policy subcommand to delete all revisions of the named policy that exist on the Chef Infra Server. (The state of the policy revision is backed up locally and may be restored using the chef undelete subcommand.)

 

chef delete-policy-group 

Use the chef delete-policy-group subcommand to delete the named policy group from the Chef Infra Server. Any policy revision associated with that policy group is not deleted. (The state of the policy group is backed up locally and may be restored using the chef undelete subcommand.)

 

chef diff 

Use the chef diff subcommand to display an itemized comparison of two revisions of a Policyfile.lock.json file.

Examples 

COMPARE CURRENT LOCK TO LATEST COMMIT ON LATEST BRANCH

chef diff --git HEAD

COMPARE CURRENT LOCK WITH LATEST COMMIT ON MASTER BRANCH

chef diff --git master

COMPARE CURRENT LOCK TO SPECIFIED REVISION

chef diff --git v1.0.0

COMPARE LOCK ON MASTER BRANCH TO LOCK ON REVISION

chef diff --git master...dev

COMPARE LOCK FOR VERSION WITH LATEST COMMIT ON MASTER BRANCH

chef diff --git v1.0.0...master

COMPARE CURRENT LOCK WITH LATEST LOCK FOR POLICY GROUP

chef diff staging

COMPARE LOCKS FOR TWO POLICY GROUP

chef diff production...staging

 

chef export 

Use the chef export subcommand to create a chef-zero-compatible chef-repo that contains the cookbooks described by a Policyfile.lock.json file. After a chef-zero-compatible chef-repo is copied to a node, the policy can be applied locally on that machine by running chef-client -z (local mode).

 

chef generate policyfile 

Use the chef generate policyfile subcommand to generate a file to be used with Policyfile.
 

chef generate repo 

Use the chef generate repo subcommand to create a chef-repo. By default, the repo is a cookbook repo with options available to support generating a cookbook that supports Policyfile.

Note

This subcommand requires using one (or more) of the options (below) to support Policyfile files.

 

chef install 

Use the chef install subcommand to evaluate a Policyfile and find a compatible set of cookbooks, build a run-list, cache it locally, and then emit a Policyfile.lock.json file that describes the locked policy set. The Policyfile.lock.json file may be used to install the locked policy set to other machines and may be pushed to a policy group on the Chef Infra Server to apply that policy to a group of nodes that are under management by Chef.

 

Policyfile.lock.json 

When the chef install command is run, Chef Workstation caches any necessary cookbooks and emits a Policyfile.lock.json file that describes:

• The versions of cookbooks in use

• A Hash of cookbook content

• The source for all cookbooks

A Policyfile.lock.json file is associated with a specific policy group, which means it is associated with one (or more) nodes that use the same revision of a given policy.

A Policyfile.lock.json file is similar to:

{
  "revision_id": "288ed244f8db8bff3caf58147e840bbe079f76e0",
  "name": "jenkins",
  "run_list": [
    "recipe[java::default]",
    "recipe[jenkins::master]",
    "recipe[policyfile_demo::default]"
  ],
  "cookbook_locks": {
    "policyfile_demo": {
      "version": "0.1.0",
      "identifier": "f04cc40faf628253fe7d9566d66a1733fb1afbe9",
      "dotted_decimal_identifier": "67638399371010690.23642238397896298.25512023620585",
      "source": "cookbooks/policyfile_demo",
      "cache_key": null,
      "scm_info": null,
      "source_options": {
        "path": "cookbooks/policyfile_demo"
      }
    },
  "java": {
    "version": "1.24.0",
    "identifier": "4c24ae46a6633e424925c24e683e0f43786236a3",
    "dotted_decimal_identifier": "21432429158228798.18657774985439294.16782456927907",
    "cache_key": "java-1.24.0-supermarket.chef.io",
    "origin": "https://supermarket.chef.io/api/v1/cookbooks/java/versions/1.24.0/download"",
    "source_options": {
      "artifactserver": "https://supermarket.chef.io/api/v1/cookbooks/java/versions/1.24.0/download"",
      "version": "1.24.0"
    }

 

chef push 

Use the chef push subcommand to upload an existing Policyfile.lock.json file to the Chef Infra Server, along with all of the cookbooks that are contained in the file. The Policyfile.lock.json file will be applied to the specified policy group, which is a set of nodes that share the same run-list and cookbooks.

 

chef push-archive 

The chef push-archive subcommand is used to publish a policy archive file to the Chef Infra Server. (A policy archive is created using the chef export subcommand.) The policy archive is assigned to the specified policy group, which is a set of nodes that share the same run-list and cookbooks.
 

chef show-policy 

Use the chef show-policy subcommand to display revisions for every Policyfile.rb file that is on the Chef Infra Server. By default, only active policy revisions are shown. When both a policy and policy group are specified, the contents of the active Policyfile.lock.json file for the policy group is returned.

 

chef undelete 

Use the chef undelete subcommand to recover a deleted policy or policy group. This command:

• Does not detect conflicts. If a deleted item has been recreated, running this command will overwrite it

• Does not include cookbooks that may be referenced by Policyfiles; cookbooks that are cleaned after running this command may not be fully restorable to their previous state

• Does not store access control data

 

chef update 

Use the chef update subcommand to read the Policyfile.rb file, and then apply any changes. This will resolve dependencies and will create a Policyfile.lock.json file. The locked policy will reflect any changes to the run-list and will pull in any cookbook updates that are compatible with any version constraints defined in the Policyfile.rb file.

 

For the entire documentation on Policyfiles, please go here .

This article provides a list of examples of the chef commands that can be used to manage your Policyfiles. To first learn about Policyfiles, you can find the 'About Policyfiles' article here - https://supportlink.chef.io/s/article/About-Chef-Policyfiles.