Policyfile.rb¶
A Policyfile is an optional way to manage role, environment, and community cookbook data with a single document that is uploaded to the Chef server. The file is associated with a group of nodes, cookbooks, and settings. When these nodes perform a Chef client run, they utilize recipes specified in the Policyfile run-list.
Note
Consider the following before using Policyfiles:
- Policyfile is not supported as part of a Chef Automate workflow
A Policyfile file allows you to specify in a single document the cookbook revisions and recipes that should be applied by the chef-client. A Policyfile file is uploaded to the Chef server, where it is associated with a group of nodes. When these nodes are configured by the chef-client, the chef-client will make decisions based on settings in the policy file, and will build a run-list based on that information. A Policyfile file may be versioned, and then promoted through deployment stages to safely and reliably deploy new configuration.
Note
For more information about Policyfile, see About Policyfile
Syntax¶
A Policyfile.rb
is a Ruby file in which run-list and cookbook locations are specified. The syntax is as follows:
name "name"
run_list "ITEM", "ITEM", ...
default_source :SOURCE_TYPE, *args
cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]
Settings¶
A Policyfile.rb
file may contain the following settings:
name "name"
- Required. The name of the policy. Use a name that reflects the purpose of the machines against which the policy will run.
run_list "ITEM", "ITEM", ...
- Required. The run-list the chef-client will use to apply the policy to one (or more) nodes.
default_source :SOURCE_TYPE, *args
The location in which any cookbooks not specified by
cookbook
are located. Possible values:chef_repo
,chef_server
,:community
,:supermarket
, and:artifactory
. Use more than onedefault_source
to specify more than one location for cookbooks.default_source :supermarket
pulls cookbooks from the public Chef Supermarket.default_source :supermarket, "https://mysupermarket.example"
pulls cookbooks from a named private Chef Supermarket.default_source :chef_server, "https://chef-server.example/organizations/example"
pulls cookbooks from the Chef Server.default_source :community
is an alias for:supermarket
.default_source :chef_repo, "path/to/repo"
pulls cookbooks from a monolithic cookbook repository. This may be a path to the top-level of a cookbook repository or to the/cookbooks
directory within that repository.default_source :artifactory, "https://artifactory.example/api/chef/my-supermarket"
pulls cookbooks from an Artifactory server. Requires eitherartifactory_api_key
to be set inconfig.rb
orARTIFACTORY_API_KEY
to be set in your environment.Multiple cookbook sources may be specified. For example from the public Chef Supermarket and a monolithic repository:
default_source :supermarket default_source :chef_repo, "path/to/repo"
or from both a public and private Chef Supermarket:
default_source :supermarket default_source :supermarket, "https://supermarket.example"
Note
If a run-list or any dependencies require a cookbook that is present in more than one source, be explicit about which source is preferred. This will ensure that a cookbook is always pulled from an expected source. For example, an internally-developed cookbook named
chef-client
will conflict with the publicchef-client
cookbook that is maintained by Chef. To specify a named source for a cookbook:default_source :supermarket default_source :supermarket, "https://supermarket.example" do |s| s.preferred_for "chef-client" end
List multiple cookbooks on the same line:
default_source :supermarket default_source :supermarket, "https://supermarket.example" do |s| s.preferred_for "chef-client", "nginx", "mysql" end
cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]
Add cookbooks to the policy, specify a version constraint, or specify an alternate source location, such as Chef Supermarket. For example, add a cookbook:
cookbook "apache2"
Specify a version constraint:
run_list "jenkins::master" # Restrict the jenkins cookbook to version 2.x, greater than 2.1 cookbook "jenkins", "~> 2.1"
Specify an alternate source:
cookbook 'my_app', path: 'cookbooks/my_app'
or:
cookbook 'mysql', github: 'opscode-cookbooks/mysql', branch: 'master'
or:
cookbook 'chef-ingredient', git: 'https://github.com/chef-cookbooks/chef-ingredient.git', tag: 'v0.12.0'
named_run_list "NAME", "ITEM1", "ITEM2", ...
Specify a named run-list to be used as an alternative to the override run-list. This setting should be used carefully and for specific use cases, like running a small set of recipes to quickly converge configuration for a single application on a host or for one-time setup tasks. For example:
named_run_list :update_app, "my_app_cookbook::default"
include_policy "NAME", *args
- New in ChefDK 2.4 Specify a policyfile lock to be merged with this policy. ChefDK supports pulling this lock from a local file or from Chef server. When the policyfile lock is included, its run-lists will appear before the current policyfile’s run-list. This setting requires that the solved cookbooks appear as-is from the included policyfile lock. If conflicting attributes or cookbooks are provided, an error will be presented. See RFC097 for the full specifications of this feature.
Pull the policyfile lock from
./NAME.lock.json
:include_policy "NAME", path: "."
Pull the policyfile lock from
./foo.lock.json
.include_policy "NAME", path: "./foo.lock.json"
Pull the policy
NAME
with revision IDrevision1
from thehttp://chef-server.example
Chef server:include_policy "NAME", policy_revision_id: "revision1", server: "http://chef-server.example"
Pull the policy
foo
with revision IDrevision1
:include_policy "NAME", policy_name: "foo", policy_revision_id: "revision1", server: "http://chef-server.example"
Pull and lock the current revision for policy
foo
in policy groupprod
:include_policy "NAME", policy_name: "foo", policy_group: "prod", server: "http://chef-server.example"
Example¶
For example:
name "jenkins-master"
run_list "java", "jenkins::master", "recipe[policyfile_demo]"
default_source :supermarket, "https://mysupermarket.example"
cookbook "policyfile_demo", path: "cookbooks/policyfile_demo"
cookbook "jenkins", "~> 2.1"
cookbook "mysql", github: "chef-cookbooks/mysql", branch: "master"