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

[править на 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, добавив следующую настройку:

Например, обработчик Reporting запуска добавляет следующий код в начало файла 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 Infra Client.

chef_handler

Обработчики исключений и отчетов могут быть распространены с помощью кулинарной книги chef_handler. Эта кулинарная книга написана и поддерживается Chef и предоставляет пользовательский ресурс, который может использоваться для включения пользовательских обработчиков из рецептов и для включения обработчиков, специфичных для продукта, из кулинарных книг. Кулинарную книгу chef_handler можно получить здесь: https://github.com/chef-cookbooks/chef_handler. См. README.md для дополнительной информации.

Клиент Chef Infra

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

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

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

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 перед выполнением интерфейса 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: