chef-solo is an open source version of the chef-client that allows using cookbooks with nodes without requiring access to a Chef server. chef-solo uses Chef local mode, and does not support the following:
Note
chef-solo can be run as a daemon.
chef-solo supports two locations from which cookbooks can be run:
Using a tar.gz archive is the more common approach, but requires that cookbooks be added to an archive. For example:
$ tar zcvf chef-solo.tar.gz ./cookbooks
If multiple cookbook directories are being used, chef-solo expects the tar.gz archive to have a directory structure similar to the following:
cookbooks/ |---- cbname1/ |--attributes/ ... etc ... |---- cbname2/ |--attributes/
The cookbook_path
variable in the solo.rb file must include both directories. For example:
$ tar zcvf chef-solo.tar.gz ./cookbooks ./site-cookbooks
When the tar.gz archive contains all of the cookbooks required by chef-solo, upload it to the web server from which chef-solo will access the archive.
Unlike chef-client, where the node object is stored on the Chef server, chef-solo stores its node objects as JSON files on disk. By default, chef-solo stores these files in a nodes
folder in the same directory as your cookbooks
directory. You can control the location of this directory via the node_path
value in your configuration file.
chef-solo does not interact with the Chef server. Consequently, node-specific attributes must be located in a JSON file on the target system, a remote location (such as Amazon Simple Storage Service (S3)), or a web server on the local network.
The JSON file must also specify the recipes that are part of the run-list. For example:
{ "resolver": { "nameservers": [ "10.0.0.1" ], "search":"int.example.com" }, "run_list": [ "recipe[resolver]" ] }
A data bag is defined using JSON. chef-solo will look for data bags in /var/chef/data_bags
, but this location can be modified by changing the setting in solo.rb. For example, the following setting in solo.rb:
data_bag_path '/var/chef-solo/data_bags'
Create a data bag by creating folders. For example:
mkdir /var/chef-solo/data_bags
and:
mkdir /var/chef-solo/data_bags/admins
and then create a JSON file in that location:
{ "id": "ITEM_NAME" }
where the name of the file is the ITEM_NAME
, for example:
/var/chef-solo/data_bags/admins/ITEM_NAME.json
A role is defined using JSON or the Ruby DSL. chef-solo will look for roles in /var/chef/roles
, but this location can be modified by changing the setting for role_path
in solo.rb. For example, the following setting in solo.rb:
role_path '/var/chef-solo/roles'
Role data looks like the following in JSON:
{ "name": "test", "default_attributes": { }, "override_attributes": { }, "json_class": "Chef::Role", "description": "This is just a test role, no big deal.", "chef_type": "role", "run_list": [ "recipe[test]" ] }
and like the following in the Ruby DSL:
name 'test' description 'This is just a test role, no big deal.' run_list 'recipe[test]'
and finally, JSON data passed to chef-solo:
{ 'run_list': 'role[test]' }
An environment is defined using JSON or the Ruby DSL. chef-solo will look for environments in /var/chef/environments
, but this location can be modified by changing the setting for environment_path
in solo.rb. For example, the following setting in solo.rb:
environment_path '/var/chef-solo/environments'
Environment data looks like the following in JSON:
{ "name": "dev", "default_attributes": { "apache2": { "listen_ports": [ "80", "443" ] } }, "json_class": "Chef::Environment", "description": "", "cookbook_versions": { "couchdb": "= 11.0.0" }, "chef_type": "environment" }
and like the following in the Ruby DSL:
name 'environment_name' description 'environment_description' cookbook OR cookbook_versions 'cookbook' OR 'cookbook' => 'cookbook_version' default_attributes 'node' => { 'attribute' => [ 'value', 'value', 'etc.' ] } override_attributes 'node' => { 'attribute' => [ 'value', 'value', 'etc.' ] }
The chef-solo executable is run as a command-line tool.
This command has the following syntax:
chef-solo OPTION VALUE OPTION VALUE ...
This command has the following options:
-c CONFIG
, --config CONFIG
-d
, --daemonize
Run the executable as a daemon. This option may not be used in the same command with the --[no-]fork
option.
This option is only available on machines that run in UNIX or Linux environments. For machines that are running Microsoft Windows that require similar functionality, use the chef-client::service
recipe in the chef-client
cookbook: https://supermarket.chef.io/cookbooks/chef-client. This will install a chef-client service under Microsoft Windows using the Windows Service Wrapper.
-E ENVIRONMENT_NAME
, --environment ENVIRONMENT_NAME
-f
, --[no-]fork
--no-fork
to disable running the chef-client in fork node. Default value: --fork
. This option may not be used in the same command with the --daemonize
and --interval
options.-F FORMAT
, --format FORMAT
The output format: doc
(default) or min
.
doc
to print the progress of the chef-client run using full strings that display a summary of updates as they occur.min
to print the progress of the chef-client run using single characters.A summary of updates is printed at the end of the chef-client run. A dot (.
) is printed for events that do not have meaningful status information, such as loading a file or synchronizing a cookbook. For resources, a dot (.
) is printed when the resource is up to date, an S
is printed when the resource is skipped by not_if
or only_if
, and a U
is printed when the resource is updated.
Other formatting options are available when those formatters are configured in the client.rb file using the add_formatter
option.
--force-formatter
--force-logger
-g GROUP
, --group GROUP
-h
, --help
-i SECONDS
, --interval SECONDS
--splay
and --interval
values are applied before the chef-client run. This option may not be used in the same command with the --[no-]fork
option.-j PATH
, --json-attributes PATH
The path to a file that contains JSON data.
Use this option to define a run_list
object. For example, a JSON file similar to:
"run_list": [ "recipe[base]", "recipe[foo]", "recipe[bar]", "role[webserver]" ],
may be used by running chef-client -j path/to/file.json
.
In certain situations this option may be used to update normal
attributes.
Warning
Any other attribute type that is contained in this JSON file will be treated as a normal
attribute. For example, attempting to update override
attributes using the -j
option:
{ "name": "dev-99", "description": "Install some stuff", "override_attributes": { "apptastic": { "enable_apptastic": "false", "apptastic_tier_name": "dev-99.bomb.com" } } }
will result in a node object similar to:
{ "name": "maybe-dev-99", "normal": { "name": "dev-99", "description": "Install some stuff", "override_attributes": { "apptastic": { "enable_apptastic": "false", "apptastic_tier_name": "dev-99.bomb.com" } } } }
-l LEVEL
, --log_level LEVEL
-L LOGLOCATION
, --logfile c
--legacy-mode
--minimal-ohai
true
during integration testing to speed up test cycles.--[no-]color
--color
.-N NODE_NAME
, --node-name NODE_NAME
-o RUN_LIST_ITEM
, --override-runlist RUN_LIST_ITEM
-r RECIPE_URL
, --recipe-url RECIPE_URL
--run-lock-timeout SECONDS
0
to cause a second chef-client to exit immediately.-s SECONDS
, --splay SECONDS
splay
that is added to interval
. Use splay to help balance the load on the Chef server by ensuring that many chef-client runs are not occuring at the same interval. When the chef-client is run at intervals, --splay
and --interval
values are applied before the chef-client run.-u USER
, --user USER
-v
, --version
-W
, --why-run
Run chef-solo using solo.rb settings
$ chef-solo -c ~/chef/solo.rb
Use a URL
$ chef-solo -c ~/solo.rb -j ~/node.json -r http://www.example.com/chef-solo.tar.gz
The tar.gz is archived into the file_cache_path
, and then extracted to cookbooks_path
.
Use a directory
$ chef-solo -c ~/solo.rb -j ~/node.json
chef-solo will look in the solo.rb file to determine the directory in which cookbooks are located.
Use a URL for cookbook and JSON data
$ chef-solo -c ~/solo.rb -j http://www.example.com/node.json -r http://www.example.com/chef-solo.tar.gz
where -r
corresponds to recipe_url
and -j
corresponds to json_attribs
, both of which are configuration options in solo.rb.
© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs-archive.chef.io/release/12-13/chef_solo.html