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

Редактировать эту страницу в репозитории Chef

Страница справочника ресурсов

Шаблон кулинарной книги — это шаблон 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, sensitive, 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 для удаления Chef Infra Client целевого файла, который не является файлом, и замены его указанным файлом. Установите значение в 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', а затем применяет umask системы, на которой файл должен быть создан, к значению mask. Например, если umask в системе равен '022', Chef Infra Client использует значение по умолчанию '0755'.

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

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

Microsoft Windows: Строка с 3-5 символами в кавычках, определяющая восьмеричный режим, который преобразуется в права безопасности Microsoft Windows. Например: '755', '0755' или 00755. Разрешены значения до '0777' (без бита «sticky»), которые означают то же самое в 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 Client. Этот путь может отличаться в разных системах. Поэтому не рекомендуется использовать путь, начинающийся с косой черты (/).

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 '/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.

Эти разрешения суммируются. Если указано :write, то оно включает :read. Если указано :full_control, то оно включает как :write, так и :read.

(Для тех, кто знаком с API Microsoft Windows: :read соответствует GENERIC_READ; :write соответствует GENERIC_WRITE; :read_execute соответствует GENERIC_READ и GENERIC_EXECUTE; :modify соответствует GENERIC_WRITE, GENERIC_READ, GENERIC_EXECUTE и DELETE; :full_control соответствует GENERIC_ALL, что позволяет пользователю изменять владельца и другие метаданные файла.)

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

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

Переменные

Шаблон Embedded Ruby (ERB) позволяет встраивать код Ruby в текстовый файл в специальных тегах. Код Ruby можно встраивать с помощью выражений и инструкций. Выражение ограничено <%= и %>. Например:

<%= "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.

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

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

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 Client (converge phase).

ignore_failure

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

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

retries

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

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

retry_delay

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

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

sensitive

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

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

Уведомления

notifies

Тип Ruby: Символ, 'Chef::Resource[Строка]'

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

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

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

:before

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

:delayed

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

:immediate, :immediately

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

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

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

subscribes

Тип Ruby: Символ, 'Chef::Resource[Строка]'

Ресурс может следить за другим ресурсом и выполнять действия, если состояние отслеживаемого ресурса изменится. Укажите '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-адрес с использованием переменных и шаблона

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

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

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

• Объявляет две переменные в начале рецепта: одну для удаленного IP-адреса и другую для разрешенного IP-адреса
• Использует ресурс служба для перезапуска и перегрузки службы 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 '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 для ресурса выполнение содержит команду, которая должна быть выполнена, а свойство source для ресурса шаблон указывает, какой шаблон использовать. Свойство notifies для шаблона указывает, что execute[test_rule] (которое определяется ресурсом выполнение) должно быть помещено в очередь и выполнено в конце выполнения Клиента Chef Infra.

Применение настроек прокси последовательно по всей организации 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 в DSL-рецепте используется для поиска первого узла, являющегося главным узлом базы данных (должен быть только один)
• свойство переменной :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.