Ресурс шаблона

Изменить эту страницу в репозитории Chef

Страница всех ресурсов Infra

Шаблон кулинарной книги — это шаблон Embedded Ruby (ERB), используемый для динамической генерации статических текстовых файлов. Шаблоны могут содержать выражения и операторы Ruby и являются отличным способом управления конфигурационными файлами. Используйте ресурс template для добавления шаблонов кулинарной книги в рецепты; поместите соответствующий файл шаблона Embedded Ruby (ERB) в каталог /templates кулинарной книги.

Используйте ресурс template для управления содержимым файла с помощью шаблона Embedded Ruby (ERB), передавая файлы из подкаталога COOKBOOK_NAME/templates/ в указанный путь на узле, на котором запущен Chef Infra Client. Этот ресурс включает действия и свойства из ресурса file. Файлы шаблонов, управляемые ресурсом template, следуют тем же правилам специфичности файла, что и ресурсы remote_file и file.

Синтаксис

Блок ресурса template обычно объявляет расположение, в котором должен быть создан файл, исходный шаблон, который будет использоваться для создания файла, и разрешения, необходимые для этого файла. Например:

template '/etc/motd' do
  source 'motd.erb'
  owner 'root'
  group 'root'
  mode '0755'
end

где:

• '/etc/motd' указывает расположение, в котором создается файл
• 'motd.erb' указывает имя шаблона, который существует в папке /templates кулинарной книги
• owner, group, и mode определяют разрешения

Полный синтаксис всех свойств, доступных ресурсу template, следующий:

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

где:

• template — это ресурс
• name — имя блока ресурса, как правило, путь к расположению, в котором создается файл, и также имя управляемого файла. Например: /var/www/html/index.html, где /var/www/html/ — это полный путь к расположению, а index.html — имя файла
• source — это файл шаблона, который будет использоваться для создания файла на узле, например: index.html.erb; файл шаблона находится в каталоге /templates кулинарной книги
• action определяет действия, которые Chef Infra Client предпримет для приведения узла в нужное состояние
• atomic_update, backup, cookbook, force_unlink, group, helper, helpers, inherits, local, manage_symlink_source, mode, owner, path, rights, source, variables, и verify — это свойства этого ресурса с указанным типом Ruby. Подробную информацию обо всех свойствах, которые могут использоваться с этим ресурсом, см. в разделе «Свойства» ниже.

Действия

Ресурс template имеет следующие действия:

:create

По умолчанию. Создать файл. Если файл уже существует (но не совпадает), обновить этот файл, чтобы он совпадал.

:create_if_missing

Создать файл только в том случае, если файла не существует. Если файл существует, ничего не происходит.

:delete

Удалить файл.

:nothing

Этот блок ресурса не действует, пока не получит уведомление от другого ресурса о выполнении действия. После уведомления этот блок ресурса либо выполняется немедленно, либо ставится в очередь для выполнения в конце выполнения Chef Infra Client.

:touch

Обновить файл. Обновляются время последнего доступа (atime) и время последнего изменения (mtime) файла. (Это действие можно использовать с этим ресурсом, но обычно используется только с ресурсом file.)

Свойства

Ресурс template имеет следующие свойства:

atomic_update

Тип Ruby: true, false

Выполнять атомарные обновления файлов на основе каждого ресурса. Установите в true для атомарных обновлений файлов. Установите в false для неатомарных обновлений файлов. Это значение переопределяет file_atomic_update, которое является глобальным значением, найденным в файле client.rb.

backup

Тип Ruby: Целое число, false | Значение по умолчанию: 5

Количество резервных копий, которые будут храниться в /var/chef/backup (для систем на базе UNIX и Linux) или C:/chef/backup (для платформы Microsoft Windows). Установите в false, чтобы не хранить резервные копии.

cookbook

Тип Ruby: Строка

Кулинарная книга, в которой находится файл (если он не находится в текущей кулинарной книге). Значение по умолчанию — текущая кулинарная книга.

force_unlink

Тип Ruby: true, false | Значение по умолчанию: false

Как Chef Infra Client обрабатывает определенные ситуации, когда целевой файл оказывается не файлом. Например, когда целевой файл фактически является символической ссылкой. Установите в true для удаления целевого файла, который не является файлом, и замены его указанным файлом. Установите в false для вывода ошибки Chef Infra Client.

group

Тип Ruby: Целое число, Строка

Строка или идентификатор, определяющий владельца группы по имени группы или SID, включая полные имена групп, такие как domain\group или group@domain. Если это значение не указано, существующие группы остаются без изменений, а новые назначения групп используют стандартную группу POSIX (если доступна).

helper

Тип Ruby: Метод | Значение по умолчанию: {}

Определите встроенный вспомогательный метод. Например: helper(:hello_world) { "hello world" } или helper(:app) { node["app"] } или helper(:app_conf) { |setting| node["app"][setting] }.

helpers

Тип Ruby: Модуль | Значение по умолчанию: []

Определите встроенный или библиотечный вспомогательный модуль. Например, встроенный модуль: helpers do, за которым следует блок кода Ruby. И для модуля библиотеки: helpers(MyHelperModule).

inherits

Тип Ruby: true, false | Значение по умолчанию: true

Только для Microsoft Windows. Наследует ли файл права из родительского каталога.

local

Тип Ruby: true, false | Значение по умолчанию: false

Загрузить шаблон из локального пути. По умолчанию Chef Infra Client загружает шаблоны из каталога /templates кулинарной книги. Когда это свойство установлено в true, используйте свойство source для указания пути к шаблону на локальном узле.

manage_symlink_source

Тип Ruby: true, false | Значение по умолчанию: true

(с предупреждением)

Изменить поведение ресурса файла, если он указывает на символическую ссылку. Если это значение установлено в true, Chef Infra Client будет управлять разрешениями символической ссылки или заменит символическую ссылку обычным файлом, если у ресурса есть содержимое. Если это значение установлено в false, Chef будет следовать символической ссылке и будет управлять разрешениями и содержимым целевого файла символической ссылки.

Поведение по умолчанию — true, но отображается предупреждение, что значение по умолчанию будет изменено на false в будущей версии; явное задание этого значения в true или false подавляет это предупреждение.

mode

Тип Ruby: Целое число, Строка

Заданная в кавычках строка длиной от 3 до 5 символов, определяющая восьмеричный режим. Например: '755', '0755', или 00755. Если mode не указано, а файл уже существует, используется существующий режим файла. Если mode не указано, файл не существует, и указано действие :create, Chef Infra Client предполагает значение маски '0777' и затем применяет маску системы, на которой файл должен быть создан, к значению mask. Например, если маска на системе — '022', Chef Infra Client использует значение по умолчанию '0755'.

Поведение отличается в зависимости от платформы.

Системы на базе UNIX и Linux: в кавычках указана строка длиной от 3 до 5 символов, определяющая восьмеричный режим, который передается в chmod. Например: '755', '0755', или 00755. Если значение задано в кавычках, оно работает точно так же, как если бы была передана команда chmod. Если значение задано как целое число, добавьте ноль (0) к значению, чтобы оно интерпретировалось как восьмеричное число. Например, чтобы назначить права чтения, записи и выполнения всем пользователям, используйте '0777' или '777'; для тех же прав плюс бит «вклейки», используйте 01777 или '1777'.

Microsoft Windows: в кавычках указана строка длиной от 3 до 5 символов, определяющая восьмеричный режим, который преобразуется в права для безопасности Microsoft Windows. Например: '755', '0755', или 00755. Разрешены значения до '0777' (без бита «вклейки»), которые означают то же самое в Microsoft Windows, что и в UNIX, где 4 равно GENERIC_READ, 2 равно GENERIC_WRITE, и 1 равно GENERIC_EXECUTE. Это свойство нельзя использовать для установки :full_control. Это свойство не оказывает никакого влияния, если не указано, но когда оно и rights указаны оба, эффекты являются кумулятивными.

owner

Тип Ruby: Целое число, строка

Строка или идентификатор, определяющий владельца группы по имени пользователя или SID, включая полные имена пользователей, такие как domain\user или user@domain. Если это значение не указано, существующие владельцы останутся неизменными, а новые назначения владельцев будут использовать текущего пользователя (при необходимости).

path

Тип Ruby: Строка | Значение по умолчанию: The resource block's name

Полный путь к файлу, включая имя файла и его расширение.

Microsoft Windows: Путь, начинающийся с косой черты (/) указывает на корень текущего рабочего каталога процесса клиента Chef Infra. Этот путь может отличаться от системы к системе. Поэтому использование пути, начинающегося с косой черты (/) не рекомендуется.

rights

Тип Ruby: Целое число, строка

Только Microsoft Windows. Разрешения для пользователей и групп в среде Microsoft Windows. Например: rights <permissions>, <principal>, <options> где <permissions> определяет права, предоставляемые принципалу, <principal> — имя группы или пользователя, а <options> — массив с одним (или несколькими) расширенными параметрами прав.

source

Тип Ruby: Строка, массив

Расположение файла шаблона. По умолчанию Chef Infra Client ищет файл шаблона в каталоге /templates кулинарной книги. Когда свойство local установлено в значение true, используйте его для указания пути к шаблону на локальном узле. Это свойство также можно использовать для распространения определенных файлов на определенные платформы. Дополнительная информация в разделе «Специфика файлов» ниже. Значение по умолчанию: name блока ресурса. Дополнительная информация в разделе «Синтаксис» выше.

variables

Тип Ruby: Массив

Массив переменных, передаваемых в файл шаблона Ruby.

Свойство variables ресурса template можно использовать для ссылки на частичный файл шаблона с помощью массива. Например:

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

где каждый из частичных файлов шаблонов затем можно объединить с помощью стандартных шаблонов Ruby в файле шаблона, таких как:

<% @partials.each  do |partial, message| %>
  Here is <%= partial %>
  <%= render partial, :variables => {:message => message} %>
<% end %>

verify

Тип Ruby: Строка, блок

Блок или строка, возвращающая true или false. Строка, когда true выполняется как системная команда.

Блок — произвольный Ruby, определенный в блоке ресурса с помощью свойства verify. Когда блок true, Chef Infra Client будет продолжать обновлять файл по мере необходимости.

Например, это должно возвращать true:

template '/tmp/baz' do
  verify { 1 == 1 }
end

Это должно возвращать true:

template '/etc/nginx.conf' do
  verify 'nginx -t -c %{path}'
end

Это должно возвращать true:

template '/tmp/bar' do
  verify { 1 == 1}
end

А это должно возвращать true:

template '/tmp/foo' do
  verify do |path|
    true
  end
end

В то время как это должно возвращать false:

template '/tmp/turtle' do
  verify '/usr/bin/false'
end

Если строка или блок возвращают false, выполнение Chef Infra Client прекращается, и возвращается ошибка.

Атомарные обновления файлов

Атомарные обновления используются с ресурсами на основе файлов, чтобы гарантировать, что обновления файлов могут быть выполнены при обновлении двоичного файла или если закончилось место на диске.

Атомарные обновления включены по умолчанию. Их можно управлять глобально, используя настройку file_atomic_update в файле client.rb. Их можно управлять на уровне каждого ресурса, используя свойство atomic_update, доступное для ресурсов cookbook_file, file, remote_file и template.

Безопасность файлов в Windows

Свойство rights может быть использовано в рецепте для управления списками управления доступом (ACL), которые позволяют предоставлять права доступа нескольким пользователям и группам. Свойство rights можно использовать столько раз, сколько необходимо; Chef Infra Client применит их к файлу или каталогу по мере необходимости. Синтаксис свойства rights следующий:

rights permission, principal, option_type => value

где

permission

Используется для указания прав, предоставляемых principal. Возможные значения: :read, :write, read_execute, :modify, :full_control, или целое число.

Целые числа, используемые для прав, должны соответствовать следующему списку FileSystemRights Enum полей.

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 Microsoft Windows API: `:read` corresponds
to `GENERIC_READ`; `:write` corresponds to `GENERIC_WRITE`;
`:read_execute` corresponds to `GENERIC_READ` and `GENERIC_EXECUTE`;
`:modify` corresponds to `GENERIC_WRITE`, `GENERIC_READ`,
`GENERIC_EXECUTE`, and `DELETE`; `:full_control` corresponds to
`GENERIC_ALL`, which allows a user to change the owner and other
metadata about a file.)

principal

Используется для указания группы или пользователя. Принцип может быть указан либо по имени, либо по SID. При использовании имени это идентично тому, что вводится в поле входа для Microsoft Windows, например, user_name, domain\user_name, или user_name@fully_qualified_domain_name. При использовании SID вы можете использовать либо стандартное строковое представление SID (S-R-I-S-S), либо одно из строковых констант SDDL. Chef Infra Client не нужно знать, является ли принцип пользователем или группой.

option_type

Массив, содержащий расширенные параметры прав. Например, права каталога, которые применяются только к первому уровню дочерних элементов, могут выглядеть примерно так: rights :write, 'domain\group_name', :one_level_deep => true. Возможные типы опций:

Тип опции	Описание
:applies_to_children	Указывает, как права применяются к дочерним элементам. Возможные значения: true для наследования как дочерних каталогов, так и файлов; false для отказа от наследования любых дочерних каталогов или файлов; :containers_only для наследования только дочерних каталогов (и не файлов); :objects_only для рекурсивного наследования файлов (и не дочерних каталогов).
:applies_to_self	Указывает, применяется ли разрешение к родительскому каталогу. Возможные значения: true для применения к родительскому каталогу или файлу и его дочерним элементам; false для применения только к дочерним каталогам и файлам.
:one_level_deep	Указывает глубину применения прав. Возможные значения: true для применения только к первому уровню дочерних элементов; false для применения ко всем дочерним элементам.

Например:

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

или:

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

Некоторые другие важные моменты при использовании атрибута rights:

• Остаются только унаследованные права. Все существующие явные права на объект удаляются и заменяются.
• Если права не указаны, ничего не изменится. Chef Infra Client не очищает права файла или каталога, если права не указаны.
• Изменение унаследованных прав может быть дорогостоящим. Microsoft Windows будет рекурсивно распространять права на все дочерние элементы из-за наследования. Это нормальный аспект Microsoft Windows, поэтому следует учитывать частоту такого типа действий и принять меры для управления такими действиями, если производительность является основным фактором.

Используйте свойство deny_rights для запрета определенных прав определенным пользователям. Порядок не зависит от использования свойства rights. Например, неважно, помещаются ли права для всех перед или после deny_rights :read, ['Julian', 'Lewis'], оба — Джулиан и Левис — не смогут прочитать документ. Например:

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

или:

deny_rights :full_control, ['Sally']

По умолчанию файл или каталог наследует права из родительского каталога. В большинстве случаев это предпочтительное поведение, но иногда может потребоваться принять меры для более точного управления правами. Свойство inherits можно использовать для явного указания Chef Infra Client применять (или не применять) унаследованные права из родительского каталога.

Например, следующий пример определяет права для каталога:

directory 'C:\mordor' do
  rights :read, 'MORDOR\Minions'
  rights :full_control, 'MORDOR\Sauron'
end

а затем следующий пример показывает, как использовать наследование для запрета доступа к дочернему каталогу:

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

Если вместо этого было бы использовано разрешение deny_rights, что-то могло бы проскочить, если бы всем пользователям и группам не было отказано.

Еще один пример также демонстрирует, как определить права для каталога:

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

но затем не использовать свойство inherits для запрета этих прав на дочернем каталоге:

directory 'C:\mordor\mount_doom' do
  deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end

Поскольку свойство inherits не указано, Chef Infra Client установит его по умолчанию в true, что гарантирует сохранение настроек безопасности существующих файлов.

Использование шаблонов

Для использования шаблона необходимо выполнить два действия:

1. В рецепт должен быть добавлен ресурс шаблона
2. Шаблон Embedded Ruby (ERB) должен быть добавлен в кулинарную книгу

Например, следующие настройки файла шаблона и ресурса шаблона могут использоваться для управления конфигурационным файлом, названным /etc/sudoers. В кулинарной книге, использующей sudo, следующий ресурс можно добавить в /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

И затем создайте шаблон, названный sudoers.erb, и сохраните его в 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 -%>

И затем установите значения по умолчанию для атрибутов в attributes/default.rb:

default['authorization']['sudo']['groups'] = %w(sysadmin wheel admin)
default['authorization']['sudo']['users'] = %w(jerry greg)

Специфичность файла

Шаблон специфичности шаблона зависит от двух вещей: пути поиска и источника. Используется первый подходящий шаблон:

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

Используйте массив с свойством source для определения явного пути поиска. Например:

template '/test' do
  source ["#{node.chef_environment}.erb", 'default.erb']
end

Следующий пример имитирует весь шаблон специфичности файла, определив его как явный путь:

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

Кулинарная книга может иметь структуру каталогов /templates следующего вида:

/templates/
  windows-10
  windows-6.3
  windows
  default

и ресурс, который выглядит примерно так:

template 'C:\path\to\file\text_file.txt' do
  source 'text_file.txt'
  mode '0755'
  owner 'root'
  group 'root'
end

Этот ресурс будет сопоставлен в том же порядке, что и структура каталогов /templates. Для узла под названием host-node-desktop, работающего под Windows 8.1, второй элемент будет соответствующим элементом и местоположением:

/templates
  windows-10/text_file.txt
  windows-6.3/text_file.txt
  windows/text_file.txt
  default/text_file.txt

Вспомогательные средства

Вспомогательное средство — это метод или модуль, который может быть использован для расширения шаблона. Существует три подхода:

• Встроенный метод вспомогательного средства
• Встроенный модуль вспомогательного средства
• Модуль библиотеки кулинарной книги

Используйте атрибут helper в рецепте для определения встроенного метода вспомогательного средства. Используйте атрибут helpers для определения встроенного модуля вспомогательного средства или модуля библиотеки кулинарной книги.

Встроенные методы

Метод вспомогательного средства шаблона всегда определяется встроенным образом на уровне каждого ресурса. Простой пример:

template '/path' do
  helper(:hello_world) { 'hello world' }
end

Другой способ определить встроенный метод вспомогательного средства — сослаться на объект узла, чтобы многократно вызывать атрибуты одной (или нескольких) кулинарных книг эффективно:

template '/path' do
  helper(:app) { node['app'] }
end

Встроенный метод вспомогательного средства также может принимать аргументы:

template '/path' do
  helper(:app_conf) { |setting| node['app'][setting] }
end

После объявления шаблон может использовать методы вспомогательных средств для построения файла. Например:

Say hello: <%= hello_world %>

или:

node['app']['listen_port'] is: <%= app['listen_port'] %>

или:

node['app']['log_location'] is: <%= app_conf('log_location') %>

Встроенные модули

Модуль вспомогательного средства шаблона может быть определён встроенным образом на уровне каждого ресурса. Этот подход может быть полезен, когда шаблон требует более сложной информации. Например:

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

где методы hello_world, app, и app_conf(setting) составляют модуль, расширяющий шаблон.

Модули библиотеки

Модуль вспомогательного средства шаблона может быть определён в библиотеке. Это полезно, когда расширения необходимо повторно использовать в рецептах или для упрощения управления кодом, который в противном случае был бы определён встроенным образом на уровне каждого рецепта.

template '/path/to/template.erb' do
  helpers(MyHelperModule)
end

Нотация хоста

Частичные шаблоны

Шаблон может быть создан таким образом, чтобы содержать ссылки на один (или несколько) меньших файлов шаблонов. (Эти меньшие файлы шаблонов также называются частями.) Часть может быть указана в файле шаблона одним из следующих способов:

• Используя метод render в файле шаблона
• Используя ресурс template и свойство variables.

Метод render

Используйте метод render в шаблоне для ссылки на файл частичного шаблона:

<%= render 'partial_name.txt.erb', :option => {} %>

где partial_name — имя файла частичного шаблона, а :option — один (или несколько) из следующих:

Например:

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

Частота передачи

Переменные

<%= "my name is #{$ruby}" %>

Инструкция ограничена модификатором, например, if, elsif, и else. Например:

if false
# this won't happen
elsif nil
      # this won't either
    end

Использование Ruby-выражения является наиболее распространённым подходом к определению переменных шаблона, поскольку именно так ссылаются на все переменные, которые отправляются в шаблон. Всякий раз, когда шаблон должен использовать each, if, или end, используйте Ruby-инструкцию.

При рендеринге шаблона Ruby-выражения и инструкции оцениваются клиентом Chef Infra. Оцениваются переменные, перечисленные в параметре variables ресурса template и в объекте узла. Клиент Chef Infra затем передаёт эти переменные шаблону, где они будут доступны как переменные экземпляра внутри шаблона. К объекту узла можно обращаться так же, как если бы он был частью рецепта, используя ту же синтаксическую конструкцию.

Например, простой ресурс шаблона такой:

node['fqdn'] = 'latte'
template '/tmp/foo' do
  source 'foo.erb'
  variables(x_men: 'are keen')
end

И простой шаблон Embedded Ruby (ERB) такой:

The node <%= node[:fqdn] %> thinks the x-men <%= @x_men %>

Сгенерирует что-то вроде:

The node latte thinks the x-men are keen

Хотя это очень простой пример, полные возможности Ruby можно использовать для решения даже самых сложных и требовательных задач шаблонов.

Общие функциональные возможности ресурсов

Ресурсы Chef включают общие свойства, уведомления и блокировки ресурсов.

Общие свойства

Следующие свойства общие для каждого ресурса:

compile_time

Тип Ruby: true, false | Значение по умолчанию: false

Управление фазой, в которой ресурс выполняется на узле. Установите в true, чтобы выполнить во время построения коллекции ресурсов (фаза compile phase). Установите в false, чтобы выполнить во время конфигурации узла клиентом Chef Infra (фаза converge phase).

ignore_failure

Тип Ruby: true, false, :quiet | Значение по умолчанию: false

Продолжать выполнение рецепта, если ресурс завершился ошибкой по любой причине. :quiet не отобразит полный стек вызовов, и рецепт продолжится, если ресурс завершился ошибкой.

retries

Тип Ruby: Целое число | Значение по умолчанию: 0

Количество попыток перехватить исключения и повторить ресурс.

retry_delay

Тип Ruby: Целое число | Значение по умолчанию: 2

Задержка в секундах между попытками повтора.

sensitive

Тип Ruby: true, false | Значение по умолчанию: false

Обеспечить, чтобы конфиденциальные данные ресурсов не регистрировались клиентом Chef Infra.

Уведомления

notifies

Тип Ruby: Символ, 'Chef::Resource[String]'

Ресурс может уведомить другой ресурс о выполнении действия при изменении его состояния. Укажите 'resource[name]', действие, которое должен выполнить ресурс :action, и :timer для этого действия. Один ресурс может уведомить несколько ресурсов; используйте оператор notifies для каждого ресурса, который должен быть уведомлен.

Если указанный ресурс не существует, возникает ошибка. В отличие от subscribes, который не завершится ошибкой, если исходный ресурс не найден.

Таймер указывает момент во время выполнения клиента Chef Infra, когда выполняется уведомление. Доступны следующие таймеры:

:before

Указывает, что действие над уведомлённым ресурсом должно быть выполнено до обработки блока ресурсов, в котором находится уведомление.

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и затем выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

Указывает, что уведомление должно быть выполнено немедленно для каждого уведомлённого ресурса.

Синтаксис для notifies:

notifies :action, 'resource[name]', :timer

subscribes

Тип Ruby: Символ, 'Chef::Resource[String]'

Ресурс может отслеживать другой ресурс и затем выполнить действие, если состояние отслеживаемого ресурса изменится. Укажите 'resource[name]', :action и :timer для этого действия.

Обратите внимание, что subscribes не применяет указанное действие к ресурсу, за которым он наблюдает — например:

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

В этом случае свойство subscribes перезагружает сервис nginx всякий раз, когда обновляется его сертификат, расположенный в /etc/nginx/ssl/example.crt. subscribes не вносит никаких изменений в сам сертификат, а только отслеживает изменения файла и выполняет действие :reload для своего ресурса (в данном примере nginx) при обнаружении изменений.

Если другого ресурса не существует, подписка не вызовет ошибку. Противопоставьте это более жёсткой семантике notifies, которая вызовет ошибку, если другого ресурса не существует.

Таймер указывает момент во время выполнения Chef Infra Client, в который выполняется уведомление. Доступны следующие таймеры:

:before

Указывает, что действие над уведомлённым ресурсом должно быть выполнено до обработки блока ресурсов, в котором находится уведомление.

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и затем выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

Указывает, что уведомление должно быть выполнено немедленно для каждого уведомлённого ресурса.

Синтаксис для subscribes:

subscribes :action, 'resource[name]', :timer

Филтры

Свойство фильтра может использоваться для оценки состояния узла во время фазы выполнения Chef Infra Client. Основываясь на результатах этой оценки, свойство фильтра затем сообщает Chef Infra Client, следует ли ему продолжать выполнение ресурса. Свойство фильтра принимает либо строковое значение, либо значение блока Ruby:

• Строка выполняется как команда оболочки. Если команда возвращает 0, фильтр применяется. Если команда возвращает любое другое значение, то свойство фильтра не применяется. Строковые фильтры в powershell_script выполняют команды Windows PowerShell и могут возвращать true в дополнение к 0.
• Блок выполняется как код Ruby, который должен вернуть либо true, либо false. Если блок возвращает true, свойство фильтра применяется. Если блок возвращает false, свойство фильтра не применяется.

Свойство фильтра полезно для обеспечения идемпотентности ресурса, позволяя этому ресурсу проверять желаемое состояние по мере его выполнения и, если желаемое состояние присутствует, Chef Infra Client ничего не делает.

Следующие свойства могут быть использованы для определения фильтра, который оценивается во время фазы выполнения Chef Infra Client:

not_if

Запретить выполнение ресурса, когда условие возвращает true.

only_if

Разрешить выполнение ресурса только если условие возвращает true.

Примеры

Следующие примеры демонстрируют различные подходы к использованию ресурса template в рецептах:

Настройка файла из шаблона

template '/tmp/config.conf' do
  source 'config.conf.erb'
end

Настройка файла из локального шаблона

template '/tmp/config.conf' do
  local true
  source '/tmp/config.conf.erb'
end

Настройка файла с использованием карты переменных

template '/tmp/config.conf' do
  source 'config.conf.erb'
  variables(
    :config_var => node['configs']['config_var']
  )
end

Использование условия not_if

Следующий пример демонстрирует, как использовать условие not_if для создания файла на основе шаблона и использования наличия значения атрибута на узле для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if { node['some_value'] }
end

Следующий пример демонстрирует, как использовать условие not_if для создания файла на основе шаблона, а затем код Ruby для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if do
    File.exist?('/etc/passwd')
  end
end

Следующий пример демонстрирует, как использовать условие not_if для создания файла на основе шаблона и использование блока Ruby (в фигурных скобках) для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if { File.exist?('/etc/passwd') }
end

Следующий пример демонстрирует, как использовать условие not_if для создания файла на основе шаблона и использование строки для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if 'test -f /etc/passwd'
end

Использование условия only_if

Следующий пример демонстрирует, как использовать условие only_if для создания файла на основе шаблона и использование наличия атрибута на узле для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  only_if { node['some_value'] }
end

Следующий пример демонстрирует, как использовать условие only_if для создания файла на основе шаблона, а затем использовать Ruby для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  only_if { ! ::File.exist?('/etc/passwd') }
end

Следующий пример демонстрирует, как использовать условие only_if для создания файла на основе шаблона и использование строки для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  only_if 'test -f /etc/passwd'
end

Использование массива пробелов (%w)

Следующий пример демонстрирует, как использовать массив Ruby с пробелами для определения списка инструментов конфигурации, а затем использовать этот список инструментов в ресурсе template, чтобы убедиться, что все эти инструменты конфигурации используют один и тот же ключ RSA:

%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

Использование относительного пути

template "#{ENV['HOME']}/chef-getting-started.txt" do
  source 'chef-getting-started.txt.erb'
  mode '0755'
end

Задержка уведомлений

template '/etc/nagios3/configures-nagios.conf' do
  # other parameters
  notifies :run, 'execute[test-nagios-config]', :delayed
end

Немедленное уведомление

По умолчанию уведомления :delayed, то есть они помещаются в очередь по мере их возникновения, а затем выполняются в самом конце выполнения Chef Infra Client. Для немедленного выполнения действия используйте :immediately:

template '/etc/nagios3/configures-nagios.conf' do
  # other parameters
  notifies :run, 'execute[test-nagios-config]', :immediately
end

а затем Chef Infra Client немедленно выполнит следующее:

execute 'test-nagios-config' do
  command 'nagios3 --verify-config'
  action :nothing
end

Уведомление нескольких ресурсов

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

Перезагрузка службы

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  notifies :reload, 'service[apache]', :immediately
end

Перезапуск службы при изменении шаблона

template '/etc/www/configures-apache.conf' do
  notifies :restart, 'service[apache]', :immediately
end

Отправка уведомлений нескольким ресурсам

Для отправки уведомлений нескольким ресурсам просто используйте несколько атрибутов. Несколько атрибутов будут отправлены уведомлённым ресурсам в указанном порядке.

template '/etc/netatalk/netatalk.conf' do
  notifies :restart, 'service[afpd]', :immediately
  notifies :restart, 'service[cnid]', :immediately
end

service 'afpd'
service 'cnid'

Выполнение команды с использованием шаблона

Следующий пример демонстрирует, как настроить переадресацию пакетов IPv4 с помощью ресурса execute для выполнения команды с именем forward_ipv4, которая использует шаблон, определённый ресурсом template:

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

где свойство command для ресурса execute содержит команду, которая должна быть выполнена, а свойство source для ресурса template указывает, какой шаблон использовать. Свойство notifies для template указывает, что execute[forward_ipv4] (которое определено ресурсом execute) должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.

Установка IP-адреса с использованием переменных и шаблона

Следующий пример демонстрирует, как ресурс template можно использовать в рецепте для объединения настроек, хранящихся в файле атрибутов, переменных в рецепте и шаблона для установки IP-адресов, используемых службой Nginx. Файл атрибутов содержит следующее:

default['nginx']['dir'] = '/etc/nginx'

Затем рецепт выполняет следующие действия:

• Объявляет две переменные в начале рецепта, одну для удалённого IP-адреса и другую для разрешённого IP-адреса
• Использует ресурс service для перезапуска и перезагрузки службы Nginx
• Загружает шаблон с именем authorized_ip.erb из каталога /templates, который используется для установки значений IP-адресов на основе переменных, указанных в рецепте

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

где свойство variables сообщает шаблону использовать переменные, заданные в начале рецепта, а свойство source используется для вызова файла шаблона, расположенного в каталоге кулинарной книги /templates. Файл шаблона похож на:

geo $<%= @remote_ip_var %> $authorized_ip {
  default no;
  <% @authorized_ips.each do |ip| %>
  <%= "#{ip} yes;" %>
  <% end %>
}

Добавление правила в таблицу IP

Следующий пример демонстрирует, как добавить правило с именем test_rule в таблицу IP с помощью ресурса execute для выполнения команды с использованием шаблона, определённого ресурсом template:

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

где свойство command для ресурса execute содержит команду, которая должна быть выполнена, а свойство source для ресурса template указывает, какой шаблон использовать. Свойство notifies для template указывает, что execute[test_rule] (которое определено ресурсом execute) должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.

Применить настройки прокси последовательно во всей организации Chef

Следующий пример демонстрирует, как шаблон можно использовать для применения согласованных настроек прокси для всех узлов одного типа:

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

где matching_node представляет собой тип узла (например, Nginx), а site_proxy представляет собой тип прокси, используемый для этого типа узла (например, Nexus).

Получение настроек шаблона из локального файла

Ресурс шаблона можно использовать для рендеринга шаблона на основе настроек, содержащихся в локальном файле на диске, или для получения настроек из шаблона в кулинарной книге. В большинстве случаев настройки извлекаются из шаблона в кулинарной книге. Следующий пример показывает, как ресурс шаблона можно использовать для извлечения этих настроек из локального файла.

Следующий пример основан на нескольких предположениях:

• Среда — это приложение Ruby on Rails, которому требуется рендеринг файла database.yml
• Информация об приложении — пользователь, его пароль, сервер — хранится в наборе данных на сервере Chef.
• Приложение уже развернуто на системе, и единственное требование в этом примере — рендеринг файла database.yml

Дерево исходного кода приложения выглядит примерно так:

  myapp/
  -> config/
     -> database.yml.erb

Развертывание приложения закончится в /srv, поэтому полный путь к этому шаблону будет примерно таким: /srv/myapp/current/config/database.yml.erb.

Содержимое самого шаблона может выглядеть так:

<%= @rails_env %>:
   adapter: <%= @adapter %>
   host: <%= @host %>
   database: <%= @database %>
   username: <%= @username %>
   password: <%= @password %>
   encoding: 'utf8'
   reconnect: true

Рецепт будет похож на следующий:

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

где:

• метод search в языке Chef Infra используется для поиска первого узла, который является главным узлом базы данных (которых должно быть только один)
• свойство переменной :adapter также может потребовать, чтобы атрибут был задан в роли, которая затем определяет правильный адаптер

Шаблон будет рендериться примерно так:

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

Этот пример показал, как использовать ресурс шаблона для рендеринга шаблона на основе настроек, содержащихся в локальном файле. Некоторые другие вопросы, которые следует учитывать при использовании такого подхода, включают:

• Должен ли файл database.yml находиться в файле .gitignore?
• Как разработчики запускают приложение локально?
• Работает ли это с chef-solo?

Передача значений из рецепта в шаблон

Следующий пример показывает, как передать значение в шаблон, используя свойство variables в ресурсе шаблона. Файл шаблона похож на:

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

Затем рецепт использует атрибут variables, чтобы найти значения для splunk_servers и outputs_conf, прежде чем передать их в шаблон:

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

Этот пример можно найти в рецепте client.rb и файлах шаблонов outputs.conf.erb, которые находятся в кулинарной книге chef-splunk, поддерживаемой Chef.