Ресурс chef_handler

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

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

Используйте ресурс 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 можно настроить для автоматической установки и настройки драгоценных камней, необходимых обработчику запуска. Например:

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
  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-client на текущем узле.

:enable

Включить обработчик для текущего выполнения chef-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: Строка

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

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

Уведомления

notifies

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

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

:before

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

:delayed

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

:immediate, :immediately

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

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

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

Фильтры

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

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

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

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

not_if

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

only_if

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

Пользовательские обработчики

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

1. Загрузите кулинарную книгу chef_handler
2. Создайте пользовательский обработчик
3. Напишите рецепт, используя ресурс chef_handler
4. Добавьте этот рецепт в список выполнения узла, часто в качестве первого рецепта в этом списке

Синтаксис

Синтаксис обработчика может различаться в зависимости от ситуации, которую обработчик должен отслеживать, типа используемого обработчика и т. д. Все пользовательские обработчики исключений и отчетов определяются с использованием Ruby и должны быть подклассом класса Chef::Handler.

require 'chef/log'

module ModuleName
  class HandlerName < Chef::Handler
    def report
      # Ruby code goes here
    end
  end
end

где:

• require гарантирует, что функциональность ведения журнала Клиента Chef Infra доступна обработчику
• ModuleName — имя модуля, как оно существует в библиотеке Chef
• HandlerName — имя обработчика, как оно используется в рецепте
• report — интерфейс, используемый для определения пользовательского обработчика

Например, ниже показан пользовательский обработчик, который отправляет электронное письмо, содержащее данные исключения, когда выполнение Клиента Chef Infra завершается неудачей:

require 'net/smtp'

module OrgName
  class SendEmail < Chef::Handler
    def report
      if run_status.failed?
        message = "From: sender_name <sender@example.com>\n"
        message << "To: recipient_address <recipient@example.com>\n"
        message << "Subject: chef-client Run Failed\n"
        message << "Date: #{Time.now.rfc2822}\n\n"
        message << "Chef run failed on #{node.name}\n"
        message << "#{run_status.formatted_exception}\n"
        message << Array(backtrace).join('\n')
        Net::SMTP.start('your.smtp.server', 25) do |smtp|
          smtp.send_message message, 'sender@example', 'recipient@example'
        end
      end
    end
  end
end

а затем используется в рецепте, как:

send_email 'blah' do
  # recipe code
end

Интерфейс report

Интерфейс report используется для определения поведения обработчика и является обязательной частью любого пользовательского обработчика. Синтаксис интерфейса report следующий:

def report
  # Ruby code
end

Код Ruby, используемый для определения пользовательского обработчика, будет сильно различаться в зависимости от обработчика. Клиент Chef Infra включает два обработчика по умолчанию: error_report и json_file. Их использование интерфейса report показано ниже.

Обработчик error_report:

require 'chef/handler'
require 'chef/resource/directory'

class Chef
  class Handler
    class ErrorReport < ::Chef::Handler
      def report
        Chef::FileCache.store('failed-run-data.json', Chef::JSONCompat.to_json_pretty(data), 0640)
        Chef::Log.fatal("Saving node information to #{Chef::FileCache.load('failed-run-data.json', false)}")
      end
    end
  end
end

Обработчик json_file:

require 'chef/handler'
require 'chef/resource/directory'

class Chef
  class Handler
    class JsonFile < ::Chef::Handler
      attr_reader :config
      def initialize(config = {})
        @config = config
        @config[:path] ||= '/var/chef/reports'
        @config
      end

      def report
        if exception
          Chef::Log.error('Creating JSON exception report')
        else
          Chef::Log.info('Creating JSON run report')
        end
        build_report_dir
        savetime = Time.now.strftime('%Y%m%d%H%M%S')
        File.open(File.join(config[:path], 'chef-run-report-#{savetime}.json'), 'w') do |file|
          run_data = data
          run_data[:start_time] = run_data[:start_time].to_s
          run_data[:end_time] = run_data[:end_time].to_s
          file.puts Chef::JSONCompat.to_json_pretty(run_data)
        end
      end

      def build_report_dir
        unless File.exist?(config[:path])
          FileUtils.mkdir_p(config[:path])
          File.chmod(00700, config[:path])
        end
      end
    end
  end
end

Дополнительные интерфейсы

data

Метод data используется для возвращения представления Hash объекта run_status. Например:

def data
  @run_status.to_hash
end

run_report_safely

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

def run_report_safely(run_status)
  run_report_unsafe(run_status)
rescue Exception => e
  Chef::Log.error('Report handler #{self.class.name} raised #{e.inspect}')
  Array(e.backtrace).each { |line| Chef::Log.error(line) }
ensure
  @run_status = nil
end

run_report_unsafe

Метод run_report_unsafe используется для запуска обработчика отчета без обработки ошибок. Этот метод никогда не должен использоваться напрямую ни в каком обработчике, кроме как во время тестирования этого обработчика. Например:

def run_report_unsafe(run_status)
  @run_status = run_status
  report
end

Объект run_status

Объект run_status инициализируется Клиентом Chef Infra перед запуском интерфейса report для любого обработчика. Объект run_status отслеживает состояние выполнения Клиента Chef Infra и будет содержать некоторые (или все) из следующих свойств:

Примеры

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

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

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

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

После выполнения данные о состоянии выполнения можно загрузить и просмотреть с помощью интерактивного 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