Ресурс chef_handler

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

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

Используйте ресурс chef_handler для включения обработчиков во время выполнения Chef Infra Client. Ресурс позволяет передавать аргументы в Chef Infra Client, который затем применяет условия, определённые пользовательским обработчиком, к данным атрибутов узла, собранным во время выполнения Chef Infra Client, а затем обрабатывает обработчик на основе этих данных. Ресурс chef_handler обычно определяется в начале списка выполнения узла (часто как первый элемент). Это гарантирует, что все обработчики будут доступны на протяжении всего выполнения Chef Infra Client.

Новое в Chef Infra Client 14.0.

Типы обработчиков

Существует три типа обработчиков:

Исключение/Отчёт

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

• Обработчик исключений используется для запуска поведения при сбое определённого аспекта выполнения Chef Infra Client.
• Обработчик отчётов используется для запуска поведения при успешном выполнении определённого аспекта выполнения Chef Infra Client.

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

Обработчики исключений и отчётов делаются доступными для выполнения Chef Infra Client одним из следующих способов:

• Добавив ресурс chef_handler в рецепт, а затем добавив этот рецепт в список выполнения для узла. (Ресурс chef_handler доступен из кулинарной книги chef_handler.)
• Добавив обработчик в одну из следующих настроек файла client.rb узла: exception_handlers и/или report_handlers

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

Чтобы использовать ресурс chef_handler в рецепте, добавьте код, похожий на следующий:

chef_handler 'name_of_handler' do
  source '/path/to/handler/handler_name'
  action :enable
end

Например, обработчик Growl должен быть включён в начале выполнения Chef Infra Client:

chef_gem 'chef-handler-growl'

а затем активируется в рецепте с помощью ресурса chef_handler:

chef_handler 'Chef::Handler::Growl' do
  source 'chef/handler/growl'
  action :enable
end

Запуск

Обработчик запуска не загружается в выполнение Chef Infra Client из рецепта, а вместо этого перечисляется в файле client.rb с помощью атрибута start_handlers. Обработчик запуска должен быть установлен на узле и доступен для Chef Infra Client до начала выполнения Chef Infra Client. Используйте кулинарную книгу chef-client для установки обработчика запуска.

Обработчики запуска делаются доступными для выполнения Chef Infra Client одним из следующих способов:

• Добавив обработчик запуска в кулинарную книгу chef-client, которая устанавливает обработчик на узел, чтобы он был доступен Chef Infra Client в начале выполнения Chef Infra Client
• Добавив обработчик в одну из следующих настроек файла client.rb узла: start_handlers

Кулинарная книга chef-client может быть настроена на автоматическую установку и настройку gem, необходимых для обработчика запуска. Например:

node.override['chef_client']['load_gems']['chef-reporting'] = {
  require_name: 'chef_reporting',
  action: :install,
}

node.override['chef_client']['config']['start_handlers'] = [
  {
    class: 'Chef::Reporting::StartHandler',
    arguments: [],
  },
]

include_recipe 'chef-client::config'

Синтаксис

Блок ресурса chef_handler включает обработчики во время выполнения chef-client. Два обработчика—JsonFile и ErrorReport—встроены в Chef:

chef_handler 'Chef::Handler::JsonFile' do
  source 'chef/handler/json_file'
  arguments :path => '/var/chef/reports'
  action :enable
end

и:

chef_handler 'Chef::Handler::ErrorReport' do
  source 'chef/handler/error_report'
  action :enable
end

показывают, как включить эти обработчики в рецепте.

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

chef_handler 'name' do
  arguments       Array, Hash # default value: []
  class_name      String # default value: 'name' unless specified
  source          String
  type            Hash # default value: {"report"=>true, "exception"=>true}
  action          Symbol # defaults to :enable if not specified
end

где:

• chef_handler — это ресурс.
• name — это имя, присвоенное блоку ресурса.
• action определяет шаги, которые Chef Infra Client предпримет для приведения узла в нужное состояние.
• arguments, class_name, source, и type — это свойства, доступные для этого ресурса.

Действия

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

:disable

Отключает обработчик для текущего выполнения Chef Infra Client на текущем узле.

:enable

Включает обработчик для текущего выполнения Chef Infra Client на текущем узле. (по умолчанию)

:nothing

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

Свойства

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

arguments

Тип Ruby: Массив, Хэш | Значение по умолчанию: []

Массив аргументов, передаваемых в инициализатор класса обработчика. Например:

arguments :key1 => 'val1'

или:

arguments [:key1 => 'val1', :key2 => 'val2']

class_name

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

Имя класса обработчика. Может быть с пространством имён модуля.

source

Тип Ruby: Строка

Полный путь к файлу обработчика. Также может быть путём gem, если обработчик поставляется в составе Ruby gem.

type

Тип Ruby: Хэш | Значение по умолчанию: {"report"=>true, "exception"=>true}

Тип регистрируемого обработчика, например :report, :exception или оба.

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

Ресурсы 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 Infra Client.

Уведомления

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

Примеры

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

Включить обработчик ‘MyHandler’

Следующий пример показывает, как включить вымышленный обработчик ‘MyHandler’, который расположен на диске по адресу /etc/chef/my_handler.rb. Обработчик будет настроен на работу с Chef Infra Client и получит значения для метода инициализации обработчика:

chef_handler 'MyHandler' do
  source '/etc/chef/my_handler.rb' # the file should already be at this path
  arguments path: '/var/chef/reports'
  action :enable
end

Включение обработчиков во время фазы компиляции

chef_handler 'Chef::Handler::JsonFile' do
  source 'chef/handler/json_file'
  arguments path: '/var/chef/reports'
  action :enable
  compile_time true
end

Обработка только исключений

chef_handler 'Chef::Handler::JsonFile' do
  source 'chef/handler/json_file'
  arguments path: '/var/chef/reports'
  type exception: true
  action :enable
end

Версии кулинарных книг (пользовательский обработчик)

@juliandunn создал пользовательский обработчик отчетов, который регистрирует все кулинарные книги и версии кулинарных книг, которые использовались во время выполнения Chef Infra Client, а затем выводит отчет после завершения выполнения.

cookbook_versions.rb:

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

require 'chef/log'

module Chef
  class CookbookVersionsHandler < Chef::Handler
    def report
      cookbooks = run_context.cookbook_collection
      Chef::Log.info('Cookbooks and versions run: #{cookbooks.map {|x| x.name.to_s + ' ' + x.version }}')
    end
  end
end

default.rb:

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

cookbook_file '/etc/chef/cookbook_versions.rb' do
  source 'cookbook_versions.rb'
  action :create
end

chef_handler 'Chef::CookbookVersionsHandler' do
  source '/etc/chef/cookbook_versions.rb'
  type report: true
  action :enable
end

Этот рецепт сгенерирует отчет, похожий на следующий:

[2013-11-26T03:11:06+00:00] INFO: Chef Infra Client Run complete in 0.300029878 seconds
[2013-11-26T03:11:06+00:00] INFO: Running report handlers
[2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["cookbook_versions_handler 1.0.0"]
[2013-11-26T03:11:06+00:00] INFO: Report handlers complete

Обработчик JsonFile

Обработчик JsonFile доступен из кулинарной книги chef_handler и может использоваться с исключениями и отчетами. Он сериализует данные состояния выполнения в файл JSON. Этот обработчик можно включить следующими способами.

Добавив следующие строки кода Ruby в файл client.rb или solo.rb, в зависимости от способа запуска Chef Infra Client:

require 'chef/handler/json_file'
report_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
exception_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')

Используя ресурс chef_handler в рецепте, аналогично следующему:

chef_handler 'Chef::Handler::JsonFile' do
  source 'chef/handler/json_file'
  arguments path: '/var/chef/reports'
  action :enable
end

После выполнения данные состояния выполнения можно загрузить и просмотреть с помощью Interactive Ruby (IRb):

irb(main):002:0> require 'json' => true
irb(main):003:0> require 'chef' => true
irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated
irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace']
irb(main):006:0> r['elapsed_time'] => 0.00246

Зарегистрировать обработчик JsonFile

chef_handler 'Chef::Handler::JsonFile' do
  source 'chef/handler/json_file'
  arguments path: '/var/chef/reports'
  action :enable
end

Обработчик ErrorReport

Обработчик ErrorReport встроен в Chef Infra Client и может использоваться как для исключений, так и для отчетов. Он сериализует данные отчёта об ошибках в файл JSON. Этот обработчик можно включить следующими способами.

Добавив следующие строки кода Ruby в файл client.rb или solo.rb, в зависимости от способа запуска Chef Infra Client:

require 'chef/handler/error_report'
report_handlers << Chef::Handler::ErrorReport.new
exception_handlers << Chef::Handler::ErrorReport.new

Используя ресурс chef_handler в рецепте, аналогично следующему:

chef_handler 'Chef::Handler::ErrorReport' do
  source 'chef/handler/error_report'
  action :enable
end