chef_client_config Resource
This page is generated from the Chef Infra Client source code.To suggest a change, edit the chef_client_config.rb file and submit a pull request to the Chef Infra Client repository.
Use the chef_client_config resource to create a client.rb file in the Chef Infra Client configuration directory. See the client.rb docs for more details on options available in the client.rb configuration file.
New in Chef Infra Client 16.6.
Syntax
The full syntax for all of the properties that are available to the chef_client_config resource is:
chef_client_config 'name' do
additional_config String
chef_license String
chef_server_url String
config_directory String
data_collector_server_url String
data_collector_token String
event_loggers Array # default value: []
exception_handlers Array # default value: []
file_backup_path String
file_cache_path String
file_staging_uses_destdir String
formatters Array # default value: []
ftp_proxy String
group String
http_proxy String
https_proxy String
log_level Symbol
log_location String, Symbol
minimal_ohai true, false
named_run_list String
no_proxy String, Array # default value: []
node_name String
ohai_disabled_plugins Array # default value: []
ohai_optional_plugins Array # default value: []
pid_file String
policy_group String
policy_name String
policy_persist_run_list true, false
report_handlers Array # default value: []
rubygems_url String, Array
ssl_verify_mode Symbol, String
start_handlers Array # default value: []
user String
action Symbol # defaults to :create if not specified
end
where:
chef_client_config
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.additional_config
,chef_license
,chef_server_url
,config_directory
,data_collector_server_url
,data_collector_token
,event_loggers
,exception_handlers
,file_backup_path
,file_cache_path
,file_staging_uses_destdir
,formatters
,ftp_proxy
,group
,http_proxy
,https_proxy
,log_level
,log_location
,minimal_ohai
,named_run_list
,no_proxy
,node_name
,ohai_disabled_plugins
,ohai_optional_plugins
,pid_file
,policy_group
,policy_name
,policy_persist_run_list
,report_handlers
,rubygems_url
,ssl_verify_mode
,start_handlers
, anduser
are the properties available to this resource.
Actions
The chef_client_config resource has the following actions:
:create
- Create a client.rb config file and folders for configuring Chef Infra Client. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a client.rb config file for configuring Chef Infra Client.
Properties
The chef_client_config resource has the following properties:
additional_config
- Ruby Type: String
Additional text to add at the bottom of the client.rb config. This can be used to run custom Ruby or to add less common config options
chef_license
- Ruby Type: StringAllowed Values:
"accept", "accept-no-persist", "accept-silent"
Accept the Chef EULA
chef_server_url
- Ruby Type: String |
REQUIRED
The URL for the Chef Infra Server.
config_directory
- Ruby Type: String | Default Value:
`/etc/chef/` on *nix-like systems and `C:\chef\` on Windows
The directory to store the client.rb in.
data_collector_server_url
- Ruby Type: String
The data collector URL (typically automate) to send node, converge, and compliance data.
Note
If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.
New in Chef Infra Client 17.8
data_collector_token
- Ruby Type: String
The data collector token to interact with the data collector server URL (Automate).
Note
If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.
New in Chef Infra Client 17.8
event_loggers
- Ruby Type: Array | Default Value:
[]
exception_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a exception handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
file_backup_path
- Ruby Type: String
The location in which backup files are stored. If this value is empty, backup files are stored in the directory of the target file
file_cache_path
- Ruby Type: String
The location in which cookbooks (and other transient data) files are stored when they are synchronized. This value can also be used in recipes to download files with the
remote_file
resource.
file_staging_uses_destdir
- Ruby Type: String
How file staging (via temporary files) is done. When
true
, temporary files are created in the directory in which files will reside. Whenfalse
, temporary files are created underENV['TMP']
formatters
- Ruby Type: Array | Default Value:
[]
Client logging formatters to load.
ftp_proxy
- Ruby Type: String
The proxy server to use for FTP connections.
group
- Ruby Type: String
The group that should own the client.rb file and the configuration directory if it needs to be created.
Note
The configuration directory will not be created if it already exists, which allows you to further control the setup of that directory outside of this resource.
http_proxy
- Ruby Type: String
The proxy server to use for HTTP connections.
https_proxy
- Ruby Type: String
The proxy server to use for HTTPS connections.
log_level
- Ruby Type: SymbolAllowed Values:
:auto, :debug, :fatal, :info, :trace, :warn
The level of logging performed by the Chef Infra Client.
log_location
- Ruby Type: String, Symbol
The location to save logs to. This can either by a path to a log file on disk
:syslog
to log to Syslog,:win_evt
to log to the Windows Event Log, or'STDERR'
/'STDOUT'
to log to the *nix text streams.
minimal_ohai
- Ruby Type: true, false
Run a minimal set of Ohai plugins providing data necessary for the execution of Chef Infra Client’s built-in resources. Setting this to true will skip many large and time consuming data sets such as
cloud
orpackages
. Setting this this to true may break cookbooks that assume all Ohai data will be present.
named_run_list
- Ruby Type: String
A specific named runlist defined in the node’s applied Policyfile, which the should be used when running Chef Infra Client.
no_proxy
- Ruby Type: String, Array | Default Value:
[]
A comma-separated list or an array of URLs that do not need a proxy.
node_name
- Ruby Type: String | Default Value:
The `node.name` value reported by Chef Infra Client.
The name of the node. This configuration sets the
node.name
value used in cookbooks and theclient_name
value used when authenticating to a Chef Infra Server to determine what configuration to apply.Note
By default this configuration uses the
node.name
value which would be set during bootstrap. Hard coding this value in theclient.rb
config avoids logic within Chef Infra Server that performs DNS lookups and may fail in the event of a DNS outage. To skip this default value and instead use the built-in Chef Infra Server logic, set this property tonil
ohai_disabled_plugins
- Ruby Type: Array | Default Value:
[]
Ohai plugins that should be disabled in order to speed up the Chef Infra Client run and reduce the size of node data sent to Chef Infra Client
ohai_optional_plugins
- Ruby Type: Array | Default Value:
[]
Optional Ohai plugins that should be enabled to provide additional Ohai data for use in cookbooks.
pid_file
- Ruby Type: String
The location in which a process identification number (pid) is saved. An executable, when started as a daemon, writes the pid to the specified file.
policy_group
- Ruby Type: String
The name of a
policy group
that exists on the Chef Infra Server.policy_name
must also be specified when setting this property.
policy_name
- Ruby Type: String
The name of a policy, as identified by the
name
setting in a Policyfile.rb file.policy_group
when setting this property.
policy_persist_run_list
- Ruby Type: true, false
Override run lists defined in a Policyfile with the
run_list
defined on the Chef Infra Server.New in Chef Infra Client 17.3
report_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a report handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
rubygems_url
- Ruby Type: String, Array
The location to source rubygems. It can be set to a string or array of strings for URIs to set as rubygems sources. This allows individuals to set up an internal mirror of rubygems for airgapped environments.
New in Chef Infra Client 17.11
ssl_verify_mode
- Ruby Type: Symbol, StringAllowed Values:
:verify_none, :verify_peer
Set the verify mode for HTTPS requests.
- Use :verify_none for no validation of SSL certificates.
- Use :verify_peer for validation of all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS remote_file resource URLs used in Chef Infra Client runs. This is the recommended setting.
start_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a report handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
user
- Ruby Type: String
The user that should own the client.rb file and the configuration directory if it needs to be created.
Note
The configuration directory will not be created if it already exists, which allows you to further control the setup of that directory outside of this resource.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_config resource in recipes:
Bare minimum Chef Infra Client client.rb:
The absolute minimum configuration necessary for a node to communicate with the Chef Infra Server is the URL of the Chef Infra Server. All other configuration options either have values at the server side (Policyfiles, Roles, Environments, etc) or have default values determined at client startup.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
end
More complex Chef Infra Client client.rb:
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
log_level :info
log_location :syslog
http_proxy 'proxy.example.dmz'
https_proxy 'proxy.example.dmz'
no_proxy %w(internal.example.dmz)
end
Adding additional config content to the client.rb:
This resource aims to provide common configuration options. Some configuration options are missing and some users may want to use arbitrary Ruby code within their configuration. For this we offer an additional_config
property that can be used to add any configuration or code to the bottom of the client.rb
file. Also keep in mind that within the configuration directory is a client.d
directory where you can put additional .rb
files containing configuration options. These can be created using file
or template
resources within your cookbooks as necessary.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
additional_config <<~CONFIG
# Extra config code to safely load a gem into the client run.
# Since the config is Ruby you can run any Ruby code you want via the client.rb.
# It's a great way to break things, so be careful
begin
require 'aws-sdk'
rescue LoadError
Chef::Log.warn "Failed to load aws-sdk."
end
CONFIG
end
Setup two report handlers in the client.rb:
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
report_handlers [
{
'class' => 'ReportHandler1Class',
'arguments' => ["'FirstArgument'", "'SecondArgument'"],
},
{
'class' => 'ReportHandler2Class',
'arguments' => ["'FirstArgument'", "'SecondArgument'"],
},
]
end
Report directly to the Chef Automate data collector endpoint.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
data_collector_server_url 'https://automate.example.dmz'
data_collector_token 'TEST_TOKEN_TEST'
end