About Templates

The templates directory doesn’t exist by default in a cookbook. Generate the templates directory and a template file from the chef-repo/cookbooks directory with the command:

chef generate template PATH_TO_COOKBOOK TEMPLATE_NAME

For example, this command generates a httpd template in the custom_web cookbook:

chef generate template cookbooks/custom_web httpd

The custom_web cookbook directory with a template has the structure:

. cookbooks
├── README.md
└── custom_web
    ├── CHANGELOG.md
    ├── LICENSE
    ├── Policyfile.rb
    ├── README.md
    ├── chefignore
    ├── compliance
    │   ├── README.md
    │   ├── inputs
    │   ├── profiles
    │   └── waivers
    ├── kitchen.yml
    ├── metadata.rb
    ├── recipes
    │   └── default.rb
    ├── templates
    │   └── httpd.erb
    └── test
        └── integration
            └── default
                └── default_test.rb

Requirements

To use a template, two things must happen:

1. A template resource must be added to a recipe
2. 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)

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 won't happen
elsif nil
      # this won't 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.

File Specificity

The pattern for template specificity depends on two things: the lookup path and the source. The first pattern that matches is used:

1. /host-$fqdn/$source
2. /$platform-$platform_version/$source
3. /$platform/$source
4. /default/$source
5. /$source

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’s 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

Host Notation

Transfer Frequency

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.

variables Attribute

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 %>

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:

For example:

<%= render 'simple.txt.erb', :variables => {:user => Etc.getlogin }, :local => true %>