chef (executable)¶
The chef executable is a command-line tool that does the following:
- Generates repositories, cookbooks, recipes, attributes, templates, and custom resources.
- Installs gems into the Chef development environment’s Ruby installation.
- Verifies that all components are installed and configured correctly
chef env¶
Use the chef env
subcommand to configure the environment for the Chef development kit.
Options¶
This command does not have any specific options.
Examples¶
None.
chef exec¶
Use the chef exec
subcommand to run arbitrary shell commands with the PATH
environment variable and the GEM_HOME
and GEM_PATH
Ruby environment variables pointed at the Chef development kit.
Options¶
This subcommand has the following options:
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef gem¶
The chef gem
subcommand is a wrapper around the gem
command in RubyGems and is used by Chef to install RubyGems into the Chef development kit development environment. All knife plugins, drivers for Kitchen, and other Ruby applications that are not packaged within the Chef development kit will be installed to the .chefdk
path in the home directory: ~/.chefdk/gem/ruby/ver.si.on/bin
(where ver.si.on
is the version of Ruby that is packaged within the Chef development kit).
Options¶
This subcommand has the following options:
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
Show an existing gem in the chef-dk
To show a gem, run a command similar to:
$ chef gem list chef-dk
to return something similar to:
*** LOCAL GEMS ***
chef-dk (0.1.0)
List all local gems
To list all of the installed gems on your development environment, use the list
command without any arguments:
$ chef gem list
Search for local gems
The list
command can also be used to search for locally installed gems. For example, to list all of the gems with knife
in their title:
$ chef gem list knife
which returns the following output:
*** LOCAL GEMS ***
knife-opc (0.3.2)
knife-push (1.0.2)
knife-spork (1.6.3)
knife-windows (1.9.0)
Search remote gems
Use the search
command to search for remote gems available for installation:
$ chef gem search kitchen
to return something similar to:
*** REMOTE GEMS ***
chefkitchen_cli (0.0.1)
gst-kitchen (0.9.0)
guard-kitchen (0.0.2)
jackal-kitchen (0.1.2)
jackal-kitchen-slack (0.1.2)
kitchen (0.0.3)
Install a gem
To install a gem, run a command similar to:
$ chef gem install knife-config
to return something similar to:
Successfully installed knife-config-1.1.0
1 gem installed
Uninstall a gem
To uninstall a gem from the Chef development kit environment:
$ chef gem uninstall knife-config
to return something similar to:
Successfully uninstalled knife-config-1.1.0
View the contents of a gem
To view the contents of a gem, run a command similar to:
$ chef gem content knife-config
to return something similar to:
/Users/user/.chefdk/gem/ruby/2.1.0/gems/knife-config-1.1.0/LICENSE
/Users/user/.chefdk/gem/ruby/2.1.0/gems/knife-config-1.1.0/README.md
/Users/user/.chefdk/gem/ruby/2.1.0/gems/knife-config-1.1.0/lib/chef/knife/config.rb
/Users/user/.chefdk/gem/ruby/2.1.0/gems/knife-config-1.1.0/lib/knife-config.rb
chef generate app¶
Note
This command is built around the idea that there should be a middle ground between the “one cookbook per repo” and the “all cookbooks in one repo” approaches.
Use the chef generate app
subcommand to generate a cookbook structure that:
- Supports multiple cookbooks (as many as needed to support an “application”)
- Supports a top-level instance of Kitchen that can be used to test each cookbook in the application
- Supports a single Policyfile.rb, which is an upcoming feature of the Chef development kit that defines a workflow around a set of cookbooks and related policy (such as roles, environments, and so on); for more information about Policyfile.rb, see the chef.lists discussions (search for “policyfile”)
Note
Cookbook and custom resource names should contain only alphanumeric characters. A hyphen (-
) is a valid character and may be used in cookbook and custom resource names, but it is discouraged. The chef-client will return an error if a hyphen is not converted to an underscore (_
) when referencing from a recipe the name of a custom resource in which a hyphen is located.
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
Create an application
To generate an application, run a command similar to:
$ chef generate app chef-repo
will return something similar to:
Recipe: code_generator::app
* directory[/Users/grantmc/chef-repo] action create
- create new directory /Users/grantmc/chef-repo
* template[/Users/grantmc/chef-repo/.kitchen.yml] action create
- create new file /Users/grantmc/chef-repo/.kitchen.yml
* template[/Users/grantmc/chef-repo/README.md] action create
- create new file /Users/grantmc/chef-repo/README.md
* directory[/Users/grantmc/chef-repo/cookbooks] action create
- create new directory /Users/grantmc/chef-repo/cookbooks
* directory[/Users/grantmc/chef-repo/cookbooks/chef-repo] action create
- create new directory /Users/grantmc/chef-repo/cookbooks/chef-repo
* template[/Users/grantmc/chef-repo/cookbooks/chef-repo/metadata.rb] action create
- create new file /Users/grantmc/chef-repo/cookbooks/chef-repo/metadata.rb
* cookbook_file[/Users/grantmc/chef-repo/cookbooks/chef-repo/chefignore] action create
- create new file /Users/grantmc/chef-repo/cookbooks/chef-repo/chefignore
* cookbook_file[/Users/grantmc/chef-repo/cookbooks/chef-repo/Berksfile] action create
- create new file /Users/grantmc/chef-repo/cookbooks/chef-repo/Berksfile
* directory[/Users/grantmc/chef-repo/cookbooks/chef-repo/recipes] action create
- create new directory /Users/grantmc/chef-repo/cookbooks/chef-repo/recipes
* template[/Users/grantmc/chef-repo/cookbooks/chef-repo/recipes/default.rb] action create
- create new file /Users/grantmc/chef-repo/cookbooks/chef-repo/recipes/default.rb
* execute[initialize-git] action run
- execute git init .
* cookbook_file[/Users/grantmc/chef-repo/.gitignore] action create
- create new file /Users/grantmc/chef-repo/.gitignore
and which creates a directory structure similar to:
/chef-repo
/.git
.gitignore
.kitchen.yml
/cookbooks
/chef-repo
Berksfile
chefignore
metadata.rb
/recipes
default.rb
README.md
chef generate attribute¶
Use the chef generate attribute
subcommand to generate an attribute file in the /attributes
directory.
Syntax¶
This subcommand has the following syntax:
$ chef generate attribute COOKBOOK_PATH NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
Create an attribute
To generate an attribute, run a command similar to:
$ chef generate attribute /path/to/cookbook FOO
will return something similar to:
Recipe: code_generator::attribute
* directory[/Users/grantmc/chef-repo/cookbooks/chef-repo/attributes] action create
- create new directory /Users/grantmc/chef-repo/cookbooks/chef-repo/attributes
* template[/Users/grantmc/chef-repo/cookbooks/chef-repo/attributes/FOO.rb] action create
- create new file /Users/grantmc/chef-repo/cookbooks/chef-repo/attributes/FOO.rb
chef generate cookbook¶
Use the chef generate cookbook
subcommand to generate a cookbook.
Note
Cookbook and custom resource names should contain only alphanumeric characters. A hyphen (-
) is a valid character and may be used in cookbook and custom resource names, but it is discouraged. The chef-client will return an error if a hyphen is not converted to an underscore (_
) when referencing from a recipe the name of a custom resource in which a hyphen is located.
Syntax¶
This subcommand has the following syntax:
$ chef generate cookbook COOKBOOK_PATH/COOKBOOK_NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -b
,--berks
- Create a Berksfile in the cookbook. Default value: enabled. This is disabled if the
--policy
option is given. -C COPYRIGHT
,--copyright COPYRIGHT
- Specify the copyright holder for copyright notices in generated files. Default value:
The Authors
-d
,--delivery
- Generate a delivery config file and build cookbook inside the new cookbook. Default value: disabled. This option is disabled. It has no effect and exists only for compatibility with past releases
-m EMAIL
,--email EMAIL
- Specify the email address of the author. Default value:
you@example.com
. -a KEY=VALUE
,--generator-arg KEY=VALUE
- Sets a property named
KEY
to the givenVALUE
on the generator context object in the generator cookbook. This allows custom generator cookbooks to accept optional user input on the command line. -I LICENSE
,--license LICENSE
- Sets the license. Valid values are
all_rights
,apache2
,mit
,gplv2
, orgplv3
. Default value:all_rights
. -P
,--policy
- Create a Policyfile in the cookbook instead of a Berksfile. Default value: disabled.
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
Create a cookbook
To generate a cookbook, run a command similar to:
$ chef generate cookbook chefdocs
will return something similar to:
Recipe: code_generator::cookbook
* directory[/Users/grantmc/chefdocs] action create
- create new directory /Users/grantmc/chefdocs
* template[/Users/grantmc/chefdocs/metadata.rb] action create
- create new file /Users/grantmc/chefdocs/metadata.rb
* template[/Users/grantmc/chefdocs/README.md] action create
- create new file /Users/grantmc/chefdocs/README.md
* cookbook_file[/Users/grantmc/chefdocs/chefignore] action create
- create new file /Users/grantmc/chefdocs/chefignore
* cookbook_file[/Users/grantmc/chefdocs/Berksfile] action create
- create new file /Users/grantmc/chefdocs/Berksfile
* template[/Users/grantmc/chefdocs/.kitchen.yml] action create
- create new file /Users/grantmc/chefdocs/.kitchen.yml
* directory[/Users/grantmc/chefdocs/recipes] action create
- create new directory /Users/grantmc/chefdocs/recipes
* template[/Users/grantmc/chefdocs/recipes/default.rb] action create
- create new file /Users/grantmc/chefdocs/recipes/default.rb
* execute[initialize-git] action run
- execute git init .
* cookbook_file[/Users/grantmc/chefdocs/.gitignore] action create
- create new file /Users/grantmc/chefdocs/.gitignore
and which creates a directory structure similar to:
/chefdocs
/.git
.gitignore
.kitchen.yml
Berksfile
chefignore
metadata.rb
README.md
/recipes
default.rb
Create a cookbook using a custom skeleton cookbook
If a custom skeleton cookbook is located on a macOS desktop (and in this example, the chef_generator
cookbook is simply a copy of the same cookbook that ships in the Chef development kit), the following command will use the skeleton cookbook at the custom location to generate a cookbook into the repository from which the chef
command is run:
$ chef generate cookbook --generator-cookbook ~/Desktop testcookbook
Note
The code_generator
cookbook itself is not specified as part of the path.
will return something similar to:
Compiling Cookbooks...
Recipe: code_generator::cookbook
* directory[/Users/grantmc/Desktop/chef-repo/test-cookbook] action create
- create new directory /Users/grantmc/Desktop/chef-repo/test-cookbook
* template[/Users/grantmc/Desktop/chef-repo/test-cookbook/metadata.rb] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/metadata.rb
* template[/Users/grantmc/Desktop/chef-repo/test-cookbook/README.md] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/README.md
* cookbook_file[/Users/grantmc/Desktop/chef-repo/test-cookbook/chefignore] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/chefignore
* cookbook_file[/Users/grantmc/Desktop/chef-repo/test-cookbook/Berksfile] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/Berksfile
* template[/Users/grantmc/Desktop/chef-repo/test-cookbook/.kitchen.yml] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/.kitchen.yml
* directory[/Users/grantmc/Desktop/chef-repo/test-cookbook/recipes] action create
- create new directory /Users/grantmc/Desktop/chef-repo/test-cookbook/recipes
* template[/Users/grantmc/Desktop/chef-repo/test-cookbook/recipes/default.rb] action create
- create new file /Users/grantmc/Desktop/chef-repo/test-cookbook/recipes/default.rb
chef generate build-cookbook¶
Use the chef generate build-cookbook
subcommand to generate a delivery configuration file and build cookbook.
Syntax¶
This subcommand has the following syntax:
$ chef generate build-cookbook COOKBOOK_PATH/COOKBOOK_NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -C COPYRIGHT
,--copyright COPYRIGHT
- Specify the copyright holder for copyright notices in generated files. Default value:
The Authors
-m EMAIL
,--email EMAIL
- Specify the email address of the author. Default value:
you@example.com
. -a KEY=VALUE
,--generator-arg KEY=VALUE
- Sets a property named
KEY
to the givenVALUE
on the generator context object in the generator cookbook. This allows custom generator cookbooks to accept optional user input on the command line. -I LICENSE
,--license LICENSE
- Sets the license. Valid values are
all_rights
,apache2
,mit
,gplv2
, orgplv3
. Default value:all_rights
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef generate file¶
Use the chef generate file
subcommand to generate a file in the /files
directory.
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-s SOURCE_FILE
,--source SOURCE_FILE
- Copy the contents from a source file.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef generate resource¶
Use the chef generate resource
subcommand to generate a custom resource in the /resources
directory.
Note
Cookbook and custom resource names should contain only alphanumeric characters. A hyphen (-
) is a valid character and may be used in cookbook and custom resource names, but it is discouraged. The chef-client will return an error if a hyphen is not converted to an underscore (_
) when referencing from a recipe the name of a custom resource in which a hyphen is located.
Syntax¶
This subcommand has the following syntax:
$ chef generate resource COOKBOOK_PATH NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef generate recipe¶
Use the chef generate recipe
subcommand to generate a recipe in the /recipes
directory.
Syntax¶
This subcommand has the following syntax:
$ chef generate recipe COOKBOOK_PATH NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
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.
Options¶
This subcommand has the following options:
-h
,--help
- Show help for the command.
-p
,--policy-only
- Create a repository that does not store cookbook files, only Policyfile files.
-P
,--policy
- Use Policyfile instead of Berkshelf.
-r
,--roles
- Create directories for
/roles
and/environments
instead of creating directories for Policyfile. -v
,--version
- The version of the chef-client.
Examples¶
None.
chef generate template¶
Use the chef generate template
subcommand to generate a template in the /templates
directory.
Syntax¶
This subcommand has the following syntax:
$ chef generate template COOKBOOK_PATH NAME (options)
Options¶
This subcommand has the following options:
-g GENERATOR_COOKBOOK_PATH
,--generator-cookbook GENERATOR_COOKBOOK_PATH
- The path at which a cookbook named
code_generator
is located. This cookbook is used by thechef generate
subcommands to generate cookbooks, cookbook files, templates, attribute files, and so on. Default value:lib/chef-dk/skeletons
, under which is the defaultcode_generator
cookbook that is included as part of the Chef development kit. -h
,--help
- Show help for the command.
-s SOURCE_FILE
,--source SOURCE_FILE
- Copy the contents from a source file.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef provision¶
Use the chef provision
subcommand to invoke an embedded chef-client run to provision machines using Chef provisioning. By default, this subcommand expects to find a cookbook named provision
in the current working directory. The chef-client run will run a recipe in this cookbook that uses Chef provisioning to create one (or more) machines.
The chef provision
subcommand is intended to:
- Provide a provisioning mechanism that supports using
Policyfile.rb
files - Support naming conventions within Chef provisioning
- Integrate Chef provisioning steps with the command-line tools that are packaged with the Chef development kit
- Separate the configuration of provisioned machines from running Chef provisioning
- Allow provisioning to be managed as code and versioned (via
Policyfile.rb
files), as opposed to the legacyknife bootstrap
behavior, which is primarily driven by command-line options
Syntax¶
This subcommand has the following syntax:
To create machines that operate using only a local Policyfile.rb
:
$ chef provision POLICY_GROUP --policy-name POLICY_NAME (options)
To create machines that operate using a Policyfile.rb
that is synchronized with the Chef server before each chef-client run:
$ chef provision POLICY_GROUP --sync PATH (options)
To create machines that will not use a Policyfile.rb
file:
$ chef provision --no-policy (options)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
--cookbook COOKBOOK_PATH
- Specify the location of the cookbook that is used to provision the node. Default value:
./provision
. -d
,--destroy
- Set the default action for the machine resource to
:destroy
. Default value:false
. -D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-n NODE_NAME
,--node-name NODE_NAME
- Specify the name of the node. (This value may be overridden by the cookbook that is used to provision the node.)
-o OPT=VALUE
,--opt OPT=VALUE
Set an arbitrary command-line option (
OPT
) and value (=VALUE
). Use this option once per command-line option. Default value:{}
.Note
Use the
extra_chef_config
property in a recipe in theprovision
cookbook to set arbitrary configuration settings. Define theextra_chef_config
values in theprovision
cookbook using the following syntax:ChefDK::ProvisioningData.context.extra_chef_config = 'setting :value'
For example:
ChefDK::ProvisioningData.context.extra_chef_config = 'log_level :debug'
-p POLICY_NAME
,--policy-name POLICY_NAME
- Set the policy name for one (or more) machines that are managed by this
Policyfile.rb
file. --[no-]policy
- Use
--policy
to enable one (or more) machines to be managed by aPolicyfile.rb
file. Default value:--policy
. -r RECIPE
,--recipe RECIPE
- Specify the name of the recipe to be run. This recipe must be located in the
policyfile
cookbook at the path specified by the--cookbook
option. -s PATH
,--sync PATH
- Push a
Policyfile.rb
file to the Chef server before running the chef-client on a node. ThePATH
is the location of thePolicyfile.rb
file to be synchronized. -t REMOTE_HOST
,--target REMOTE_HOST
- Set the hostname or IP address of the host on which the chef-client run will occur. (This value may be overridden by the cookbook that is used to provision the node.)
-v
,--version
- The version of the chef-client.
Examples¶
Create a machine with lock file, synchronized to the Chef server
with_driver 'vagrant:~/.vagrant.d/boxes' do
# Set machine options
options = {
vagrant_options: { 'vm.box' => 'opscode-ubuntu-14.04' },
# Set all machine options to default values
convergence_options: ChefDK::ProvisioningData.context.convergence_options
}
# Set node name to --node-name
machine context.node_name do
machine_options(options)
# Force a Chef run every time and set action to --destroy option
action(ChefDK::ProvisioningData.context.action)
end
end
and then to provision the machine, run the following:
$ chef provision test123 --sync -n aar-dev
This will synchronize the Policyfile.lock.json
file to the Chef server, and then run the Chef client on the node.
Recipe: code_generator::cookbook
* directory[/Users/grantmc/chefdocs] action create
- create new directory /Users/grantmc/chefdocs
* template[/Users/grantmc/chefdocs/metadata.rb] action create
- create new file /Users/grantmc/chefdocs/metadata.rb
* template[/Users/grantmc/chefdocs/README.md] action create
- create new file /Users/grantmc/chefdocs/README.md
* cookbook_file[/Users/grantmc/chefdocs/chefignore] action create
- create new file /Users/grantmc/chefdocs/chefignore
* cookbook_file[/Users/grantmc/chefdocs/Berksfile] action create
- create new file /Users/grantmc/chefdocs/Berksfile
* template[/Users/grantmc/chefdocs/.kitchen.yml] action create
- create new file /Users/grantmc/chefdocs/.kitchen.yml
* directory[/Users/grantmc/chefdocs/recipes] action create
- create new directory /Users/grantmc/chefdocs/recipes
* template[/Users/grantmc/chefdocs/recipes/default.rb] action create
- create new file /Users/grantmc/chefdocs/recipes/default.rb
* execute[initialize-git] action run
- execute git init .
* cookbook_file[/Users/grantmc/chefdocs/.gitignore] action create
- create new file /Users/grantmc/chefdocs/.gitignore
and which creates a directory structure similar to:
/chefdocs
/.git
.gitignore
.kitchen.yml
Berksfile
chefignore
metadata.rb
README.md
/recipes
default.rb
Pass arbitrary options
Use the --opt
option to pass arbitrary command-line options. For example:
$ chef provision (other options) --opt foo=bar
Use the --opt
option more than once to pass more than one option. For example:
$ chef provision (other options) --opt foo=bar --opt baz=qux
chef shell-init¶
Use the chef shell-init
subcommand to set the Ruby included in the Chef development kit as the system Ruby. The Chef development kit is designed to allow the isolation of applications used by the Chef development kit from other Ruby development tools that may be present on the workstation. This supports Bash, fish, Windows PowerShell (posh), and zsh.
bash zsh fish PowerShell (posh)
Options¶
This subcommand has the following options:
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
Set PowerShell
You can use the chef shell-init
command with Windows PowerShell to add the appropriate variables to your environment.
To try it in your current session:
chef shell-init powershell | Invoke-Expression
To enable it permanently:
"chef shell-init powershell | Invoke-Expression" >> $PROFILE
Set the execution policy on new machines
On new Windows machines, PowerShell scripts will not work until an administrator runs the following command:
Set-ExecutionPolicy RemoteSigned
Create a $PROFILE on new machines
On new Windows machines, commands cannot be appended to $PROFILE
if the folder does not exist, or if there is a new user profile. This will result in an error similar to the following:
PS C:\Users\Stuart> "chef shell-init powershell | Invoke-Expression" >> $PROFILE
out-file : Could not find a part of the path
'C:\Users\Stuart\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1'.
At line:1 char:1
+ "chef shell-init powershell | Invoke-Expression" >> $PROFILE
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OpenError: (:) [Out-File], DirectoryNotFoundException
+ FullyQualifiedErrorId : FileOpenFailure,Microsoft.PowerShell.Commands.OutFileCommand
In this situation, run the following chef shell-init
command instead:
if(Test-Path $PROFILE){ chef shell-init powershell | Add-Content $PROFILE } else { New-Item -Force -ItemType File $PROFILE; chef shell-init powershell | Add-Content $PROFILE }
Policyfile 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 server.
Note
Cookbooks that are referenced by orphaned policy revisions are not removed. Use chef clean-policy-revisions
to remove orphaned policies.
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef clean-policy-revisions¶
Use the chef clean-policy-revisions
subcommand to delete orphaned policy revisions to Policyfile files from the Chef 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.
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef delete-policy¶
Use the chef delete-policy
subcommand to delete all revisions of the named policy that exist on the Chef server. (The state of the policy revision is backed up locally and may be restored using the chef undelete
subcommand.)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef delete-policy-group¶
Use the chef delete-policy-group
subcommand to delete the named policy group from the Chef 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.)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef diff¶
Use the chef diff
subcommand to display an itemized comparison of two revisions of a Policyfile.lock.json
file.
Syntax¶
This subcommand has the following syntax:
$ chef diff POLICY_FILE --head | --git POLICY_GROUP | POLICY_GROUP...POLICY_GROUP (options)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -g GIT_REF
,--git GIT_REF
- Compare the specified git reference against the current revision of a
Policyfile.lock.json
file or against another git reference. -h
,--help
- Show help for the command.
--head
- A shortcut for
chef diff --git HEAD
. When a git-specific flag is not provided, the on-diskPolicyfile.lock.json
file is compared to one on the Chef server or (if aPolicyfile.lock.json
file is not present on-disk) twoPolicyfile.lock.json
files in the specified policy group on the Chef server are compared. --[no-]pager
- Use
--pager
to enable paged output for aPolicyfile.lock.json
file. Default value:--pager
. -v
,--version
- The version of the chef-client.
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 groups
$ 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).
Configuration Settings¶
The client.rb file on that machine requires the following settings:
deployment_group
- This setting should be set to
'$POLICY_NAME-local'
. policy_document_native_api
- This setting should be set to
false
. use_policyfile
- This setting should be set to
true
. versioned_cookbooks
- This setting should be set to
true
.
Options¶
This subcommand has the following options:
-a
,--archive
- Export an archive as a tarball, instead as a directory. Default value:
false
. -D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -f
,--force
- Remove the contents of the destination directory if that directory is not empty. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef generate policyfile¶
Use the chef generate policyfile
subcommand to generate a file to be used with Policyfile.
Options¶
This subcommand has the following options:
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef install¶
Use the chef install
subcommand to evaluate a policy file 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 server to apply that policy to a group of nodes that are under management by Chef.
Options¶
This subcommand has the following options:
-D
,--debug
- Enable stack traces and other debug output.
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Policyfile.lock.json¶
When the chef install
command is run, the Chef development kit 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, i.e. 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"
}
Examples¶
None.
chef provision¶
Use the chef provision
subcommand to invoke an embedded chef-client run to provision machines using Chef provisioning. By default, this subcommand expects to find a cookbook named provision
in the current working directory. The chef-client run will run a recipe in this cookbook that uses Chef provisioning to create one (or more) machines.
The chef provision
subcommand is intended to:
- Provide a provisioning mechanism that supports using
Policyfile.rb
files - Support naming conventions within Chef provisioning
- Integrate Chef provisioning steps with the command-line tools that are packaged with the Chef development kit
- Separate the configuration of provisioned machines from running Chef provisioning
- Allow provisioning to be managed as code and versioned (via
Policyfile.rb
files), as opposed to the legacyknife bootstrap
behavior, which is primarily driven by command-line options
Syntax¶
This subcommand has the following syntax:
To create machines that operate using only a local Policyfile.rb
:
$ chef provision POLICY_GROUP --policy-name POLICY_NAME (options)
To create machines that operate using a Policyfile.rb
that is synchronized with the Chef server before each chef-client run:
$ chef provision POLICY_GROUP --sync PATH (options)
To create machines that will not use a Policyfile.rb
file:
$ chef provision --no-policy (options)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
--cookbook COOKBOOK_PATH
- Specify the location of the cookbook that is used to provision the node. Default value:
./provision
. -d
,--destroy
- Set the default action for the machine resource to
:destroy
. Default value:false
. -D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-n NODE_NAME
,--node-name NODE_NAME
- Specify the name of the node. (This value may be overridden by the cookbook that is used to provision the node.)
-o OPT=VALUE
,--opt OPT=VALUE
Set an arbitrary command-line option (
OPT
) and value (=VALUE
). Use this option once per command-line option. Default value:{}
.Note
Use the
extra_chef_config
property in a recipe in theprovision
cookbook to set arbitrary configuration settings. Define theextra_chef_config
values in theprovision
cookbook using the following syntax:ChefDK::ProvisioningData.context.extra_chef_config = 'setting :value'
For example:
ChefDK::ProvisioningData.context.extra_chef_config = 'log_level :debug'
-p POLICY_NAME
,--policy-name POLICY_NAME
- Set the policy name for one (or more) machines that are managed by this
Policyfile.rb
file. --[no-]policy
- Use
--policy
to enable one (or more) machines to be managed by aPolicyfile.rb
file. Default value:--policy
. -r RECIPE
,--recipe RECIPE
- Specify the name of the recipe to be run. This recipe must be located in the
policyfile
cookbook at the path specified by the--cookbook
option. -s PATH
,--sync PATH
- Push a
Policyfile.rb
file to the Chef server before running the chef-client on a node. ThePATH
is the location of thePolicyfile.rb
file to be synchronized. -t REMOTE_HOST
,--target REMOTE_HOST
- Set the hostname or IP address of the host on which the chef-client run will occur. (This value may be overridden by the cookbook that is used to provision the node.)
-v
,--version
- The version of the chef-client.
Examples¶
Create a machine with lock file, synchronized to the Chef server
with_driver 'vagrant:~/.vagrant.d/boxes' do
# Set machine options
options = {
vagrant_options: { 'vm.box' => 'opscode-ubuntu-14.04' },
# Set all machine options to default values
convergence_options: ChefDK::ProvisioningData.context.convergence_options
}
# Set node name to --node-name
machine context.node_name do
machine_options(options)
# Force a Chef run every time and set action to --destroy option
action(ChefDK::ProvisioningData.context.action)
end
end
and then to provision the machine, run the following:
$ chef provision test123 --sync -n aar-dev
This will synchronize the Policyfile.lock.json
file to the Chef server, and then run the Chef client on the node.
Recipe: code_generator::cookbook
* directory[/Users/grantmc/chefdocs] action create
- create new directory /Users/grantmc/chefdocs
* template[/Users/grantmc/chefdocs/metadata.rb] action create
- create new file /Users/grantmc/chefdocs/metadata.rb
* template[/Users/grantmc/chefdocs/README.md] action create
- create new file /Users/grantmc/chefdocs/README.md
* cookbook_file[/Users/grantmc/chefdocs/chefignore] action create
- create new file /Users/grantmc/chefdocs/chefignore
* cookbook_file[/Users/grantmc/chefdocs/Berksfile] action create
- create new file /Users/grantmc/chefdocs/Berksfile
* template[/Users/grantmc/chefdocs/.kitchen.yml] action create
- create new file /Users/grantmc/chefdocs/.kitchen.yml
* directory[/Users/grantmc/chefdocs/recipes] action create
- create new directory /Users/grantmc/chefdocs/recipes
* template[/Users/grantmc/chefdocs/recipes/default.rb] action create
- create new file /Users/grantmc/chefdocs/recipes/default.rb
* execute[initialize-git] action run
- execute git init .
* cookbook_file[/Users/grantmc/chefdocs/.gitignore] action create
- create new file /Users/grantmc/chefdocs/.gitignore
and which creates a directory structure similar to:
/chefdocs
/.git
.gitignore
.kitchen.yml
Berksfile
chefignore
metadata.rb
README.md
/recipes
default.rb
Pass arbitrary options
Use the --opt
option to pass arbitrary command-line options. For example:
$ chef provision (other options) --opt foo=bar
Use the --opt
option more than once to pass more than one option. For example:
$ chef provision (other options) --opt foo=bar --opt baz=qux
chef push¶
Use the chef push
subcommand to upload an existing Policyfile.lock.json
file to the Chef 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.
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output.
-h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef push-archive¶
The chef push-archive
subcommand is used to publish a policy archive file to the Chef 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.
Syntax¶
This subcommand has the following syntax:
$ chef push-archive POLICY_GROUP ARCHIVE_FILE (options)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.
chef show-policy¶
Use the chef show-policy
subcommand to display revisions for every Policyfile.rb
file that is on the Chef 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.
Syntax¶
This subcommand has the following syntax:
$ chef show-policy POLICY_NAME POLICY_GROUP (options)
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-o
,--orphans
- Show policy revisions that are not currently assigned to any policy group.
--[no-]pager
- Use
--pager
to enable paged output for aPolicyfile.lock.json
file. Default value:--pager
. -v
,--version
- The version of the chef-client.
Examples¶
None.
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 policy files; cookbooks that are cleaned after running this command may not be fully restorable to their previous state
- Does not store access control data
Syntax¶
This subcommand has the following syntax:
$ chef undelete (options)
When run with no arguments, returns a list of available operations.
Options¶
This subcommand has the following options:
-c CONFIG_FILE
,--config CONFIG_FILE
- The path to the knife configuration file.
-D
,--debug
- Enable stack traces and other debug output.
-h
,--help
- Show help for the command.
-i ID
,--id ID
- Undo the delete operation specified by
ID
. -l
,--last
- Undo the most recent delete operation.
--list
- Default. Return a list of available operations.
-v
,--version
- The version of the chef-client.
Examples¶
None.
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.
Options¶
This subcommand has the following options:
-a
,--attributes
- Update attributes. Default value:
false
. -D
,--debug
- Enable stack traces and other debug output. Default value:
false
. -h
,--help
- Show help for the command.
-v
,--version
- The version of the chef-client.
Examples¶
None.