template Resource
This page is generated from the Chef Infra Client source code.To suggest a change, edit the template.rb file and submit a pull request to the Chef Infra Client repository.
A cookbook template is an Embedded Ruby (ERB) template that is used to dynamically generate static text files. Templates may contain Ruby expressions and statements, and are a great way to manage configuration files. Use the template resource to add cookbook templates to recipes; place the corresponding Embedded Ruby (ERB) template file in a cookbook’s /templates
directory.
Use the template resource to manage the contents of a file using an Embedded Ruby (ERB) template by transferring files from a sub-directory of COOKBOOK_NAME/templates/
to a specified path located on a host that is running Chef Infra Client. This resource includes actions and properties from the file resource. Template files managed by the template resource follow the same file specificity rules as the remote_file and file resources.
Syntax
A template resource block typically declares the location in which a file is to be created, the source template that will be used to create the file, and the permissions needed on that file. For example:
template '/etc/motd' do
source 'motd.erb'
owner 'root'
group 'root'
mode '0755'
end
where:
'/etc/motd'
specifies the location in which the file is created'motd.erb'
specifies the name of a template that exists in in the/templates
folder of a cookbookowner
,group
, andmode
define the permissions
The full syntax for all of the properties that are available to the template resource is:
template 'name' do
atomic_update true, false
backup false, Integer
cookbook String
force_unlink true, false
group String, Integer
helper(:method) Method { String } # see Helpers below
helpers(module) Module # see Helpers below
inherits true, false
local true, false
manage_symlink_source true, false
mode String, Integer
owner String, Integer
path String # defaults to 'name' if not specified
rights Hash
sensitive true, false
source String, Array
variables Hash
verify String, Block
action Symbol # defaults to :create if not specified
end
where:
template
is the resourcename
is the name of the resource block, typically the path to the location in which a file is created and also the name of the file to be managed. For example:/var/www/html/index.html
, where/var/www/html/
is the fully qualified path to the location andindex.html
is the name of the filesource
is the template file that will be used to create the file on the node, for example:index.html.erb
; the template file is located in the/templates
directory of a cookbookaction
identifies the steps Chef Infra Client will take to bring the node into the desired stateatomic_update
,backup
,cookbook
,force_unlink
,group
,helper
,helpers
,inherits
,local
,manage_symlink_source
,mode
,owner
,path
,rights
,source
,variables
, andverify
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Actions
The template resource has the following actions:
:create
- (default) Create a file. If a file already exists (but does not match), update that file to match.
:create_if_missing
- Create a file only if the file does not exist. When the file exists, nothing happens.
:delete
- Delete a file.
: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.
:touch
- Touch a file. This updates the access (atime) and file modification (mtime) times for a file. (This action may be used with this resource, but is typically only used with the file resource.)
Properties
The template resource has the following properties:
atomic_update
- Ruby Type: true, false
Perform atomic file updates on a per-resource basis. Set to
true
for atomic file updates. Set tofalse
for non-atomic file updates. This setting overridesfile_atomic_update
, which is a global setting found in the client.rb file.
backup
- Ruby Type: Integer, false | Default Value:
5
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform). Set tofalse
to prevent backups from being kept.
cookbook
- Ruby Type: String
The cookbook in which a file is located (if it is not located in the current cookbook). The default value is the current cookbook.
force_unlink
- Ruby Type: true, false | Default Value:
false
How Chef Infra Client handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to
true
for Chef Infra Client to delete the non-file target and replace it with the specified file. Set tofalse
for Chef Infra Client to raise an error.
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
helper
- Ruby Type: Method | Default Value:
{}
Define a helper method inline. For example:
helper(:hello_world) { "hello world" }
orhelper(:app) { node["app"] }
orhelper(:app_conf) { |setting| node["app"][setting] }
.
helpers
- Ruby Type: Module | Default Value:
[]
Define a helper module inline or in a library. For example, an inline module:
helpers do
, which is then followed by a block of Ruby code. And for a library module:helpers(MyHelperModule)
.
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
local
- Ruby Type: true, false | Default Value:
false
Load a template from a local path. By default, Chef Infra Client loads templates from a cookbook’s
/templates
directory. When this property is set totrue
, use thesource
property to specify the path to a template on the local node.
manage_symlink_source
- Ruby Type: true, false | Default Value:
true
(with warning) Change the behavior of the file resource if it is pointed at a symlink. When this value is set to
true
, Chef Infra Client will manage the symlink’s permissions or will replace the symlink with a normal file if the resource has content. When this value is set tofalse
, Chef will follow the symlink and will manage the permissions and content of the symlink’s target file. The default behavior istrue
but emits a warning that the default value will be changed tofalse
in a future version; setting this explicitly totrue
orfalse
suppresses this warning.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
. Ifmode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
. The behavior is different depending on the platform. UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
The full path to the file, including the file name and its extension. Microsoft Windows: A path that begins with a forward slash (
/
) will point to the root of the current working directory of Chef Infra Client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/
) is not recommended.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
source
- Ruby Type: String, Array
The location of a template file. By default, Chef Infra Client looks for a template file in the
/templates
directory of a cookbook. When thelocal
property is set totrue
, use to specify the path to a template on the local node. This property may also be used to distribute specific files to specific platforms. See “File Specificity” below for more information. Default value: thename
of the resource block. See “Syntax” section above for more information.
variables
- Ruby Type: Hash
A Hash of variables that are passed into a Ruby template file.
The
variables
property of the template resource can be used to reference a partial template file by using a Hash. For example:template '/file/name.txt' do variables partials: { 'partial_name_1.txt.erb' => 'message', 'partial_name_2.txt.erb' => 'message', 'partial_name_3.txt.erb' => 'message', } end
where each of the partial template files can then be combined using normal Ruby template patterns within a template file, such as:
<% @partials.each do |partial, message| %> Here is <%= partial %> <%= render partial, :variables => {:message => message} %> <% end %>
verify
- Ruby Type: String, Block
A block or a string that returns
true
orfalse
. A string, whentrue
is executed as a system command.A block is arbitrary Ruby defined within the resource block by using the
verify
property. When a block istrue
, Chef Infra Client will continue to update the file as appropriate.For example, this should return
true
:template '/tmp/baz' do verify { 1 == 1 } end
This should return
true
:template '/etc/nginx.conf' do verify 'nginx -t -c %{path}' end
This should return
true
:template '/tmp/bar' do verify { 1 == 1} end
And this should return
true
:template '/tmp/foo' do verify do |path| true end end
Whereas, this should return
false
:template '/tmp/turtle' do verify '/usr/bin/false' end
If a string or a block return
false
, the Chef Infra Client run will stop and an error is returned.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Using Templates
To use a template, two things must happen:
- A template resource must be added to a recipe
- An Embedded Ruby (ERB) template must be added to a cookbook
For example, the following template file and template resource settings
can be used to manage a configuration file named /etc/sudoers
. Within
a cookbook that uses sudo, the following resource could be added to
/recipes/default.rb
:
template '/etc/sudoers' do
source 'sudoers.erb'
mode '0440'
owner 'root'
group 'root'
variables(sudoers_groups: node['authorization']['sudo']['groups'],
sudoers_users: node['authorization']['sudo']['users'])
end
And then create a template called sudoers.erb
and save it to
templates/default/sudoers.erb
:
#
# /etc/sudoers
#
# Generated by Chef for <%= node['fqdn'] %>
#
Defaults !lecture,tty_tickets,!fqdn
# User privilege specification
root ALL=(ALL) ALL
<% @sudoers_users.each do |user| -%>
<%= user %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% end -%>
# Members of the sysadmin group may gain root privileges
%sysadmin ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% @sudoers_groups.each do |group| -%>
# Members of the group '<%= group %>' may gain root privileges
<%= group %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% end -%>
And then set the default attributes in attributes/default.rb
:
default['authorization']['sudo']['groups'] = %w(sysadmin wheel admin)
default['authorization']['sudo']['users'] = %w(jerry greg)
File Specificity
A cookbook is frequently designed to work across many platforms and is often required to distribute a specific template to a specific platform. A cookbook can be designed to support the distribution of templates across platforms, while ensuring that the correct template ends up on each system.The pattern for template specificity depends on two things: the lookup path and the source. The first pattern that matches is used:
/host-$fqdn/$source
/$platform-$platform_version/$source
/$platform/$source
/default/$source
/$source
Note
To specify a particular Windows version, use the operating system
version
number.
For example, a template in templates/windows-6.3
will be deployed on
systems installed with Windows 8.1.
Use an array with the source
property to define an explicit lookup
path. For example:
template '/test' do
source ["#{node.chef_environment}.erb", 'default.erb']
end
The following example emulates the entire file specificity pattern by defining it as an explicit path:
template '/test' do
source %W(
host-#{node['fqdn']}/test.erb
#{node['platform']}-#{node['platform_version']}/test.erb
#{node['platform']}/test.erb
default/test.erb
)
end
A cookbook may have a /templates
directory structure like this:
/templates/
windows-10
windows-6.3
windows
default
and a resource that looks something like the following:
template 'C:\path\to\file\text_file.txt' do
source 'text_file.txt'
mode '0755'
owner 'root'
group 'root'
end
This resource would be matched in the same order as the /templates
directory structure. For a node named host-node-desktop
that is
running Windows 8.1, the second item would be the matching item and the
location:
/templates
windows-10/text_file.txt
windows-6.3/text_file.txt
windows/text_file.txt
default/text_file.txt
Helpers
A helper is a method or a module that can be used to extend a template. There are three approaches:
- An inline helper method
- An inline helper module
- A cookbook library module
Use the helper
attribute in a recipe to define an inline helper
method. Use the helpers
attribute to define an inline helper module or
a cookbook library module.
Inline Methods
A template helper method is always defined inline on a resource basis. A simple example:
template '/path' do
helper(:hello_world) { 'hello world' }
end
Another way to define an inline helper method is to reference a node object so that repeated calls to one (or more) cookbook attributes can be done efficiently:
template '/path' do
helper(:app) { node['app'] }
end
An inline helper method can also take arguments:
template '/path' do
helper(:app_conf) { |setting| node['app'][setting] }
end
Once declared, a template can then use the helper methods to build a file. For example:
Say hello: <%= hello_world %>
or:
node['app']['listen_port'] is: <%= app['listen_port'] %>
or:
node['app']['log_location'] is: <%= app_conf('log_location') %>
Inline Modules
A template helper module can be defined inline on a resource basis. This approach can be useful when a template requires more complex information. For example:
template '/path' do
helpers do
def hello_world
'hello world'
end
def app
node['app']
end
def app_conf(setting)
node['app']['setting']
end
end
end
where the hello_world
, app
, and app_conf(setting)
methods comprise
the module that extends a template.
Library Modules
A template helper module can be defined in a library. This is useful when extensions need to be reused across recipes or to make it easier to manage code that would otherwise be defined inline for each recipe basis.
template '/path/to/template.erb' do
helpers(MyHelperModule)
end
Host Notation
The naming of folders within cookbook directories must literally match the host notation used for template specificity matching. For example, if a host is namedfoo.example.com
, then the folder must be named
host-foo.example.com
.Partial Templates
A template can be built in a way that allows it to contain references to one (or more) smaller template files. (These smaller template files are also referred to as partials.) A partial can be referenced from a template file in one of the following ways:
- By using the
render
method in the template file - By using the template resource and the
variables
property.
render Method
Use the render
method in a template to reference a partial template
file:
<%= render 'partial_name.txt.erb', :option => {} %>
where partial_name
is the name of the partial template file and
:option
is one (or more) of the following:
Option | Description |
---|---|
:cookbook | By default, a partial template file is assumed to be located in the cookbook that contains the top-level template. Use this option to specify the path to a different cookbook |
:local | Indicates that the name of the partial template file should be interpreted as a path to a file in the local file system or looked up in a cookbook using the normal rules for template files. Set to true to interpret as a path to a file in the local file system and to false to use the normal rules for template files |
:source | By default, a partial template file is identified by its file name. Use this option to specify a different name or a local path to use (instead of the name of the partial template file) |
:variables | A hash of variable_name => value that will be made available to the partial template file. When this option is used, any variables that are defined in the top-level template that are required by the partial template file must have them defined explicitly using this option |
For example:
<%= render 'simple.txt.erb', :variables => {:user => Etc.getlogin }, :local => true %>
Transfer Frequency
The Chef Infra Client caches a template when it is first requested. On each subsequent request for that template, the Chef Infra Client compares that request to the template located on the Chef Infra Server. If the templates are the same, no transfer occurs.Variables
An Embedded Ruby (ERB) template allows Ruby code to be embedded inside a
text file within specially formatted tags. Ruby code can be embedded
using expressions and statements. An expression is delimited by <%=
and %>
. For example:
<%= "my name is #{$ruby}" %>
A statement is delimited by a modifier, such as if
, elsif
, and
else
. For example:
if false
# this will not happen
elsif nil
# this will not either
end
Using a Ruby expression is the most common approach for defining
template variables because this is how all variables that are sent to a
template are referenced. Whenever a template needs to use an each
,
if
, or end
, use a Ruby statement.
When a template is rendered, Ruby expressions and statements are
evaluated by Chef Infra Client. The variables listed in the template
resource’s variables
parameter and in the node object are evaluated.
Chef Infra Client then passes these variables to the template, where
they will be accessible as instance variables within the template. The
node object can be accessed just as if it were part of a recipe, using
the same syntax.
For example, a simple template resource like this:
node['fqdn'] = 'latte'
template '/tmp/foo' do
source 'foo.erb'
variables(x_men: 'are keen')
end
And a simple Embedded Ruby (ERB) template like this:
The node <%= node[:fqdn] %> thinks the x-men <%= @x_men %>
Would render something like:
The node latte thinks the x-men are keen
Even though this is a simple example, the full capabilities of Ruby can be used to tackle even the most complex and demanding template requirements.
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 template resource in recipes:
Configure a file from a template
template '/tmp/config.conf' do
source 'config.conf.erb'
end
Configure a file from a local template
template '/tmp/config.conf' do
local true
source '/tmp/config.conf.erb'
end
Configure a file using a variable map
template '/tmp/config.conf' do
source 'config.conf.erb'
variables(
:config_var => node['configs']['config_var']
)
end
Use the not_if condition
The following example shows how to use the not_if
condition to create
a file based on a template and using the presence of an attribute value
on the node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { node['some_value'] }
end
The following example shows how to use the not_if
condition to create
a file based on a template and then Ruby code to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if do
File.exist?('/etc/passwd')
end
end
The following example shows how to use the not_if
condition to create
a file based on a template and using a Ruby block (with curly braces) to
specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { File.exist?('/etc/passwd') }
end
The following example shows how to use the not_if
condition to create
a file based on a template and using a string to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if 'test -f /etc/passwd'
end
Use the only_if condition
The following example shows how to use the only_if
condition to create
a file based on a template and using the presence of an attribute on the
node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if { node['some_value'] }
end
The following example shows how to use the only_if
condition to create
a file based on a template, and then use Ruby to specify a condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if { ! ::File.exist?('/etc/passwd') }
end
The following example shows how to use the only_if
condition to create
a file based on a template and using a string to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if 'test -f /etc/passwd'
end
Use a whitespace array (%w)
The following example shows how to use a Ruby whitespace array to define a list of configuration tools, and then use that list of tools within the template resource to ensure that all of these configuration tools are using the same RSA key:
%w{openssl.cnf pkitool vars Rakefile}.each do |f|
template "/etc/openvpn/easy-rsa/#{f}" do
source "#{f}.erb"
owner 'root'
group 'root'
mode '0755'
end
end
Use a relative path
template "#{ENV['HOME']}/chef-getting-started.txt" do
source 'chef-getting-started.txt.erb'
mode '0755'
end
Delay notifications
template '/etc/nagios3/configures-nagios.conf' do
# other parameters
notifies :run, 'execute[test-nagios-config]', :delayed
end
Notify immediately
By default, notifications are :delayed
, that is they are queued up as
they are triggered, and then executed at the very end of a Chef Infra
Client run. To run an action immediately, use :immediately
:
template '/etc/nagios3/configures-nagios.conf' do
# other parameters
notifies :run, 'execute[test-nagios-config]', :immediately
end
and then Chef Infra Client would immediately run the following:
execute 'test-nagios-config' do
command 'nagios3 --verify-config'
action :nothing
end
Notify multiple resources
template '/etc/chef/server.rb' do
source 'server.rb.erb'
owner 'root'
group 'root'
mode '0755'
notifies :restart, 'service[chef-solr]', :delayed
notifies :restart, 'service[chef-solr-indexer]', :delayed
notifies :restart, 'service[chef-server]', :delayed
end
Reload a service
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
notifies :reload, 'service[apache]', :immediately
end
Restart a service when a template is modified
template '/etc/www/configures-apache.conf' do
notifies :restart, 'service[apache]', :immediately
end
Send notifications to multiple resources
To send notifications to multiple resources, just use multiple attributes. Multiple attributes will get sent to the notified resources in the order specified.
template '/etc/netatalk/netatalk.conf' do
notifies :restart, 'service[afpd]', :immediately
notifies :restart, 'service[cnid]', :immediately
end
service 'afpd'
service 'cnid'
Execute a command using a template
The following example shows how to set up IPv4 packet forwarding using
the execute resource to run a command named forward_ipv4
that uses
a template defined by the template resource:
execute 'forward_ipv4' do
command 'echo > /proc/.../ipv4/ip_forward'
action :nothing
end
template '/etc/file_name.conf' do
source 'routing/file_name.conf.erb'
notifies :run, 'execute[forward_ipv4]', :delayed
end
where the command
property for the execute resource contains the
command that is to be run and the source
property for the template
resource specifies which template to use. The notifies
property for
the template specifies that the execute[forward_ipv4]
(which is
defined by the execute resource) should be queued up and run at the
end of a Chef Infra Client run.
Set an IP address using variables and a template
The following example shows how the template resource can be used in a recipe to combine settings stored in an attributes file, variables within a recipe, and a template to set the IP addresses that are used by the Nginx service. The attributes file contains the following:
default['nginx']['dir'] = '/etc/nginx'
The recipe then does the following to:
- Declare two variables at the beginning of the recipe, one for the remote IP address and the other for the authorized IP address
- Use the service resource to restart and reload the Nginx service
- Load a template named
authorized_ip.erb
from the/templates
directory that is used to set the IP address values based on the variables specified in the recipe
node.default['nginx']['remote_ip_var'] = 'remote_addr'
node.default['nginx']['authorized_ips'] = ['127.0.0.1/32']
service 'nginx' do
supports :status => true, :restart => true, :reload => true
end
template 'authorized_ip' do
path "#{node['nginx']['dir']}/authorized_ip"
source 'modules/authorized_ip.erb'
owner 'root'
group 'root'
mode '0755'
variables(
:remote_ip_var => node['nginx']['remote_ip_var'],
:authorized_ips => node['nginx']['authorized_ips']
)
notifies :reload, 'service[nginx]', :immediately
end
where the variables
property tells the template to use the variables
set at the beginning of the recipe and the source
property is used to
call a template file located in the cookbook’s /templates
directory.
The template file looks similar to:
geo $<%= @remote_ip_var %> $authorized_ip {
default no;
<% @authorized_ips.each do |ip| %>
<%= "#{ip} yes;" %>
<% end %>
}
Add a rule to an IP table
The following example shows how to add a rule named test_rule
to an IP
table using the execute resource to run a command using a template
that is defined by the template resource:
execute 'test_rule' do
command 'command_to_run
--option value
...
--option value
--source #{node[:name_of_node][:ipsec][:local][:subnet]}
-j test_rule'
action :nothing
end
template '/etc/file_name.local' do
source 'routing/file_name.local.erb'
notifies :run, 'execute[test_rule]', :delayed
end
where the command
property for the execute resource contains the
command that is to be run and the source
property for the template
resource specifies which template to use. The notifies
property for
the template specifies that the execute[test_rule]
(which is
defined by the execute resource) should be queued up and run at the
end of a Chef Infra Client run.
Apply proxy settings consistently across a Chef organization
The following example shows how a template can be used to apply consistent proxy settings for all nodes of the same type:
template "#{node['matching_node']['dir']}/sites-available/site_proxy.conf" do
source 'site_proxy.matching_node.conf.erb'
owner 'root'
group 'root'
mode '0755'
variables(
:ssl_certificate => "#{node['matching_node']['dir']}/shared/certificates/site_proxy.crt",
:ssl_key => "#{node['matching_node']['dir']}/shared/certificates/site_proxy.key",
:listen_port => node['site']['matching_node_proxy']['listen_port'],
:server_name => node['site']['matching_node_proxy']['server_name'],
:fqdn => node['fqdn'],
:server_options => node[:site]['matching_node']['server']['options'],
:proxy_options => node[:site]['matching_node']['proxy']['options']
)
end
where matching_node
represents a type of node (like Nginx) and
site_proxy
represents the type of proxy being used for that type of
node (like Nexus).
Get template settings from a local file
The template resource can be used to render a template based on settings contained in a local file on disk or to get the settings from a template in a cookbook. Most of the time, the settings are retrieved from a template in a cookbook. The following example shows how the template resource can be used to retrieve these settings from a local file.
The following example is based on a few assumptions:
- The environment is a Ruby on Rails application that needs render a
file named
database.yml
- Information about the application—the user, their password, the server—is stored in a data bag on the Chef server
- The application is already deployed to the system and that only
requirement in this example is to render the
database.yml
file
The application source tree looks something like:
myapp/
-> config/
-> database.yml.erb
Note
There should not be a file named database.yml
(without the .erb
), as the database.yml
file is what will be rendered using the template resource.
The deployment of the app will end up in /srv
, so the full path to
this template would be something like
/srv/myapp/current/config/database.yml.erb
.
The content of the template itself may look like this:
<%= @rails_env %>:
adapter: <%= @adapter %>
host: <%= @host %>
database: <%= @database %>
username: <%= @username %>
password: <%= @password %>
encoding: 'utf8'
reconnect: true
The recipe will be similar to the following:
results = search(:node, "role:myapp_database_master AND chef_environment:#{node.chef_environment}")
db_master = results[0]
template '/srv/myapp/shared/database.yml' do
source '/srv/myapp/current/config/database.yml.erb'
local true
variables(
:rails_env => node.chef_environment,
:adapter => db_master['myapp']['db_adapter'],
:host => db_master['fqdn'],
:database => "myapp_#{node.chef_environment}",
:username => "myapp",
:password => "SUPERSECRET",
)
end
where:
- the
search
method in the Chef Infra Language is used to find the first node that is the database master (of which there should only be one) - the
:adapter
variable property may also require an attribute to have been set on a role, which then determines the correct adapter
The template will render similar to the following:
production:
adapter: mysql
host: domU-12-31-39-14-F1-C3.compute-1.internal
database: myapp_production
username: myapp
password: SUPERSECRET
encoding: utf8
reconnect: true
This example showed how to use the template resource to render a template based on settings contained in a local file. Some other issues that should be considered when using this type of approach include:
- Should the
database.yml
file be in a.gitignore
file? - How do developers run the application locally?
- Does this work with chef-solo?
Pass values from recipe to template
The following example shows how pass a value to a template using the
variables
property in the template resource. The template file is
similar to:
[tcpout]
defaultGroup = splunk_indexers_<%= node['splunk']['receiver_port'] %>
disabled=false
[tcpout:splunk_indexers_<%= node['splunk']['receiver_port'] %>]
server=<% @splunk_servers.map do |s| -%><%= s['ipaddress'] %>:<%= s['splunk']['receiver_port'] %> <% end.join(', ') -%>
<% @outputs_conf.each_pair do |name, value| -%>
<%= name %> = <%= value %>
<% end -%>
The recipe then uses the variables
attribute to find the values for
splunk_servers
and outputs_conf
, before passing them into the
template:
template "#{splunk_dir}/etc/system/local/outputs.conf" do
source 'outputs.conf.erb'
mode '0755'
variables :splunk_servers => splunk_servers, :outputs_conf => node['splunk']['outputs_conf']
notifies :restart, 'service[splunk]'
end
This example can be found in the client.rb
recipe and the
outputs.conf.erb
template files that are located in the chef-splunk
cookbook that is
maintained by Chef.