О обработчиках

[редактировать на GitHub]

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

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

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

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

Запуск из client.rb

Простой обработчик исключений или отчетов может быть установлен и настроен во время выполнения. Это требует редактирования файла client.rb узла для добавления соответствующей настройки и информации об этом обработчике в файлы client.rb или solo.rb. В зависимости от типа обработчика необходимо добавить одну (или несколько) из следующих настроек:

При использовании этого подхода файл client.rb также должен сообщить Chef Infra Client, как установить и запустить обработчик. Нет стандартного места установки обработчиков. Самый простой способ их распространения и установки — через RubyGems, хотя также подойдут и другие методы, такие как GitHub или HTTP. После установки обработчика на систему его необходимо включить в файле client.rb, подключив его. После установки обработчик может потребовать дополнительной настройки. Это будет зависеть от обработчика. Если обработчик очень простой, может потребоваться только создание нового экземпляра. Например, если обработчик под названием MyOrg::EmailMe жестко закодирован для всех значений, необходимых для отправки электронного письма, требуется новый экземпляр. А затем пользовательский обработчик должен быть связан с каждым типом обработчика, для которого он будет работать.

Например:

require '/var/chef/handlers/email_me'         # the installation path

email_handler = MyOrg::EmailMe.new            # a simple handler

start_handlers << email_handler               # run at the start of the run
report_handlers << email_handler              # run at the end of a successful run
exception_handlers << email_handler           # run at the end of a failed run

Обработчики запуска

Обработчик запуска не загружается в выполнение 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'

Запуск из client.rb

Обработчик запуска можно настроить в файле client.rb, добавив следующую настройку:

Например, обработчик запуска отчетов добавляет следующий код в начало файла client.rb:

begin
  require 'chef_reporting'
  start_handlers << Chef::Reporting::StartHandler.new()
rescue LoadError
  Chef::Log.warn 'Failed to load #{lib}. This should be resolved after a chef run.'
end

Это гарантирует, что при запуске выполнения Chef Infra Client обработчик событий chef_reporting включен. Обработчик событий chef_reporting является частью gem под названием chef-reporting. Для установки этого gem используется ресурс chef_gem:

chef_gem 'chef-reporting' do
  action :install
end

Обработчики событий

Используйте DSL обработчика для добавления обратного вызова к событию. Если событие происходит во время выполнения Chef Infra Client, связанный обратный вызов выполняется. Например:

• Отправка электронного письма, если выполнение Chef Infra Client завершается сбоем
• Агрегирование статистики о ресурсах, обновленных во время выполнения Chef Infra Client, в StatsD

Метод on

Используйте метод on для связывания типа события с обратным вызовом. Обратный вызов определяет шаги, выполняемые, если событие происходит во время выполнения Chef Infra Client, и определяется произвольным кодом Ruby. Синтаксис следующий:

Chef.event_handler do
  on :event_type do
    # some Ruby
  end
end

где

• Chef.event_handler объявляет блок кода в рецепте, который обрабатывается при возникновении указанного события во время выполнения Chef Infra Client
• on определяет блок кода, который укажет Chef Infra Client, как обработать событие
• :event_type — это допустимый тип события исключения, например :run_start, :run_failed, :converge_failed, :resource_failed, или :recipe_not_found

Например:

Chef.event_handler do
  on :converge_start do
    puts "Ohai! I have started a converge."
  end
end

Типы событий

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

Примеры

В следующих примерах показаны способы использования DSL обработчика.

Отправка электронной почты

Используйте метод on для создания обработчика событий, который отправляет электронное письмо при сбое выполнения Chef Infra Client. Для этого потребуется:

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

Настройка отправки электронной почты

Используйте библиотеку для определения кода, который отправляет электронное письмо при сбое выполнения Chef Infra Client. Назовите файл helper.rb и добавьте его в каталог /libraries кулинарной книги:

require 'net/smtp'

module HandlerSendEmail
  class Helper
    def send_email_on_run_failure(node_name)
      message = "From: Chef <chef@chef.io>\n"
      message << "To: Grant <grantmc@chef.io>\n"
      message << "Subject: Chef run failed\n"
      message << "Date: #{Time.now.rfc2822}\n\n"
      message << "Chef run failed on #{node_name}\n"
      Net::SMTP.start('localhost', 25) do |smtp|
        smtp.send_message message, 'chef@chef.io', 'grantmc@chef.io'
      end
    end
  end
end

Добавление обработчика

Вызовите вспомогательную функцию библиотеки в рецепте:

Chef.event_handler do
  on :run_failed do
    HandlerSendEmail::Helper.new.send_email_on_run_failure(
      Chef.run_context.node.name
    )
  end
end

• Используйте Chef.event_handler для определения обработчика событий
• Используйте метод on для указания типа события

Внутри блока on, укажите Chef Infra Client, как обрабатывать событие при его срабатывании.

Тестирование обработчика

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

ruby_block 'fail the run' do
  block do
    raise 'deliberately fail the run'
  end
end

Блокировки etcd

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

lock_key = "#{node.chef_environment}/#{node.name}"

Chef.event_handler do
  on :converge_start do |run_context|
    Etcd.lock_acquire(lock_key)
  end
end

Chef.event_handler do
  on :converge_complete do
    Etcd.lock_release(lock_key)
  end
end

Уведомления HipChat

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

Chef.event_handler do
  on :run_failed do |exception|
    hipchat_notify exception.message
  end
end

или отправьте оповещение при изменении конфигурации:

Chef.event_handler do
  on :resource_updated do |resource, action|
    if resource.to_s == 'template[/etc/nginx/nginx.conf]'
      Helper.hipchat_message("#{resource} was updated by chef")
    end
  end
end

Обработчики и кулинарии

Следующие кулинарии могут быть использованы для загрузки обработчиков во время выполнения Chef InfraClient.

chef_handler

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

Для получения дополнительной информации см. документацию по ресурсу chef_handler Resource.

Chef Infra Client

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

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

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

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 Client доступна для обработчика
• ModuleName — имя модуля в библиотеке Chef
• HandlerName — имя обработчика, используемого в рецепте
• report — интерфейс, используемый для определения пользовательского обработчика

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

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 следующий:

def report
  # Ruby code
end

Ruby-код, используемый для определения пользовательского обработчика, будет сильно отличаться в зависимости от обработчика. Chef Infra Client включает два обработчика по умолчанию: 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

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

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

data

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

def data
  @run_status.to_hash
end

run_report_safely

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

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 Client перед запуском интерфейса report для любого обработчика. Объект run_status отслеживает состояние запуска Chef Infra Client и будет содержать некоторые (или все) из следующих свойств:

Примеры

В следующих разделах представлены примеры обработчиков.

Версии кулинарий

Пользователь сообщества juliandunn создал пользовательский обработчик отчетов, который регистрирует все кулинарии и версии кулинарий, которые были использованы во время запуска Chef Infra Client, а затем отчитывается после завершения запуска. Этот обработчик требует ресурса chef_handler (который доступен из кулинарии chef_handler).

cookbook_versions.rb

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

require 'chef/log'

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

default.rb

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

include_recipe 'chef_handler'

cookbook_file "#{node['chef_handler']['handler_path']}/cookbook_versions.rb" do
  source 'cookbook_versions.rb'
  owner 'root'
  group 'root'
  mode '0755'
  action :create
end

chef_handler 'Opscode::CookbookVersionsHandler' do
  source "#{node['chef_handler']['handler_path']}/cookbook_versions.rb"
  supports :report => true
  action :enable
end

Этот рецепт сгенерирует вывод отчёта, подобный следующему:

[2013-11-26T03:11:06+00:00] INFO: Chef 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: ["chef_handler 1.1.4", "cookbook_versions_handler 1.0.0"]
[2013-11-26T03:11:06+00:00] INFO: Report handlers complete

Отчётность

Функциональность обработчика запуска была добавлена, когда Chef начал создавать дополнения для Chef Infra Server. Дополнение Отчётность предназначено для создания отчётных данных на основе запуска Chef Infra Client. Поскольку Отчётность должна собирать данные для всего запуска Chef Infra Client, Отчётность должна быть включена до того, как произойдёт что-либо ещё в начале запуска Chef Infra Client.

start_handler.rb

Следующий код демонстрирует обработчик запуска, используемый дополнением Отчётность для Chef Infra Server:

require 'chef/handler'
require 'chef/rest'
require 'chef/version_constraint'

class Chef
  class Reporting
    class StartHandler < ::Chef::Handler
      attr_reader :config

      def initialize(config = {})
        @config = config
      end

      def report
        version_checker = Chef::VersionConstraint.new('< 11.6.0')
        if version_checker.include?(Chef::VERSION)
          Chef::Log.info('Enabling backported resource reporting Handler')
          rest = Chef::REST.new(Chef::Config[:chef_server_url], @run_status.node.name, Chef::Config[:client_key])
          resource_reporter = Chef::Reporting::ResourceReporter.new(rest)
          @run_status.events.register(resource_reporter)

          resource_reporter.run_started(@run_status)
        else
          Chef::Log.debug('Chef Version already has new Resource Reporter - skipping startup of backport version')
        end
      end
    end
  end
end

Обработчик json_file

Обработчик json_file доступен из кулинарии 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

Обработчик error_report

Обработчик error_report встроен в 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

Обработчики сообщества

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