About Berkshelf
Warning
Policyfiles are the preferred pattern for creating immutable collections of cookbooks, cookbook dependencies, and attributes. Berkshelf is no longer under active development. Please replace Berkshelf with Policyfiles
This document is no longer maintained.
Berkshelf is a dependency manager for Chef cookbooks. With it, you can depend on community cookbooks and include them in your workflow. You can also ensure that your CI systems reproducibly select the same cookbook versions, and can upload and bundle cookbook dependencies without needing a locally maintained copy. Berkshelf is included in Chef Workstation.
Note
Quick Start
Run chef generate cookbook -b
or --berks
to create a Berksfile in
the root of the cookbook. The Berksfile will be placed alongside the
cookbook’s metadata.rb file. As usual, add your cookbook’s dependencies
to the metadata.rb file:
name 'my_first_cookbook'
version '0.1.0'
depends 'apt', '~> 5.0'
The default Berksfile
will contain the following:
source 'https://supermarket.chef.io'
metadata
Now, when you run berks install
, the apt cookbook will be downloaded
from Supermarket into the cache:
berks install
Resolving cookbook dependencies...
Fetching 'my_first_cookbook' from source at .
Fetching cookbook index from https://supermarket.chef.io...
Installing apt (5.0.0)
Using my_first_cookbook (0.1.0) from source at .
Installing compat_resource (12.16.2)
In this example, the compat_resource
cookbook is also installed since
it’s a dependency of the apt
cookbook. Running the install command
also creates a Berksfile.lock
, which represents exactly which cookbook
versions Berkshelf installed. This file ensures that someone else can
check the cookbook out of git and get exactly the same dependencies as
you.
You can now upload all cookbooks to your Chef Infra Server with
berks upload
:
berks upload
Uploaded apt (5.0.0) to: 'https://api.chef.io:443/organizations/example'
Uploaded compat_resource (12.16.2) to: 'https://api.chef.io:443/organizations/example'
Uploaded my_first_cookbook (0.1.0) to: 'https://api.chef.io:443/organizations/example'
The Berksfile
A Berksfile describes the set of sources and dependencies needed to use
a cookbook. It is used in conjunction with the berks
command.
Syntax
A Berksfile is a Ruby file, in which sources, dependencies, and options may be specified. Berksfiles are modeled on Bundler’s Gemfile. The syntax is as follows:
source "https://supermarket.chef.io"
metadata
cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]
Source Keyword
A source defines where Berkshelf should look for cookbooks. Sources are processed in the order that they are defined in, and processing stops as soon as a suitable cookbook is found. Locations include a private or public Supermarket, Chef Infra Server, or local Chef repository.
By default, a Berksfile has a source for Chef’s public Supermarket:
source "https://supermarket.chef.io"
To add a private Supermarket, which will be preferred:
source "https://supermarket.example.com"
source "https://supermarket.chef.io"
To add a Chef Infra Server:
source "https://supermarket.chef.io"
source :chef_server
To add a local Chef repository:
source "https://supermarket.chef.io"
source chef_repo: ".."
The location and authentication details for the Chef Infra Server will
be taken from the user’s config.rb
by default.
To add multiple Chef Infra Servers:
source "https://supermarket.chef.io"
source chef_server: "https://mychefserver.example.com/organizations/one", client_name: "one-client", client_key: "/path/to/one-client.pem"
source chef_server: "https://mychefserver.example.com/organizations/two", client_name: "two-client", client_key: "/path/to/two-client.pem"
To use an Artifactory server as a source:
source artifactory: "https://artifactory.example.com/api/chef/nameofrepo", api_key: "XZg6tefUZYfiglmSbQ1s1e6habk"
If the api_key
option is not given, it will use the value of the
$ARTIFACTORY_API_KEY
environment variable by default.
Metadata Keyword
The metadata
keyword causes Berkshelf to process the local cookbook
metadata. This ensures that the dependencies of the cookbook are
resolved by Berkshelf. Using the metadata
keyword requires that the
Berksfile be placed in the root of the cookbook, next to metadata.rb
.
Cookbook Keyword
The cookbook
keyword allows the user to define where a cookbook is
installed from, or to set additional version constraints. It can also be
used to install additional cookbooks, for example to use during testing.
The format of a cookbook
stanza is as follows:
cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]
The simplest form is:
cookbook "library-cookbook"
This ensures that a cookbook named library-cookbook
is installed by
berkshelf.
Version constraints are the second parameter:
cookbook "library-cookbook", "~> 0.1.1"
These are identical to the version constraints in a cookbook metadata file.
Source options are used to specify the location to acquire a cookbook from, or to place a cookbook in a group. By default, cookbooks are acquired from the default sources, but it’s possible to override this on a case by case basis. Often this is used to get a development cookbook from Git, or to use another cookbook in a monolithic cookbook repository.
Path Location
The path location enables Berkshelf to use a cookbook located on the
same system. It does not cache the target cookbook, ensuring that the
latest version is always used. The target must be a single cookbook with
a metadata.rb
.
cookbook "library-cookbook", "~> 0.1.1", path: "../library-cookbook"
Git Location
The git location enables Berkshelf to use acquire a cookbook from a git repository.
cookbook "library-cookbook", "~> 0.1.1", git: "https://github.com/example/library-cookbook.git"
The user can specify a git branch or a tag (the options are synonymous) using an optional argument:
cookbook "library-cookbook", "~> 0.1.1", git: "https://github.com/example/library-cookbook.git", branch: "smartos-dev"
cookbook "library-cookbook", "~> 0.1.1", git: "https://github.com/example/library-cookbook.git", tag: "1.2.3"
The user can also specify a revision:
cookbook "library-cookbook", "~> 0.1.1", git: "https://github.com/example/library-cookbook.git", ref: "eef7e65806e7ff3bdbe148e27c447ef4a8bc3881"
If a git repository contains many cookbooks, the user can specify the
path to the desired cookbook using the rel
option:
cookbook "library-cookbook", "~> 0.1.1", git: "https://github.com/example/cookbook-repo.git", rel: "library-cookbook"
GitHub Location
If a cookbook is in GitHub, you can use the github:
shorthand to refer
to it:
cookbook "library-cookbook", "~> 0.1.1", github: "example/library-cookbook"
Any other git options are valid for a GitHub location.
Groups
Adding cookbooks to a group is useful should you wish to exclude certain cookbooks from upload or vendoring.
Groups can be defined via blocks:
group :test do
cookbook "test-cookbook", path: "test/fixtures/test"
end
Groups can also be specified inline:
cookbook "test-cookbook", path: "test/fixtures/test", group: :test
To exclude a group when using berks
, use the --except
flag:
berks install --except test
Solver Keyword
It is possible to configure which engine to use for the solve dependency resolution system.
By default, the solver selection depends on your environment. When the
dep_selector
gem is installed, as in the case of Chef Workstation, the
gecode
solver is used. Otherwise, the ruby
solver is utilized by
default.
The gecode
solver matches the engine used by the Chef Infra Server, so it reflects the behavior of the Chef Infra Server in selecting cookbooks:
solver :gecode
The ruby
solver can give better results in some situations, notably
when Berkshelf times out when trying to build a dependency set.
solver :ruby
Berkshelf CLI
The Berkshelf CLI is the interface to Berkshelf.
Common Options
-c PATH
,--config PATH
The path to the Berkshelf configuration file.
-d
,--debug
Use to print debug information. Default value:
false
.-F JSON
,--format JSON
Use to specify the output format to be used. Default value:
human
Possible values:base
,human
,json
, andnull
.-q
,--quiet
Use to silence all informational output. Default value:
false
.
berks apply
Use berks apply
to apply Berksfile version locks to the named
environment on the Chef Infra Server.
Syntax
This subcommand has the following syntax:
berks apply ENVIRONMENT (options)
Options
This command has the following options:
-b LOCK_FILE_PATH
,--lockfile LOCK_FILE_PATH
The path to the Berksfile lock file from which Berksfile version locks are applied.
-f JSON_FILE_PATH
,--envfile PATH
The path to an environment file (in JSON format) to which Berksfile version locks are applied.
--ssl-verify
Use to enable (
true
) or disable (false
) SSL verification when applying Berksfile version locks to an environment.
berks contingent
Use berks contingent
to list all cookbooks in a Berksfile that depend
on the named cookbook.
Syntax
This subcommand has the following syntax:
berks contingent COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the cookbook is located.
berks cookbook
Use berks cookbook
to create a skeleton for a new cookbook.
Warning
chef generate cookbook
instead.berks info
Use berks info
to display the name, author, copyright, and dependency
information for the named cookbook.
Syntax
This subcommand has the following syntax:
berks info COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the cookbook is located.
berks init
Use berks init
to initialize Berkshelf to the specified directory.
Warning
chef generate cookbook
instead.berks install
Use berks install
to install cookbooks into the cache. This command
generates the Berkshelf lock file that ensures consistency.
Syntax
This subcommand has the following syntax:
berks install (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the cookbook is located.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be listed.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be listed. When this option is used, cookbooks that exist in groups not listed will not be listed.
berks list
Use berks list
to list cookbooks and their dependencies.
Syntax
This subcommand has the following syntax:
berks list (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the cookbook is located.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be listed.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be listed. When this option is used, cookbooks that exist in groups not listed will not be listed.
berks outdated
Use berks outdated
to list dependencies for the named cookbook, and
then check if there are new versions available for version constraints
that may exist.
Syntax
This subcommand has the following syntax:
berks outdated COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the cookbook is located.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be checked for version constraints.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be checked for version constraints. When this option is used, cookbooks that exist in groups not listed will not be checked for version constraints.
berks package
Use berks package
to vendor, and then archive the dependencies of a
Berksfile.
Syntax
This subcommand has the following syntax:
berks package PATH (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile to be vendored, and then archived.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be vendored, and then archived.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be vendored, and then archived. When this option is used, cookbooks that exist in groups not listed will not be vendored or archived.
berks search
Use berks search
to search the remote source for cookbooks that match
the search query. The query itself will match partial cookbook names.
Syntax
This subcommand has the following syntax:
berks search QUERY (options)
Options
This command has the following options:
--source URL
The URL at which remote cookbooks are located. Default value:
https://supermarket.chef.io
.
berks show
Use berks show
to show the path to the named cookbook.
Syntax
This subcommand has the following syntax:
berks show COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the named cookbook is defined.
berks update
Use berks update
to update the named cookbook or cookbooks (and any
dependencies).
Syntax
This subcommand has the following syntax:
berks update COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the named cookbook is defined.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be updated.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be updated. When this option is used, cookbooks that exist in groups not listed will not be updated.
berks upload
Use berks upload
to upload the named cookbook to the Chef Infra
Server.
Syntax
This subcommand has the following syntax:
berks upload COOKBOOK (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile in which the named cookbook is defined.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be uploaded.
--force
Use to upload any named cookbook even if that cookbook exists on the Chef Infra Server and is frozen.
--halt-on-frozen
Use to exit the command with a non-zero exit code if this version of a cookbook already exists on the Chef Infra Server.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be uploaded. When this option is used, cookbooks that exist in groups not listed will not be uploaded.
--no-freeze
A frozen cookbook requires changes to that cookbook to be submitted as a new version of that cookbook. Use this option to prevent this cookbook from being frozen. Default value:
false
(that is, “frozen”).--ssl-verify
Use to enable (
true
) or disable (false
) SSL verification when uploading cookbooks to the Chef Infra Server.-s
,--skip-syntax-check
Use to skip Ruby syntax checking when uploading a cookbook to the Chef Infra Server. Default value:
false
.
berks vendor
Use berks vendor
to vendor groups of cookbooks (as specified by group
name) into a directory.
Syntax
This subcommand has the following syntax:
berks vendor PATH (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile from which cookbooks will be vendored.
--delete
Use to clean the directory in which vendored cookbooks will be placed before executing this command.
-e [GROUP, GROUP, ...]
,--except [GROUP, GROUP, ...]
An array of cookbook groups that will not be vendored.
-o [GROUP, GROUP, ...]
,--only [GROUP, GROUP, ...]
An array of cookbook groups to be vendored. When this option is used, cookbooks that exist in groups not listed will not be vendored.
berks verify
Use berks verify
to perform a validation of the contents of resolved
cookbooks.
Syntax
This subcommand has the following syntax:
berks verify (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile from which resolved cookbooks are validated.
berks version
Use berks version
to display the version of Berkshelf.
berks viz
Use berks viz
to generate a dependency graph image file.
Syntax
This subcommand has the following syntax:
berks viz (options)
Options
This command has the following options:
-b PATH
,--berksfile PATH
The path to the Berksfile for which the dependency graph is built.
-o NAME
,--outfile NAME
The name of the file to which output is saved. Default value:
graph.png
.