Все ресурсы инфраструктуры

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

Общие возможности

Свойства и действия в этом разделе применяются ко всем ресурсам.

Действия

Следующие действия могут использоваться с любым ресурсом:

:nothing

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

Примеры

Следующие примеры показывают, как использовать общие действия в рецепте.

Используйте действие :nothing

service 'memcached' do
  action :nothing
end

Свойства

Следующие свойства являются общими для каждого ресурса:

ignore_failure

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

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

retries

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

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

retry_delay

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

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

sensitive

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

Убедиться, что чувствительные данные ресурса не регистрируются Chef Infra Client.

Примеры

Следующие примеры показывают, как использовать общие свойства в рецепте.

Используйте общее свойство ignore_failure

gem_package 'syntax' do
  action :install
  ignore_failure true
end

Используйте общие свойства retries и retry_delay

service 'apache' do
  action [ :enable, :start ]
  retries 3
  retry_delay 5
end

Ограничения

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

Аргументы

Следующие аргументы могут использоваться со свойствами ограничения not_if или only_if:

:user

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

not_if 'grep adam /etc/passwd', user: 'adam'

:group

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

not_if 'grep adam /etc/passwd', group: 'adam'

:environment

Укажите хеш переменных среды, которые нужно установить. Например:

not_if 'grep adam /etc/passwd', environment: {
  'HOME' => '/home/adam',
}

:cwd

Установите текущий рабочий каталог перед запуском команды. Например:

not_if 'grep adam passwd', cwd: '/etc'

:timeout

Установите таймаут для команды. Например:

not_if 'sleep 10000', timeout: 10

Примеры not_if

Следующие примеры показывают, как использовать not_if в качестве условия в рецепте:

Создать файл, но не если атрибут имеет определенное значение

Следующий пример показывает, как использовать условие not_if для создания файла на основе шаблона и использования наличия значения атрибута на узле для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if { node['some_value'] }
end

Создать файл с блоком Ruby, но не если “/etc/passwd” существует

Следующий пример показывает, как использовать условие not_if для создания файла на основе шаблона и затем код Ruby для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if do
    ::File.exist?('/etc/passwd')
  end
end

Создать файл с блоком Ruby, содержащим фигурные скобки, но не если “/etc/passwd” существует

Следующий пример показывает, как использовать условие not_if для создания файла на основе шаблона и использования блока Ruby (с фигурными скобками) для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  not_if { ::File.exist?('/etc/passwd') }
end

Создать файл, используя строку, но не если “/etc/passwd” существует

Следующий пример показывает, как использовать условие not_if для создания файла на основе шаблона и использования строки для указания условия:

template '/etc/some_config' do
  mode '0640'
  source 'some_config.erb'
  not_if 'some_app --check-config'
end

Примеры only_if

Следующие примеры показывают, как использовать only_if в качестве условия в рецепте:

Создать файл, только если атрибут имеет определенное значение

Следующий пример показывает, как использовать условие only_if для создания файла на основе шаблона и использования наличия атрибута на узле для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  only_if { node['some_value'] }
end

Создать файл с блоком Ruby, только если “/etc/passwd” не существует

Следующий пример показывает, как использовать условие only_if для создания файла на основе шаблона, а затем использовать Ruby для указания условия:

template '/etc/some_app/some_config' do
  mode '0640'
  source 'some_config.erb'
  only_if { ::File.exist?('/etc/some_app/') }
end

Создать файл, используя строку, только если “/etc/passwd” существует

Следующий пример показывает, как использовать условие only_if для создания файла на основе шаблона и использования строки для указания условия:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
  only_if 'test -f /etc/passwd'
end

Интерпретаторы ограничений

Любой ресурс, который передает строковую команду, также может указать интерпретатор, который будет использоваться для оценки этой строковой команды. Это делается с помощью свойства guard_interpreter для указания ресурса на основе script.

Атрибуты

Свойство guard_interpreter может быть установлено на любое из следующих значений:

:bash

Оценивает строковую команду, используя ресурс bash.

:batch

Оценивает строковую команду, используя ресурс batch. Значение по умолчанию (внутри блока ресурса batch): :batch.

:csh

Оценивает строковую команду, используя ресурс csh.

:default

Значение по умолчанию. Выполняет интерпретатор по умолчанию, определенный Chef Infra Client.

:perl

Оценивает строковую команду, используя ресурс perl.

:powershell_script

Оценивает строковую команду, используя ресурс powershell_script. Значение по умолчанию (внутри блока ресурса powershell_script): :powershell_script.

:python

Оценивает строковую команду, используя ресурс python.

:ruby

Оценивает строковую команду, используя ресурс ruby.

Наследование

Свойство guard_interpreter по умолчанию установлено в значение :default для ресурсов bash, csh, perl, python и ruby. Когда свойство guard_interpreter установлено в значение :default, not_if или only_if, операторы ограничений не наследуют свойства, которые определены ресурсом на основе script.

Например, оператор ограничения not_if в следующем примере ресурса не наследует свойство environment:

bash 'javatooling' do
  environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
  code 'java-based-daemon-ctl.sh -start'
  not_if 'java-based-daemon-ctl.sh -test-started'
end

и требует добавления свойства environment к оператору ограничения not_if, чтобы он мог использовать путь JAVA_HOME в рамках своей оценки:

bash 'javatooling' do
  environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
  code 'java-based-daemon-ctl.sh -start'
  not_if 'java-based-daemon-ctl.sh -test-started', :environment => 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
end

Для наследования свойств добавьте свойство guard_interpreter в блок ресурса и установите его в соответствующее значение:

• :bash для bash
• :csh для csh
• :perl для perl
• :python для python
• :ruby для ruby

Например, используя тот же пример, что и выше, но на этот раз добавив свойство guard_interpreter и установив его в значение :bash:

bash 'javatooling' do
  guard_interpreter :bash
  environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
  code 'java-based-daemon-ctl.sh -start'
  not_if 'java-based-daemon-ctl.sh -test-started'
end

Оператор not_if теперь наследует свойство environment и будет использовать путь JAVA_HOME в рамках своей оценки.

Примеры

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

resource 'name' do
  guard_interpreter :default
  # code
end

Ленивая оценка

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

property_name lazy { code_block }

где lazy используется для того, чтобы указать Chef Infra Client на вычисление содержимого блока кода позже в процессе оценки ресурса (а не немедленно), и { code_block } — произвольный Ruby-код, который предоставляет значение.

Например, ресурс, который не использует ленивую вычисление:

template 'template_name' do
  # some properties
  path '/foo/bar'
end

и блок ресурса, использующий ленивую вычисление:

template 'template_name' do
  # some properties
  path lazy { ' some Ruby code ' }
end

В предыдущих примерах первый ресурс использует значение /foo/bar, а второй — значение, предоставленное блоком кода, при условии, что содержимое этого блока кода является допустимым свойством ресурса.

Следующий пример показывает, как использовать ленивую вычисление с переменными шаблонов:

template '/tmp/canvey_island.txt' do
  source 'canvey_island.txt.erb'
  variables(
    lazy do
      { canvey_island: node.run_state['sea_power'] }
    end
  )
end

Уведомления

Уведомление — это свойство ресурса, которое следит за другими ресурсами в коллекции ресурсов и выполняет действия на основе типа уведомления (notifies или subscribes).

Таймеры

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

:before

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

:delayed

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

:immediate, :immediately

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

Уведомления

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

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

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

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

Примеры

В следующих примерах показано, как использовать уведомление notifies в рецепте.

Задержка уведомлений

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-elasticsearch]', :delayed
  notifies :restart, 'service[chef-server]', :delayed
end

Уведомление в определённом порядке

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

execute 'foo' do
  command '...'
  notifies :create, 'template[baz]', :immediately
  notifies :install, 'package[bar]', :immediately
  notifies :run, 'execute[final]', :immediately
end

template 'baz' do
  ...
  notifies :run, 'execute[restart_baz]', :immediately
end

package 'bar'

execute 'restart_baz'

execute 'final' do
  command '...'
end

где порядок будет совпадать с порядком перечисления ресурсов в рецепте: execute 'foo', template 'baz', execute [restart_baz], package 'bar' и execute 'final'.

Перезагрузка службы

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.

Перезапуск службы и затем уведомление другой службы

Следующий пример показывает, как запустить службу с именем example_service и немедленно уведомить службу Nginx о перезапуске.

service 'example_service' do
  action :start
  notifies :restart, 'service[nginx]', :immediately
end

Перезапуск одной службы перед перезапуском другой

В этом примере уведомление :before используется для перезапуска службы php-fpm перед перезапуском службы nginx:

service 'nginx' do
  action :restart
  notifies :restart, 'service[php-fpm]', :before
end

С уведомлением :before действие, указанное для ресурса nginx, не будет выполнено до тех пор, пока не будет выполнено действие с уведомлённым ресурсом (php-fpm).

Уведомление при изменении удалённого источника

remote_file '/tmp/couch.png' do
  source 'http://couchdb.apache.org/img/sketch.png'
  action :nothing
end

http_request 'HEAD http://couchdb.apache.org/img/sketch.png' do
  message ''
  url 'http://couchdb.apache.org/img/sketch.png'
  action :head
  if ::File.exist?('/tmp/couch.png')
    headers 'If-Modified-Since' => File.mtime('/tmp/couch.png').httpdate
  end
  notifies :create, 'remote_file[/tmp/couch.png]', :immediately
end

Подписки

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

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

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

Примеры

В следующих примерах показано, как использовать уведомление subscribes в рецепте.

Предотвращение перезапуска и переконфигурации при нарушении конфигурации

Используйте действие :nothing (общее для всех ресурсов) для предотвращения автоматического запуска теста, а затем используйте уведомление subscribes для выполнения теста конфигурации при обнаружении изменений в шаблоне:

execute 'test-nagios-config' do
  command 'nagios3 --verify-config'
  action :nothing
  subscribes :run, 'template[/etc/nagios3/configures-nagios.conf]', :immediately
end

Перезагрузка службы с помощью шаблона

Для перезагрузки службы, основанной на шаблоне, используйте ресурсы template и service вместе в одном рецепте, подобно следующему:

template '/tmp/somefile' do
  mode '0755'
  source 'somefile.erb'
end

service 'apache' do
  action :enable
  subscribes :reload, 'template[/tmp/somefile]', :immediately
end

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

Хранение файла в пакете данных

Следующий пример показывает, как использовать ресурс ruby_block для хранения файла BitTorrent в пакете данных, чтобы он мог быть распределён по узлам организации.

# the following code sample comes from the ``seed`` recipe
# in the following cookbook: https://github.com/mattray/bittorrent-cookbook

ruby_block 'share the torrent file' do
  block do
    f = File.open(node['bittorrent']['torrent'], 'rb')
    #read the .torrent file and base64 encode it
    enc = Base64.encode64(f.read)
    data = {
      'id' => bittorrent_item_id(node['bittorrent']['file']),
      'seed' => node['ipaddress'],
      'torrent' => enc,
    }
    item = Chef::DataBagItem.new
    item.data_bag('bittorrent')
    item.raw_data = data
    item.save
  end
  action :nothing
  subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
end

Относительные пути

Следующие относительные пути могут быть использованы с любым ресурсом:

#{ENV['HOME']}

Используйте для получения пути ~ в Linux и macOS или %HOMEPATH% в Microsoft Windows.

Примеры

template "#{ENV['HOME']}/chef-getting-started.txt" do
  source 'chef-getting-started.txt.erb'
  mode '0755'
end

Выполнение в фазе компиляции

Chef Infra Client обрабатывает рецепты в двух фазах:

1. Сначала каждый ресурс в объекте узла идентифицируется, и создаётся коллекция ресурсов. Все рецепты загружаются в определённом порядке, а затем идентифицируются действия, указанные в каждом из них. Это также называется «фазой компиляции».
2. Затем Chef Infra Client настраивает систему в соответствии с порядком ресурсов в коллекции ресурсов. Каждый ресурс проверяет узел и выполняет необходимые шаги для завершения действия. Это также называется «фазой выполнения».

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

run_action

Используйте .run_action(:some_action) в конце блока ресурса для выполнения указанного действия во время фазы компиляции. Например:

build_essential 'Install compilers' do
  action :nothing
end.run_action(:install)

где action установлено в :nothing, чтобы гарантировать, что run_action выполняется во время фазы компиляции, а не позже во время фазы выполнения.

Это можно упростить, используя флаг compile_time в Chef Infra Client 16 и более поздних версиях:

build_essential 'Install compilers' do
  compile_time true
end

Этот флаг одновременно заставляет ресурс выполняться во время компиляции и устанавливает действие слияния в :nothing.

В следующих примерах показано, когда (и когда не) использовать run_action.

Использование пользовательских ресурсов предпочтительнее принудительного выполнения во время компиляции

Выполнение во время компиляции часто используется для установки gem перед их использованием в коде рецепта.

Это плохая практика, поскольку gem могут зависеть от других gem, которые могут потребовать установки компиляторов во время компиляции.

build_essential 'Install compilers' do
  compile_time true
end

chef_gem 'aws-dsk' do
  compile_time true
end

require 'aws-sdk'

Лучшая стратегия — перемещение кода, требующего gem, в пользовательский ресурс. Поскольку все действия пользовательских ресурсов выполняются во время схождения, это откладывает необходимость в gem до более позднего этапа выполнения Chef Infra Client. Режим унификации также может быть использован в ресурсе для полного устранения проблем со сборкой/схождением:

unified_mode true

action :run do
  build_essential 'Install compilers'

  chef_gem 'aws-sdk'

  require 'aws-sdk'
end

Загрузка и парсинг файла конфигурации

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

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

Для загрузки и парсинга JSON-файла и его рендеринга в шаблоне логично загружать файл во время компиляции:

  # the remote_file is being downloaded to a temporary file
  remote_file "#{Chef::Config[:file_cache_path]}/users.json" do
    source "https://jsonplaceholder.typicode.com/users"
    compile_time true
  end

  # this parsing needs to happen after the remote_file is downloaded, but will
  # be executed at compile time.
  array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json")

  # the `array.last["phone"]` expression here will also be evaluated at compile
  # time and must be lazied via wrapping the expresssion in `lazy {}`
  file "/tmp/phone_number.txt" do
    content array.last["phone"]
  end

Это значительно чище, чем альтернативный вариант ленивой оценки парсинга JSON и рендеринга данных в шаблон файла, который произойдёт, если ресурс remote_file не выполняется во время компиляции:

  # the execution of this is now deferred
  remote_file "#{Chef::Config[:file_cache_path]}/users.json" do
    source "https://jsonplaceholder.typicode.com/users"
  end

  # it is necessary due to lexical scoping issues to create this variable here
  array = nil

  # the parsing of the JSON is now deferred due to the ruby_block
  ruby_block "parse JSON" do
    block do
      array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json")
    end
  end

  # the argument to the content property must now also be deferred
  file "/tmp/phone_number.txt" do
    content lazy { array.last["phone"] }
  end

Это пример кода, чрезмерно использующего отложенное выполнение, больше полагающегося на «ленивую» оценку и существенно сложнее для понимания и корректного написания.

Уведомления не будут работать

Ресурсы, выполняемые на стадии компиляции, не могут уведомлять другие ресурсы. Например:

execute 'ifconfig'

package 'vim-enhanced' do
  compile_time true
  notifies :run, 'execute[ifconfig]', :immediately
end

Лучший подход в такой ситуации — установить пакет до построения коллекции ресурсов, чтобы он был доступен другим ресурсам в дальнейшем.

Наилучший подход к этой проблеме — использовать unified mode, который устраняет различие между компиляцией и схождением, при этом позволяя уведомлениям работать корректно.

Ресурсы, которые по умолчанию выполняются на стадии компиляции

Ресурсы ohai_hint и hostname по умолчанию выполняются на стадии компиляции.

Это связано с тем, что последующие ресурсы могут использовать атрибуты узла, установленные этими ресурсами, что приводит к чрезмерному использованию lazy в последующих ресурсах (и аналогичным проблемам с примером remote_file выше).

Ресурс chef_gem ранее выполнялся по умолчанию на стадии компиляции, но сейчас мы рекомендуем пользователям перемещать код, выполняемый на стадии компиляции, в пользовательские ресурсы.

Атомарные обновления файлов

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

Атомарные обновления включены по умолчанию. Их можно управлять глобально, используя настройку file_atomic_update в файле client.rb. Их можно управлять на уровне каждого ресурса, используя свойство atomic_update, доступное для ресурсов cookbook_file, file, remote_file и template.

Безопасность файлов в Windows

Для поддержки безопасности Microsoft Windows ресурсы template, file, remote_file, cookbook_file, directory и remote_directory поддерживают использование наследования и списков управления доступом (ACL) в рецептах.

Списки управления доступом (ACL)

Свойство rights может быть использовано в рецепте для управления списками управления доступом (ACL), которые позволяют предоставлять разрешения нескольким пользователям и группам. Свойство rights можно использовать любое количество раз; Chef Infra Client применит их к файлу или каталогу по мере необходимости. Синтаксис свойства rights следующий:

rights permission, principal, option_type => value

где

permission

Используется для указания прав, предоставляемых principal. Возможные значения: :read, :write, read_execute, :modify, :full_control или целое число.

Целые числа, используемые для разрешений, должны соответствовать следующему списку FileSystemRights Enum fields.

These permissions are cumulative. If `:write` is specified, then it
includes `:read`. If `:full_control` is specified, then it includes
both `:write` and `:read`.

(For those who know the Microsoft Windows API: `:read` corresponds
to `GENERIC_READ`; `:write` corresponds to `GENERIC_WRITE`;
`:read_execute` corresponds to `GENERIC_READ` and `GENERIC_EXECUTE`;
`:modify` corresponds to `GENERIC_WRITE`, `GENERIC_READ`,
`GENERIC_EXECUTE`, and `DELETE`; `:full_control` corresponds to
`GENERIC_ALL`, which allows a user to change the owner and other
metadata about a file.)

principal

Используется для указания группы или пользователя. Субъект может быть задан либо по имени, либо по SID. При использовании имени, это идентично тому, что вводится в окне входа в Microsoft Windows, например user_name, domain\user_name или user_name@fully_qualified_domain_name. При использовании SID, вы можете использовать либо стандартное строковое представление SID (S-R-I-S-S), либо один из SDDL string constants. 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, что гарантирует сохранение первоначальных настроек безопасности существующих файлов.

Ресурсы

Следующие ресурсы встроены в Chef Infra Client:

Ресурс alternatives

Используйте ресурс alternatives для настройки альтернативных команд в Linux с использованием пакетов alternatives или update-alternatives.

Новое в Chef Infra Client 16.0.

Синтаксис

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

alternatives 'name' do
  link           String # default value: "/usr/bin/LINK_NAME"
  link_name      String # default value: 'name' unless specified
  path           String
  priority       String, Integer
  action         Symbol # defaults to :install if not specified
end

где:

• alternatives — это ресурс.
• name — имя блока ресурса.
• action определяет шаги, которые Chef Infra Client предпримет для приведения узла в желаемое состояние.
• link, link_name, path и priority — доступные для этого ресурса свойства.

Действия

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

:auto

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

:install

Установить альтернативу в системе, включая символические ссылки. (по умолчанию)

:nothing

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

:refresh

Обновить альтернативы.

:remove

Удалить альтернативу и все связанные ссылки.

:set

Установить символическую ссылку для альтернативы.

Свойства

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

link

Тип Ruby: Строка | Значение по умолчанию: /usr/bin/LINK_NAME

Путь к ссылке альтернативы.

link_name

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

Имя создаваемой ссылки. Это будет команда, которую вы набираете в командной строке, например, ruby или gcc.

path

Тип Ruby: Строка

Абсолютный путь к исходному двоичному файлу приложения, например, /usr/bin/ruby27.

priority

Тип Ruby: Строка, Целое число

Приоритет альтернативы.

Общие возможности ресурса

Ресурсы Chef включают общие свойства, уведомления и средства защиты ресурсов.

Общие свойства

Следующие свойства являются общими для всех ресурсов:

compile_time

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

Управление фазой, в которой ресурс выполняется на узле. Установите значение true, чтобы запустить его, когда собирается коллекция ресурсов (compile phase). Установите значение false, чтобы запустить его, когда Клиент Chef Infra настраивает узел (converge phase).

ignore_failure

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

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

retries

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

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

retry_delay

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

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

sensitive

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

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

Уведомления

notifies

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

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

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

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

:before

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

:delayed

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

:immediate, :immediately

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

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

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

subscribes

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

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

Примеры

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

Установить альтернативу:

alternatives 'python install 2' do
  link_name 'python'
  path '/usr/bin/python2.7'
  priority 100
  action :install
end

Установить альтернативу:

alternatives 'python set version 3' do
  link_name 'python'
  path '/usr/bin/python3'
  action :set
end

Установить автоматическое состояние альтернативы:

alternatives 'python auto' do
  link_name 'python'
  action :auto
end

Обновить альтернативу:

alternatives 'python refresh' do
  link_name 'python'
  action :refresh
end

Удалить альтернативу:

alternatives 'python remove' do
  link_name 'python'
  path '/usr/bin/python3'
  action :remove
end

Ресурс apt_package

Используйте ресурс apt_package для управления пакетами в системах Debian, Ubuntu и других платформах, использующих систему пакетов APT.

Синтаксис

Блок ресурса apt_package управляет пакетом на узле, обычно устанавливая его. Самое простое использование ресурса apt_package: apt_package 'package_name', что установит указанный пакет с использованием всех значений по умолчанию и действия по умолчанию :install.

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

apt_package 'name' do
  default_release              String
  options                      String, Array
  overwrite_config_files       true, false # default value: false
  package_name                 String, Array
  response_file                String
  response_file_variables      Hash # default value: {}
  timeout                      String, Integer
  version                      String, Array
  action                       Symbol # defaults to :install if not specified
end

где:

• apt_package — это ресурс.
• name — имя, данное блоку ресурса.
• action определяет действия, которые Клиент Chef Infra предпримет для приведения узла в желаемое состояние.
• default_release, options, overwrite_config_files, package_name, response_file, response_file_variables, timeout и version — доступные свойства для данного ресурса.

Действия

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

:install

Установить пакет. Если указана версия, установить указанную версию пакета. (по умолчанию)

:lock

Заблокировать пакет apt до определенной версии.

:nothing

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

:purge

Удалить пакет. Это действие, как правило, удаляет файлы конфигурации, а также пакет.

:reconfig

Переконфигурировать пакет. Это действие требует файла ответов.

:remove

Удалить пакет.

:unlock

Разблокировать пакет apt, чтобы его можно было обновить до более новой версии.

:upgrade

Установить пакет и/или убедиться, что пакет имеет последнюю версию.

Свойства

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

default_release

Тип Ruby: Строка

Значение по умолчанию для релиза. Например: stable.

options

Тип Ruby: Строка, массив

Один или несколько дополнительных параметров, которые передаются команде. Например, общие директивы apt-get, такие как --no-install-recommends. Полный список см. в документации apt-get.

overwrite_config_files

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

Перезаписывать существующие файлы конфигурации файлами, предоставленными пакетом, если APT попросит.

Новое в Chef Client 14.0

package_name

Тип Ruby: Строка, массив

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

response_file

Тип Ruby: Строка

Прямой путь к файлу, используемому для предварительной установки пакета.

response_file_variables

Тип Ruby: Хэш | Значение по умолчанию: {}

Хэш переменных файла ответов в формате {‘ПЕРЕМЕННАЯ’ => ‘ЗНАЧЕНИЕ’}.

timeout

Тип Ruby: Строка, целое число

Время ожидания (в секундах) перед истечением времени.

version

Тип Ruby: Строка, массив

Версия пакета, который нужно установить или обновить.

Множественные пакеты

Ресурс может указывать несколько пакетов и/или версий для платформ, использующих менеджеры пакетов Apt, Chocolatey, DNF, Homebrew, Pacman или Zypper. Указание нескольких пакетов и/или версий позволяет выполнить одну транзакцию для:

• Загрузки указанных пакетов и версий через одну HTTP-транзакцию
• Обновления или установки нескольких пакетов одним ресурсом во время выполнения Chef Infra Client

Например, установка нескольких пакетов:

package %w(package1 package2)

Установка нескольких пакетов с версиями:

package %w(package1 package2) do
  version [ '1.3.4-2', '4.3.6-1']
end

Обновление нескольких пакетов:

package %w(package1 package2) do
  action :upgrade
end

Удаление нескольких пакетов:

package %w(package1 package2) do
  action :remove
end

Удаление нескольких пакетов (purge):

package %w(package1 package2) do
  action :purge
end

Уведомления с использованием неявного имени:

package %w(package1 package2) do
  action :nothing
end

log 'call a notification' do
  notifies :install, 'package[package1, package2]', :immediately
end

Общие возможности ресурсов

Ресурсы 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[Строка]'

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

Множественные пакеты

Ресурс может указывать несколько пакетов и/или версий для платформ, использующих менеджеры пакетов Apt, Chocolatey, DNF, Homebrew, Pacman или Zypper. Указание нескольких пакетов и/или версий позволяет выполнить одну транзакцию для:

• Загрузки указанных пакетов и версий через одну HTTP-транзакцию
• Обновления или установки нескольких пакетов одним ресурсом во время выполнения Chef Infra Client

Например, установка нескольких пакетов:

package %w(package1 package2)

Установка нескольких пакетов с версиями:

package %w(package1 package2) do
  version [ '1.3.4-2', '4.3.6-1']
end

Обновление нескольких пакетов:

package %w(package1 package2) do
  action :upgrade
end

Удаление нескольких пакетов:

package %w(package1 package2) do
  action :remove
end

Очистка нескольких пакетов:

package %w(package1 package2) do
  action :purge
end

Уведомления, с помощью неявного имени:

package %w(package1 package2) do
  action :nothing
end

log 'call a notification' do
  notifies :install, 'package[package1, package2]', :immediately
end

Примеры

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

Установка пакета с помощью диспетчера пакетов:

apt_package 'name of package' do
  action :install
end

Установка пакета без указания действия по умолчанию:

apt_package 'name of package'

Установка нескольких пакетов одновременно:

apt_package %w(package1 package2 package3)

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

package 'apache2' do
  options '--no-install-recommends'
end

Ресурс apt_preference

Используйте ресурс apt_preference для создания файлов предпочтений APT файлов предпочтений. Файлы предпочтений используются для управления приоритетом версий пакетов и источников при установке.

Новое в Chef Infra Client 13.3.

Синтаксис

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

apt_preference 'name' do
  glob              String
  package_name      String # default value: 'name' unless specified
  pin               String
  pin_priority      String, Integer
  action            Symbol # defaults to :add if not specified
end

где:

• apt_preference — ресурс.
• name — имя, заданное для блока ресурса.
• action определяет действия, которые Chef Infra Client предпримет для приведения узла в нужное состояние.
• glob, package_name, pin и pin_priority — доступные свойства этого ресурса.

Действия

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

:add

Создаёт файл предпочтений в /etc/apt/preferences.d. (по умолчанию)

:nothing

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

:remove

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

Свойства

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

glob

Тип в Ruby: Строка

Привязка с помощью glob() выражения или с помощью регулярного выражения в /.

package_name

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

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

pin

Тип в Ruby: Строка | REQUIRED

Версия пакета или репозиторий для привязки.

pin_priority

Тип в Ruby: Строка, целое число | REQUIRED

Устанавливает Приоритет привязки для пакета. См. https://wiki.debian.org/AptPreferences для получения дополнительной информации.

Общие возможности ресурсов

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

not_if

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

only_if

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

Примеры

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

Привязка libmysqlclient16 к версии 5.1.49-3:

apt_preference 'libmysqlclient16' do
  pin          'version 5.1.49-3'
  pin_priority '700'
end

Примечание: pin_priority 700 гарантирует, что эта версия будет иметь приоритет над другими доступными версиями.

Снятие привязки libmysqlclient16:

apt_preference 'libmysqlclient16' do
  action :remove
end

Привязать все пакеты к репозиторию packages.dotdeb.org:

apt_preference 'dotdeb' do
  glob         '*'
  pin          'origin packages.dotdeb.org'
  pin_priority '700'
end

Ресурс apt_repository

Используйте ресурс apt_repository для указания дополнительных репозиториев APT. Добавление нового репозитория немедленно обновит кеш пакетов APT.

Новое в Chef Infra Client 12.9.

Синтаксис

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

apt_repository 'name' do
  arch               String, false
  cache_rebuild      true, false # default value: true
  components         Array # default value: `main` if using a PPA repository.
  cookbook           String, false
  deb_src            true, false # default value: false
  distribution       String, false # default value: The LSB codename of the node such as 'focal'.
  key                String, Array, false # default value: []
  key_proxy          String, false
  keyserver          String, false # default value: "keyserver.ubuntu.com"
  repo_name          String # default value: 'name' unless specified
  trusted            true, false # default value: false
  uri                String
  action             Symbol # defaults to :add if not specified
end

где:

• apt_repository — это ресурс.
• name — имя, заданное для блока ресурса.
• action определяет, какие действия Chef Infra Client предпримет для приведения узла в желаемое состояние.
• arch, cache_rebuild, components, cookbook, deb_src, distribution, key, key_proxy, keyserver, repo_name, trusted и uri — доступные для этого ресурса свойства.

Действия

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

:add

Создаёт файл репозитория в /etc/apt/sources.list.d/ и создаёт список репозитория. (по умолчанию)

:nothing

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

:remove

Удаляет список репозитория.

Свойства

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

arch

Тип Ruby: Строка, false

Ограничение пакетов определённой архитектурой процессора, например, i386 или amd64.

cache_rebuild

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

Определяет, нужно ли перестраивать кэш APT-пакетов.

components

Тип Ruby: Массив | Значение по умолчанию: `main` if using a PPA repository.

Группировка пакетов, например, «main» и «stable».

cookbook

Тип Ruby: Строка, false

Если ключ должен быть cookbook_file, укажите кулинарную книгу, где расположен ключ для файлов/default. Значение по умолчанию — nil, поэтому будет использована кулинарная книга, где используется ресурс.

deb_src

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

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

distribution

Тип Ruby: Строка, false | Значение по умолчанию: The LSB codename of the node such as 'focal'.

Обычно кодовое имя дистрибутива, например, xenial, bionic или focal.

key

Тип Ruby: Строка, Массив, false | Значение по умолчанию: []

Если предоставлен ключ сервера, предполагается, что это отпечаток; в противном случае он может быть либо URI GPG-ключа для репозитория, либо cookbook_file.

key_proxy

Тип Ruby: Строка, false

Если установлено, указанный прокси передаётся GPG через http-proxy=.

keyserver

Тип Ruby: Строка, false | Значение по умолчанию: keyserver.ubuntu.com

Сервер GPG-ключей, где должен быть получен ключ для репозитория.

repo_name

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

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

Новое в Chef Client 14.1

trusted

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

Определяет, следует ли рассматривать все пакеты из этого репозитория как проверенные независимо от подписи.

uri

Тип Ruby: Строка

Основа дистрибутива Debian.

Общие функции ресурсов

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

Примеры

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

Добавление репозитория с базовыми настройками:

apt_repository 'nginx' do
  uri        'http://nginx.org/packages/ubuntu/'
  components ['nginx']
end

Включение репозиториев Ubuntu multiverse:

apt_repository 'security-ubuntu-multiverse' do
  uri          'http://security.ubuntu.com/ubuntu'
  distribution 'xenial-security'
  components   ['multiverse']
  deb_src      true
end

Добавление Nginx PPA, автоматическое определение ключа и URL репозитория:

apt_repository 'nginx-php' do
  uri          'ppa:nginx/stable'
end

Добавление JuJu PPA, получение ключа с сервера ключей Ubuntu и добавление источника репозитория:

apt_repository 'juju' do
  uri 'ppa:juju/stable'
  components ['main']
  distribution 'xenial'
  key 'C8068B11'
  action :add
  deb_src true
end

Добавление репозитория, требующего нескольких ключей для аутентификации пакетов:

apt_repository 'rundeck' do
  uri 'https://dl.bintray.com/rundeck/rundeck-deb'
  distribution '/'
  key ['379CE192D401AB61', 'http://rundeck.org/keys/BUILD-GPG-KEY-Rundeck.org.key']
  keyserver 'keyserver.ubuntu.com'
  action :add
end

Добавление репозитория Cloudera Repo пакетов CDH4 для Ubuntu 16.04 на AMD64:

apt_repository 'cloudera' do
  uri          'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh'
  arch         'amd64'
  distribution 'xenial-cdh4'
  components   ['contrib']
  key          'http://archive.cloudera.com/debian/archive.key'
end

Удаление репозитория из списка:

apt_repository 'zenoss' do
  action :remove
end

Ресурс apt_update

Используйте ресурс apt_update для управления обновлениями репозиториев APT на платформах Debian и Ubuntu.

Новое в Chef Infra Client 12.7.

Синтаксис

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

apt_update 'name' do
  frequency      Integer # default value: 86400
  action         Symbol # defaults to :periodic if not specified
end

где:

• apt_update — это ресурс.
• name — это имя, данное блоку ресурса.
• action определяет, какие шаги Chef Infra Client предпримет для приведения узла к желаемому состоянию.
• frequency — это свойство, доступное для данного ресурса.

Без имени

Этот ресурс может быть без имени. Добавьте сам ресурс в свой рецепт, чтобы получить стандартное поведение:

apt_update

будет вести себя так же, как:

apt_update 'update'

Действия

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

:nothing

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

:periodic

Обновляет репозиторий Apt с интервалом, указанным свойством frequency. (по умолчанию)

:update

Обновляет репозиторий Apt в начале выполнения Chef Infra Client.

Свойства

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

frequency

Тип Руби: Целое число | Значение по умолчанию: 86400

Определяет, как часто (в секундах) производятся обновления репозитория APT. Используйте это свойство, когда указано действие :periodic.

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

Ресурсы Chef включают общие свойства, уведомления и сторожа ресурсов.

Общие свойства

Следующие свойства общие для всех ресурсов:

compile_time

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

Управляет фазой, в которой ресурс выполняется на узле. Установите в значение true, чтобы запустить его при построении коллекции ресурсов (compile phase). Установите в значение false, чтобы запустить его при конфигурировании узла Chef Infra Client (converge phase).

ignore_failure

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

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

retries

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

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

retry_delay

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

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

sensitive

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

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

Уведомления

notifies

Тип Руби: Символ, '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

Тип Руби: Символ, '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.

Примеры

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

Обновление репозитория Apt с заданным интервалом:

apt_update 'all platforms' do
  frequency 86400
  action :periodic
end

Обновление репозитория Apt в начале выполнения Chef Infra Client:

apt_update 'update'

Ресурс archive_file

Используйте ресурс archive_file для извлечения файлов архивов на диск. Этот ресурс использует библиотеку libarchive для извлечения нескольких форматов архивов, включая tar, gzip, bzip и zip.

Новое в Chef Infra Client 15.0.

Синтаксис

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

archive_file 'name' do
  destination           String
  group                 String
  mode                  String, Integer # default value: "'755'"
  options               Array, Symbol
  overwrite             true, false, auto # default value: false
  owner                 String
  path                  String # default value: 'name' unless specified
  strip_components      Integer # default value: 0
  action                Symbol # defaults to :extract if not specified
end

где:

• archive_file — ресурс.
• name — имя, заданное для блока ресурса.
• action определяет, какие шаги Chef Infra Client предпримет для приведения узла в желаемое состояние.
• destination, group, mode, options, overwrite, owner, path и strip_components — доступные свойства для этого ресурса.

Действия

Для ресурса archive_file доступны следующие действия:

:extract

Извлечение и архивирование файла. (по умолчанию)

:nothing

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

Свойства

Для ресурса archive_file доступны следующие свойства:

destination

Тип Ruby: Строка | REQUIRED

Путь к файлу, в который будет извлечён архив.

group

Тип Ruby: Строка

Группа извлечённых файлов.

mode

Тип Ruby: Строка, Целое число | Значение по умолчанию: '755'

Режим извлечённых файлов. Целые значения устарели, так как восьмеричные значения (например, 0755) не будут интерпретированы корректно.

options

Тип Ruby: Массив, Символ | Значение по умолчанию: lazy default

Массив символов, представляющих флаги извлечения. Например: :no_overwrite для предотвращения перезаписи файлов на диске. По умолчанию это правильно устанавливает :time, что сохраняет отметки времени изменения файлов в архиве при записи их на диск.

overwrite

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

Нужно ли ресурсу перезаписывать содержимое целевого файла, если оно уже существует? Если установлено :auto, будет сравниваться отметка времени файлов в архиве с отметками на диске, и содержимое диска будет перезаписано, если они отличаются. Это может привести к непредвиденным последствиям, если отметки времени на диске изменяются между выполнениями, что приведёт к перезаписи файлов во время каждого запуска клиента. Убедитесь в правильной проверке любых изменений в этом свойстве.

owner

Тип Ruby: Строка

Владелец извлечённых файлов.

path

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

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

strip_components

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

Удалить указанное количество ведущих элементов пути. Пути с меньшим количеством элементов будут пропущены без ошибок. Это аналогично команде командной строки tar –strip-components.

Новое в Chef Infra Client 17.5

Общие функции ресурсов

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

Примеры

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

Извлечение файла zip в указанный каталог:

archive_file 'Precompiled.zip' do
  path '/tmp/Precompiled.zip'
  destination '/srv/files'
end

Установка определённых разрешений на извлечённые файлы:

archive_file 'Precompiled.zip' do
  owner 'tsmith'
  group 'staff'
  mode '700'
  path '/tmp/Precompiled.zip'
  destination '/srv/files'
end

bash ресурс

Используйте ресурс bash для выполнения скриптов с помощью интерпретатора Bash. Этот ресурс также может использовать любые действия и свойства, доступные для ресурса execute. Команды, выполняемые с помощью этого ресурса, по своей природе не являются идемпотентными, так как они обычно уникальны для среды, в которой они выполняются. Используйте not_if и only_if для защиты этого ресурса от идемпотентности.

Синтаксис

Блок ресурса bash выполняет скрипты с помощью Bash:

bash 'extract_module' do
  cwd ::File.dirname(src_filepath)
  code <<-EOH
    mkdir -p #{extract_path}
    tar xzf #{src_filename} -C #{extract_path}
    mv #{extract_path}/*/* #{extract_path}/
  EOH
  not_if { ::File.exist?(extract_path) }
end

где:

• cwd указывает каталог, из которого выполняется команда
• code указывает команду для выполнения

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

bash 'name' do
  code                       String
  creates                    String
  cwd                        String
  environment                Hash
  flags                      String
  group                      String, Integer
  path                       Array
  returns                    Integer, Array
  timeout                    Integer, Float
  user                       String, Integer
  umask                      String, Integer
  action                     Symbol # defaults to :run if not specified
end

где:

• bash — это ресурс.
• name — имя, заданное для блока ресурса.
• action определяет действия, которые Chef Infra Client предпримет для приведения узла в желаемое состояние.
• code, creates, cwd, environment, flags, group, path, returns, timeout, user и umask — свойства этого ресурса с указанным типом Ruby. Более подробную информацию о всех свойствах, которые можно использовать с этим ресурсом, см. в разделе «Свойства» ниже.

Действия

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

:nothing

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

:run

По умолчанию. Выполняет скрипт.

Свойства

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

code

Тип Ruby: Строка | REQUIRED

Строка кода, заключенная в кавычки (" “), который должен быть выполнен.

creates

Тип Ruby: Строка

Запрещает команде создавать файл, если такой файл уже существует.

cwd

Тип Ruby: Строка

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

environment

Тип Ruby: Хеш

Хеш переменных среды в формате ({'ENV_VARIABLE' => 'VALUE'}). Примечание: Эти переменные должны существовать для успешного выполнения команды.

flags

Тип Ruby: Строка

Одна или несколько командных строк, передаваемых интерпретатору при вызове команды.

group

Тип Ruby: Строка, Целое число

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

returns

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

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

timeout

Тип Ruby: Целое число, Строка, Вещественное число | Значение по умолчанию: 3600

Время (в секундах), которое команда должна ждать перед истечением времени ожидания.

user

Тип Ruby: Строка, Целое число

Имя пользователя или идентификатор пользователя, который должен быть изменен перед выполнением команды.

umask

Тип Ruby: Строка, Целое число

Маска создания режима файла или umask.

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

Ресурсы 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[Строка]'

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

Примеры

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

Использование именованного поставщика для выполнения скрипта

bash 'install_something' do
  user 'root'
  cwd '/tmp'
  code <<-EOH
    wget http://www.example.com/tarball.tar.gz
    tar -zxf tarball.tar.gz
    cd tarball
    ./configure
    make
    make install
  EOH
end

Установка файла из удаленного расположения с помощью bash

Следующий пример демонстрирует, как установить модуль foo123 для Nginx. Этот модуль добавляет функциональность в стиле оболочки в конфигурационный файл Nginx и выполняет следующие действия:

• Объявляет три переменные
• Получает файл Nginx из удаленного расположения
• Устанавливает файл с помощью Bash в путь, указанный переменной src_filepath

# the following code sample is similar to the ``upload_progress_module``
# recipe in the ``nginx`` cookbook:
# https://github.com/chef-cookbooks/nginx

src_filename = "foo123-nginx-module-v#{
  node['nginx']['foo123']['version']
}.tar.gz"
src_filepath = "#{Chef::Config['file_cache_path']}/#{src_filename}"
extract_path = "#{
  Chef::Config['file_cache_path']
  }/nginx_foo123_module/#{
  node['nginx']['foo123']['checksum']
}"

remote_file 'src_filepath' do
  source node['nginx']['foo123']['url']
  checksum node['nginx']['foo123']['checksum']
  owner 'root'
  group 'root'
  mode '0755'
end

bash 'extract_module' do
  cwd ::File.dirname(src_filepath)
  code <<-EOH
    mkdir -p #{extract_path}
    tar xzf #{src_filename} -C #{extract_path}
    mv #{extract_path}/*/* #{extract_path}/
  EOH
  not_if { ::File.exist?(extract_path) }
end

Установка приложения из git с помощью bash

Следующий пример демонстрирует, как Bash можно использовать для установки плагина для rbenv под названием ruby-build, который расположен в системе управления версиями git. Сначала приложение синхронизируется, затем Bash меняет рабочую директорию на местоположение, где находится ruby-build, и затем выполняет команду.

git "#{Chef::Config[:file_cache_path]}/ruby-build" do
  repository 'git://github.com/sstephenson/ruby-build.git'
  revision 'master'
  action :sync
end

bash 'install_ruby_build' do
  cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
  user 'rbenv'
  group 'rbenv'
  code <<-EOH
    ./install.sh
  EOH
  environment 'PREFIX' => '/usr/local'
end

Чтобы узнать больше о ruby-build, см. здесь: https://github.com/sstephenson/ruby-build.

Хранение определенных настроек

Следующий рецепт показывает, как файл атрибутов можно использовать для хранения определенных настроек. Файл атрибутов расположен в директории attributes/ в том же кулинарном руководстве, что и рецепт, который вызывает файл атрибутов. В этом примере файл атрибутов определяет определенные настройки для Python, которые затем используются на всех узлах, на которых будет выполняться этот рецепт.

У пакетов Python есть версии, каталоги установки, URL-адреса и файлы контрольных сумм. Файл атрибутов, предназначенный для поддержки такого типа рецептов, будет содержать настройки, подобные следующим:

default['python']['version'] = '2.7.1'

if python['install_method'] == 'package'
  default['python']['prefix_dir'] = '/usr'
else
  default['python']['prefix_dir'] = '/usr/local'
end

default['python']['url'] = 'http://www.python.org/ftp/python'
default['python']['checksum'] = '80e387...85fd61'

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

• Определить каждый пакет для установки (в этом примере подразумевается, но не показано)
• Определить переменные для пакета version и install_path
• Получить пакет из удаленного расположения, но только если пакет еще не существует на целевой системе
• Использовать ресурс bash для установки пакета на узел, но только если пакет еще не установлен

#  the following code sample comes from the ``oc-nginx`` cookbook on |github|: https://github.com/cookbooks/oc-nginx

version = node['python']['version']
install_path = "#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\d+\.\d+)/)[1]}"

remote_file "#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2" do
  source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"
  checksum node['python']['checksum']
  mode '0755'
  not_if { ::File.exist?(install_path) }
end

bash 'build-and-install-python' do
  cwd Chef::Config[:file_cache_path]
  code <<-EOF
    tar -jxvf Python-#{version}.tar.bz2
    (cd Python-#{version} && ./configure #{configure_options})
    (cd Python-#{version} && make && make install)
  EOF
  not_if { ::File.exist?(install_path) }
end

Ресурс batch

Используйте ресурс batch для выполнения скрипта пакетной обработки с помощью интерпретатора cmd.exe в Windows. Ресурс batch создает и выполняет временный файл (подобно тому, как ведет себя ресурс скрипта), а не выполняет команду непосредственно. Команды, выполняемые с помощью этого ресурса, по своей природе не идемпотентны, так как они обычно уникальны для среды, в которой они выполняются. Используйте not_if и only_if для обеспечения идемпотентности этого ресурса.

Синтаксис

Блок ресурса batch выполняет скрипт пакетной обработки с помощью интерпретатора cmd.exe:

batch 'echo some env vars' do
  code <<-EOH
    echo %TEMP%
    echo %SYSTEMDRIVE%
    echo %PATH%
    echo %WINDIR%
  EOH
end

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

batch 'name' do
  architecture               Symbol
  code                       String
  command                    String, Array
  creates                    String
  cwd                        String
  flags                      String
  group                      String, Integer
  guard_interpreter          Symbol
  interpreter                String
  returns                    Integer, Array
  timeout                    Integer, Float
  user                       String
  password                   String
  domain                     String
  action                     Symbol # defaults to :run if not specified
end

где:

• batch — это ресурс.
• name — это имя, заданное для блока ресурса.
• action определяет, какие шаги Chef Infra Client предпримет для приведения узла в нужное состояние.
• architecture, code, command, creates, cwd, flags, group, guard_interpreter, interpreter, returns, timeout, user, password и domain — это свойства этого ресурса с указанным типом Ruby. См. раздел «Свойства» ниже для получения дополнительной информации обо всех свойствах, которые можно использовать с этим ресурсом.

Действия

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

:nothing

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

:run

Выполнить файл пакетной обработки.

Свойства

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

architecture

Тип Ruby: Символ

Архитектура процесса, в рамках которого выполняется скрипт. Если значение не указано, Chef Infra Client использует соответствующее значение для архитектуры, определяемое Ohai. Возникает исключение, когда для 32-битного процесса указывается что-либо кроме :i386. Возможные значения: :i386 (для 32-битных процессов) и :x86_64 (для 64-битных процессов).

code

Тип Ruby: Строка | REQUIRED

Строка кода в кавычках, подлежащая выполнению.

command

Тип Ruby: Строка, Массив

Имя команды, подлежащей выполнению.

creates

Тип Ruby: Строка

Предотвращение создания команды файла, если этот файл уже существует.

cwd

Тип Ruby: Строка

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

flags

Тип Ruby: Строка

Один или несколько флагов командной строки, передаваемых интерпретатору при вызове команды.

group

Тип Ruby: Строка, Целое число

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

guard_interpreter

Тип Ruby: Символ | Значение по умолчанию: :batch

При установке этого свойства в :batch, будет использована 64-разрядная версия оболочки cmd.exe для вычисления строковых значений для свойств not_if и only_if. Установите это значение в :default для использования 32-разрядной версии оболочки cmd.exe.

interpreter

Тип Ruby: Строка

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

returns

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

Возвращаемое значение для команды. Это может быть массив допустимых значений. Возникает исключение, если возвращаемое значение(я) не соответствуют.

timeout

Тип Ruby: Целое число, Строка, Вещественное число | Значение по умолчанию: 3600

Время (в секундах), которое команда должна ждать перед истечением времени ожидания.

user

Тип Ruby: Строка

Имя пользователя учетной записи пользователя, с которой нужно запустить новый процесс. Имя пользователя необязательно может быть указано с доменом, например, domainuser или user@my.dns.domain.com в формате Universal Principal Name (UPN). Его также можно указать без домена просто как user, если вместо этого домен указан с помощью атрибута domain. Только в Windows, если это свойство указано, необходимо указать свойство password.

password

Тип Ruby: Строка

Только Windows: Пароль пользователя, указанного в свойстве user. Это свойство обязательно, если user указано в Windows, и может быть указано только если указано user. Свойство sensitive для этого ресурса автоматически будет установлено в true, если указан пароль.

domain

Тип Ruby: Строка

Только Windows: Домен пользователя, указанного в свойстве user. Если не указано, имя пользователя и пароль, указанные в свойствах user и password, будут использоваться для поиска этого пользователя в домене, к которому присоединена система, выполняющая Chef Infra Client, или если эта система не присоединена к домену, пользователь будет найден как локальная учетная запись на этой системе. Альтернативный способ указания домена — оставить это свойство не указанным и указать домен в свойстве user.

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

Ресурсы 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[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[Строка]'

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

Примеры

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

Разархивировать файл и затем переместить его

Для выполнения пакетного файла, который разархивирует и затем переместит Ruby, выполните:

batch 'unzip_and_move_ruby' do
  code <<-EOH
    7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z
      -oC:\\source -r -y
    xcopy C:\\source\\ruby-1.8.7-p352-i386-mingw32 C:\\ruby /e /y
  EOH
end

batch 'echo some env vars' do
  code <<-EOH
    echo %TEMP%
    echo %SYSTEMDRIVE%
    echo %PATH%
    echo %WINDIR%
  EOH
end

или:

batch 'unzip_and_move_ruby' do
  code <<-EOH
    7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z
      -oC:\\source -r -y
    xcopy C:\\source\\ruby-1.8.7-p352-i386-mingw32 C:\\ruby /e /y
  EOH
end

batch 'echo some env vars' do
  code 'echo %TEMP%\\necho %SYSTEMDRIVE%\\necho %PATH%\\necho %WINDIR%'
end

Запустить команду от имени другого пользователя

Примечание: При работе Chef в качестве службы для этой функции требуется, чтобы пользователь, от имени которого работает Chef, обладал правом «SeAssignPrimaryTokenPrivilege» (также известным как «SE_ASSIGNPRIMARYTOKEN_NAME»). По умолчанию только LocalSystem и NetworkService имеют это право при запуске в качестве службы. Это необходимо даже если пользователь является администратором.

Это право может быть добавлено и проверено в рецепте с помощью этого примера:

# Add 'SeAssignPrimaryTokenPrivilege' for the user
Chef::ReservedNames::Win32::Security.add_account_right('<user>', 'SeAssignPrimaryTokenPrivilege')

# Check if the user has 'SeAssignPrimaryTokenPrivilege' rights
Chef::ReservedNames::Win32::Security.get_account_right('<user>').include?('SeAssignPrimaryTokenPrivilege')

Следующий пример демонстрирует запуск mkdir test_dir из выполнения Chef Infra Client от имени другого пользователя.

# Passing only username and password
batch 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "username"
 password "password"
end

# Passing username and domain
batch 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 domain "domain"
 user "username"
 password "password"
end

# Passing username = 'domain-name\\username'. No domain is passed
batch 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "domain-name\\username"
 password "password"
end

# Passing username = 'username@domain-name'. No domain is passed
batch 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "username@domain-name"
 password "password"
end

Ресурс bff_package

Используйте ресурс bff_package для управления пакетами для платформы AIX с помощью утилиты installp. При установке пакета из локального файла он должен быть добавлен в узел с помощью ресурсов remote_file или cookbook_file.

Синтаксис

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

bff_package 'name' do
  options           String, Array
  package_name      String
  source            String
  timeout           String, Integer
  version           String
  action            Symbol # defaults to :install if not specified
end

где:

• bff_package — ресурс.
• name — имя, присвоенное блоку ресурса.
• action — определяет шаги, которые Chef Infra Client предпримет, чтобы привести узел в желаемое состояние.
• options, package_name, source, timeout и version — доступные свойства этого ресурса.

Действия

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

:install

По умолчанию. Устанавливает пакет. Если указана версия, устанавливается указанная версия пакета.

:nothing

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

:purge

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

:remove

Удаляет пакет.

Свойства

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

options

Тип в Ruby: Строка, Массив

Одна (или несколько) дополнительных командных опций, которые передаются команде.

package_name

Тип в Ruby: Строка

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

source

Тип в Ruby: Строка

Обязательное. Путь к пакету в локальной файловой системе. Платформа AIX требует, чтобы source был путем в локальной файловой системе, поскольку installp не получает пакеты с помощью HTTP или FTP.

timeout

Тип в Ruby: Строка, Целое число

Время ожидания в секундах перед истечением срока действия.

version

Тип в 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 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[Строка]'

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

Примеры

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

Ресурс bff_package является по умолчанию поставщиком пакетов на платформе AIX. Можно использовать базовый ресурс package, и затем, когда платформа — AIX, Chef Infra Client определит правильного поставщика пакетов. Следующие примеры показывают, как установить часть компилятора IBM XL C/C++.

Установка с помощью базового ресурса package

package 'xlccmp.13.1.0' do
  source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
  action :install
end

Установка с помощью ресурса bff_package

bff_package 'xlccmp.13.1.0' do
  source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
  action :install
end

ресурс breakpoint

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

Новинка в Chef Infra Client 12.0.

Синтаксис

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

breakpoint 'name' do
  action      Symbol # defaults to :break if not specified
end

где:

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

Действия

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

:break

Добавить точку останова для использования с chef-shell (по умолчанию)

:nothing

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

Свойства

У данного ресурса нет свойств.

Отладка рецептов с помощью chef-shell

Режимы

chef-shell — это инструмент, работающий в сессии Interactive Ruby (IRb). В настоящее время chef-shell поддерживает синтаксис файлов рецептов и атрибутов, а также интерактивные функции отладки. chef-shell имеет три режима работы:

Настройка

chef-shell определяет, какой файл конфигурации загрузить, на основе следующего:

1. Если файл конфигурации указан с помощью параметра -c, chef-shell использует указанный файл конфигурации
2. Если задан NAMED_CONF, chef-shell загрузит ~/.chef/NAMED_CONF/chef_shell.rb
3. Если NAMED_CONF не задан, chef-shell загрузит ~/.chef/chef_shell.rb, если он существует
4. Если chef_shell.rb не найден, chef-shell возвращается к загрузке:
   • /etc/chef/client.rb, если задан параметр -z.
   • /etc/chef/solo.rb, если задан параметр –solo-legacy-mode.
   • .chef/config.rb, если задан параметр -s.
   • .chef/knife.rb, если задан параметр -s.

chef-shell.rb

Файл chef-shell.rb можно использовать для настройки chef-shell аналогично тому, как файл client.rb используется для настройки Chef Infra Client. Например, чтобы настроить chef-shell на аутентификацию на сервере Chef Infra Server, скопируйте настройки node_name, client_key и chef_server_url из файла config.rb:

node_name                'your-knife-clientname'
client_key               File.expand_path('~/.chef/my-client.pem')
chef_server_url          'https://api.opscode.com/organizations/myorg'

и добавьте их в файл chef-shell.rb. Другие возможности настройки включают отключение плагинов Ohai (что ускорит загрузку chef-shell) или включение произвольного кода Ruby в файл chef-shell.rb.

Запуск как клиента Chef Infra

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

chef-shell может использовать те же учетные данные, что и knife, при подключении к серверу Chef Infra Server. Убедитесь, что настройки в chef-shell.rb совпадают с настройками в config.rb, а затем используйте параметр -z в командной строке. Например:

chef-shell -z

Управление

При настройке chef-shell для доступа к Chef Infra Server, chef-shell может перечислять, показывать, искать и редактировать кулинарные книги, клиентов, узлы, роли, среды, файлы политики и пакеты данных.

Синтаксис управления объектами на Chef Infra Server следующий:

chef-shell -z named_configuration

Где:

• named_configuration — это существующий файл конфигурации в ~/.chef/named_configuration/chef_shell.rb, такой как production, staging или test.

После входа в chef-shell команды могут выполняться над объектами следующим образом:

chef (preprod) > items.command

Где:

• items — это тип элемента для поиска: cookbooks, clients, nodes, roles, environments или пакет данных.
• command — это команда: list, show, find или edit.

Например, чтобы перечислить все узлы в конфигурации с именем «preprod», введите:

chef (preprod) > nodes.list

Что вернёт результат, подобный этому:

=> [node[i-f09a939b], node[i-049a936f], node[i-eaaaa581], node[i-9154b1fb],
    node[i-6a213101], node[i-c2687aa9], node[i-7abeaa11], node[i-4eb8ac25],
    node[i-9a2030f1], node[i-a06875cb], node[i-145f457f], node[i-e032398b],
    node[i-dc8c98b7], node[i-6afdf401], node[i-f49b119c], node[i-5abfab31],
    node[i-78b8ac13], node[i-d99678b3], node[i-02322269], node[i-feb4a695],
    node[i-9e2232f5], node[i-6e213105], node[i-cdde3ba7], node[i-e8bfb083],
    node[i-743c2c1f], node[i-2eaca345], node[i-aa7f74c1], node[i-72fdf419],
    node[i-140e1e7f], node[i-f9d43193], node[i-bd2dc8d7], node[i-8e7f70e5],
    node[i-78f2e213], node[i-962232fd], node[i-4c322227], node[i-922232f9],
    node[i-c02728ab], node[i-f06c7b9b]]

Команда list может принимать блок кода, который будет применён (но не сохранён) к каждому объекту, возвращённому сервером. Например:

chef (preprod) > nodes.list {|n| puts "#{n.name}: #{n.run_list}" }

вернёт результат, подобный этому:

=> i-f09a939b: role[lb], role[preprod], recipe[aws]
   i-049a936f: role[lb], role[preprod], recipe[aws]
   i-9154b1fb: recipe[erlang], role[base], role[couchdb], role[preprod],
   i-6a213101: role[chef], role[preprod]
   # more...

Команда show может использоваться для отображения определённого узла. Например:

chef (preprod) > load_balancer = nodes.show('i-f09a939b')

вернёт результат, подобный этому:

=> node[i-f09a939b]

Или:

chef (preprod) > load_balancer.ec2.public_hostname

вернёт результат, подобный этому:

=> "ec2-111-22-333-44.compute-1.amazonaws.com"

Команда find может использоваться для поиска на Chef Infra Server из chef-shell. Например:

chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*')

Вы также можете отформатировать результаты с помощью блока кода. Например:

chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id } and nil

вернёт результат, подобный этому:

=> ["ami-f8927a91",
    "ami-f8927a91",
    "ami-a89870c1",
    "ami-a89870c1",
    "ami-a89870c1",
    "ami-a89870c1",
    "ami-a89870c1"
    # and more...

Или:

chef (preprod) > amis = nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id }
chef (preprod) > puts amis.uniq.sort

вернёт результат, подобный этому:

=> ami-4b4ba522
   ami-a89870c1
   ami-eef61587
   ami-f8927a91

Использование точек останова

Пошаговое выполнение списка выполнения

Чтобы изучить использование точки останова для ручного пошагового выполнения работы Chef Infra Client, создайте простой рецепт в chef-shell:

chef > recipe_mode
  chef:recipe > echo off
  chef:recipe > file "/tmp/before-breakpoint"
  chef:recipe > breakpoint "foo"
  chef:recipe > file "/tmp/after-breakpoint"

и затем запустите Chef Infra Client:

chef:recipe > run_chef
  [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
  [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
  [Fri, 15 Jan 2020 14:17:49 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint
  [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
  [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint

Chef Infra Client выполнил первый ресурс перед точкой останова (file[/tmp/before-breakpoint]), но затем остановился после выполнения. Chef Infra Client попытался назвать точку останова по её позиции в исходном файле, но Chef Infra Client запутался, потому что ресурс был введён интерактивно. Отсюда chef-shell может продолжить прерванную работу Chef Infra Client:

chef:recipe > chef_run.resume
  [Fri, 15 Jan 2020 14:27:08 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint

Быстрый просмотр каталога /tmp показывает, что были созданы следующие файлы:

after-breakpoint
before-breakpoint

Вы можете отмотать и выполнить по шагам работу Chef Infra Client:

chef:recipe > Chef::Log.level = :debug # debug logging won't turn on automatically in this case
    => :debug
  chef:recipe > chef_run.rewind
    => 0
  chef:recipe > chef_run.step
  [Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
  [Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
    => 1
  chef:recipe > chef_run.step
  [Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
  [Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint
    => 2
  chef:recipe > chef_run.step
  [Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: Processing file[/tmp/after-breakpoint]
  [Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File
    => 3

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

chef:recipe > ls("/tmp").grep(/breakpoint/).each {|f| rm "/tmp/#{f}" }
    => ["after-breakpoint", "before-breakpoint"]

Отмотайте и затем возобновите работу Chef Infra Client, чтобы получить ожидаемые результаты:

chef:recipe > chef_run.rewind
  chef:recipe > chef_run.resume
  [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
  [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
  [Fri, 15 Jan 2020 14:48:56 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint
  [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
  [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint
  chef:recipe > chef_run.resume
  [Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: Processing file[/tmp/after-breakpoint]
  [Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File
  [Fri, 15 Jan 2020 14:49:20 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint

Отладка существующего рецепта

chef-shell можно использовать для отладки существующих рецептов. Рецепт сначала необходимо добавить в список выполнения для узла, чтобы он кешировался при запуске chef-shell и затем использовался для отладки. chef-shell сообщит, какие рецепты кешируются при запуске:

loading configuration: none (standalone session)
Session type: standalone
Loading.............done.

Welcome to the chef-shell 15.8.23
For usage see https://docs.chef.io/chef_shell.html

run `help' for help, `exit' or ^D to quit.

chef (15.8.23)>

Чтобы загрузить только один рецепт из списка выполнения, перейдите в рецепт и используйте команду include_recipe. Например:

chef > recipe_mode
  chef:recipe > include_recipe "getting-started"
    => [#< Chef::Recipe:0x10256f9e8 @cookbook_name="getting-started",
  ... output truncated ...

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

node.run_list.expand(node.chef_environment).recipes.each do |r|
  include_recipe r
end

После загрузки рецептов, которые необходимо отладить, используйте команду run_chef для их выполнения.

Расширенная отладка

В chef-shell можно получить подробную отладку, используя функцию отслеживания в Interactive Ruby (IRb). chef-shell предоставляет ярлык для включения и выключения отслеживания. Например:

chef > tracing on
tracing is on
=> nil
chef >

и:

chef > tracing off
#0:(irb):2:Object:-: tracing off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:109:Shell::Extensions::ObjectCoreExtensions:>:       def off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:110:Shell::Extensions::ObjectCoreExtensions:-:         :off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:111:Shell::Extensions::ObjectCoreExtensions:<:       end
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:272:main:>:       def tracing(on_or_off)
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:273:main:-:         conf.use_tracer = on_or_off.on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:162:Shell::Extensions::Symbol:>:       def on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:163:Shell::Extensions::Symbol:-:         to_s.on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:149:Shell::Extensions::String:>:       def on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:150:Shell::Extensions::String:-:         case self
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:154:Shell::Extensions::String:-:           false
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:158:Shell::Extensions::String:<:       end
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:164:Shell::Extensions::Symbol:<:       end
tracing is off
=> nil
chef >

Примеры отладки

Следующие примеры показывают, как использовать chef-shell.

"Привет, мир"

Этот пример демонстрирует, как запустить chef-shell в автономном режиме. (Для режимов chef-solo или Chef Infra Client вам нужно запустить chef-shell с опциями командной строки -s или -z, а затем учесть необходимые настройки конфигурации.)

При установке Chef Infra Client с помощью RubyGems или менеджера пакетов chef-shell должен быть уже установлен. При запуске Chef Infra Client из git-клона он будет расположен в chef/bin/chef shell. Чтобы запустить chef-shell, просто запустите его без каких-либо опций. Вы увидите сообщение о загрузке, затем баннер и затем приглашение chef-shell:

bin/chef-shell

  loading configuration: none (standalone session)
  Session type: standalone
  Loading.............done.

  Welcome to the chef-shell 15.8.23
  For usage see https://docs.chef.io/chef_shell.html

  run `help' for help, `exit' or ^D to quit.

  chef (15.8.23)>

(Используйте команду help, чтобы получить список поддерживаемых команд.) Используйте команду recipe_mode, чтобы переключиться в контекст рецепта:

chef > recipe_mode
  chef:recipe_mode >

Ввод оценивается в том же контексте, что и рецепты. Создайте ресурс файла:

chef:recipe_mode > file "/tmp/ohai2u_shef"
    => #< Chef::Resource::File:0x1b691ac
       @enclosing_provider=nil,
       @resource_name=:file,
       @before=nil,
       @supports={},
       @backup=5,
       @allowed_actions=[:nothing, :create, :delete, :touch, :create_if_missing],
       @only_if=nil,
       @noop=nil,
       @collection=#< Chef::ResourceCollection:0x1b9926c
       @insert_after_idx=nil,
       @resources_by_name={"file[/tmp/ohai2u_shef]"=>0},
       @resources=[#< Chef::Resource::File:0x1b691ac ...>]>,
       @updated=false,
       @provider=nil,
       @node=< Chef::Node:0xdeeaae
       @name="eigenstate.local">,
       @recipe_name=nil,
       @not_if=nil,
       @name="/tmp/ohai2u_shef",
       @action="create",
       @path="/tmp/ohai2u_shef",
       @source_line="/Users/username/ruby/chef/chef/(irb#1) line 1",
       @params={},
       @actions={},
       @cookbook_name=nil,
       @ignore_failure=false>

(Предыдущий пример был отформатирован для представления.) На этом этапе chef-shell создал ресурс и поместил его в список выполнения, но ещё не создал файл. Чтобы запустить работу Chef Infra Client, используйте команду run_chef:

chef:recipe_mode > run_chef
  [Fri, 15 Jan 2020 10:42:47 -0800] DEBUG: Processing file[/tmp/ohai2u_shef]
  [Fri, 15 Jan 2020 10:42:47 -0800] DEBUG: file[/tmp/ohai2u_shef] using Chef::Provider::File
  [Fri, 15 Jan 2020 10:42:47 -0800] INFO: Creating file[/tmp/ohai2u_shef] at /tmp/ohai2u_shef
    => true

chef-shell также может переключиться на тот же контекст, что и файлы атрибутов. Установите атрибут с помощью следующего синтаксиса:

chef:recipe_mode > attributes_mode
  chef:attributes > default[:hello] = "ohai2u-again"
    => "ohai2u-again"
  chef:attributes >

Вернитесь в контекст recipe_mode и используйте атрибуты:

chef:attributes > recipe_mode
    => :attributes
  chef:recipe_mode > file "/tmp/#{node.hello}"

Теперь снова запустите Chef Infra Client:

chef:recipe_mode > run_chef
  [Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: Processing file[/tmp/ohai2u_shef]
  [Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: file[/tmp/ohai2u_shef] using Chef::Provider::File
  [Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: Processing file[/tmp/ohai2u-again]
  [Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: file[/tmp/ohai2u-again] using Chef::Provider::File
  [Fri, 15 Jan 2020 10:53:22 -0800] INFO: Creating file[/tmp/ohai2u-again] at /tmp/ohai2u-again
    => true
  chef:recipe_mode >

Поскольку первый ресурс (file[/tmp/ohai2u_shef]) всё ещё находится в списке выполнения, он выполняется снова. И поскольку этот файл уже существует, Chef Infra Client не пытается его повторно создать. Наконец, файлы были созданы с помощью метода ls:

chef:recipe_mode > ls("/tmp").grep(/ohai/)
    => ["ohai2u-again", "ohai2u_shef"]
  Shell Tutorial

Получение конкретных узлов

Чтобы получить список узлов, используя рецепт с именем postfix, используйте search(:node,"recipe:postfix"). Чтобы получить список узлов, используя подрецепты с именем delivery, используйте chef-shell. Например:

search(:node, 'recipes:postfix\:\:delivery')

Примеры

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

Рецепт без точки останова

yum_key node['yum']['elrepo']['key'] do
  url  node['yum']['elrepo']['key_url']
  action :add
end

yum_repository 'elrepo' do
  description 'ELRepo.org Community Enterprise Linux Extras Repository'
  key node['yum']['elrepo']['key']
  mirrorlist node['yum']['elrepo']['url']
  includepkgs node['yum']['elrepo']['includepkgs']
  exclude node['yum']['elrepo']['exclude']
  action :create
end

Тот же рецепт с точками останова

В следующем примере имя каждой точки останова — произвольная строка.

breakpoint "before yum_key node['yum']['repo_name']['key']" do
  action :break
end

yum_key node['yum']['repo_name']['key'] do
  url  node['yum']['repo_name']['key_url']
  action :add
end

breakpoint "after yum_key node['yum']['repo_name']['key']" do
  action :break
end

breakpoint "before yum_repository 'repo_name'" do
  action :break
end

yum_repository 'repo_name' do
  description 'description'
  key node['yum']['repo_name']['key']
  mirrorlist node['yum']['repo_name']['url']
  includepkgs node['yum']['repo_name']['includepkgs']
  exclude node['yum']['repo_name']['exclude']
  action :create
end

breakpoint "after yum_repository 'repo_name'" do
  action :break
end

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

ресурс build_essential

Используйте ресурс build_essential для установки пакетов, необходимых для компиляции программного обеспечения C из исходного кода.

Новое в Chef Infra Client 14.0.

Синтаксис

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

build_essential 'name' do
  raise_if_unsupported      true, false # default value: false
  action                    Symbol # defaults to :install if not specified
end

где:

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

Без имени

Этот ресурс может быть без имени. Добавьте сам ресурс в свой рецепт, чтобы получить стандартное поведение:

build_essential

будет вести себя так же, как:

build_essential 'install tools'

Действия

У ресурса build_essential следующие действия:

:install

Установка пакетов build essential. (по умолчанию)

:nothing

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

:upgrade

Обновление инструментов Xcode CLI на узлах macOS. Новое в Chef Infra Client 16

Свойства

У ресурса build_essential следующие свойства:

raise_if_unsupported

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

Вызовите жёсткую ошибку на платформах, где этот ресурс не поддерживается.

Новое в Chef Infra Client 15.5

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

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

Примеры

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

Установка пакетов компиляции:

build_essential

Установка пакетов компиляции во время фазы компиляции:

build_essential 'Install compilation tools' do
  compile_time true
end

Обновление пакетов компиляции на системах macOS:

build_essential 'Install compilation tools' do
  action :upgrade
end

Ресурс cab_package

Используйте ресурс cab_package для установки или удаления пакетов Microsoft Windows cabinet (.cab).

Новое в Chef Infra Client 12.15.

Синтаксис

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

cab_package 'name' do
  options           String, Array
  package_name      String
  source            String # default value: The package name.
  timeout           String, Integer
  version           String
  action            Symbol # defaults to :install if not specified
end

где:

• cab_package — это ресурс.
• name — это имя, заданное для блока ресурса.
• action определяет шаги, которые Chef Infra Client предпримет, чтобы привести узел в желаемое состояние.
• options, package_name, source, timeout и version — это доступные свойства этого ресурса.

Действия

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

:install

Устанавливает пакет cabinet.

:nothing

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

:remove

Удаляет пакет cabinet.

Свойства

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

options

Тип Ruby: Строка, Массив

Одна (или несколько) дополнительных командных опций, передаваемые команде.

package_name

Тип Ruby: Строка

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

source

Тип Ruby: Строка | Значение по умолчанию: The package name.

Локальный путь к файлу или URL пакета CAB.

timeout

Тип Ruby: Строка, Целое число

Время ожидания (в секундах) до истечения времени ожидания.

version

Тип 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 Infra Client.

Уведомления

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

Примеры

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

Использование локального пути в источнике

cab_package 'Install .NET 3.5 sp1 via KB958488' do
  source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
  action :install
end

cab_package 'Remove .NET 3.5 sp1 via KB958488' do
  source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
  action :remove
end

Использование URL-адреса в источнике

cab_package 'Install .NET 3.5 sp1 via KB958488' do
  source 'https://s3.amazonaws.com/my_bucket/Windows6.1-KB958488-x64.cab'
  action :install
end

cab_package 'Remove .NET 3.5 sp1 via KB958488' do
  source 'https://s3.amazonaws.com/my_bucket/Temp\Windows6.1-KB958488-x64.cab'
  action :remove
end

ресурс chef_acl

Используйте ресурс chef_acl для взаимодействия с списками управления доступом (ACL), которые существуют на сервере Chef Infra.

Синтаксис

Синтаксис использования ресурса chef_acl в рецепте следующий:

chef_acl 'name' do
  attribute 'value' # see properties section below
  ...
  action :action # see actions section below
end

где:

• chef_acl сообщает Chef Infra Client использовать поставщик Chef::Provider::ChefAcl во время выполнения Chef Infra Client
• name — имя блока ресурса; когда свойство path не указано в рецепте, name также является именем Chef Infra Client.
• attribute — ноль или более свойств, доступных для этого ресурса
• action определяет, какие шаги выполнит Chef Infra Client для приведения узла к желаемому состоянию

Действия

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

:create

По умолчанию.

:nothing

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

Свойства

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

chef_server

URL сервера Chef Infra.

complete

Указывает, определяет ли этот ресурс полностью chef-клиент. При значении true все свойства, не указанные в этом ресурсе, будут сброшены до значений по умолчанию.

ignore_failure

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

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

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

path

Путь к каталогу в chef-repo, к которому применяется ACL. Например: nodes, nodes/*, nodes/my_node, */*, **, roles/base, data/secrets, cookbooks/apache2, /users/* и так далее.

raw_json

Данные Chef Infra Client в формате JSON. Например:

{
  "clientname": "client_name",
  "orgname": "org_name",
  "validator": false,
  "certificate": "-----BEGIN CERTIFICATE-----\n
                  ...
                  1234567890abcdefghijklmnopq\n
                  ...
                  -----END CERTIFICATE-----\n",
  "name": "node_name"
}

recursive

Используется для применения изменений к дочерним объектам. Используйте :on_change для применения изменений к дочерним объектам только при изменении родительского объекта. Установите в true, чтобы применить изменения даже если родительский объект не изменяется. Установите в false, чтобы предотвратить любые изменения. Значение по умолчанию: :on_change.

remove_rights

Используется для удаления прав. Например:

remove_rights :read, :users => 'jkeiser', :groups => [ 'admins', 'users' ]

или:

remove_rights [ :create, :read ], :users => [ 'jkeiser', 'adam' ]

или:

remove_rights :all, :users => [ 'jkeiser', 'adam' ]

rights

Используется для добавления прав. Синтаксис: :right, :right => 'user', :groups => [ 'group', 'group']. Например:

rights :read, :users => 'jkeiser', :groups => [ 'admins', 'users' ]

или:

rights [ :create, :read ], :users => [ 'jkeiser', 'adam' ]

или:

rights :all, :users => 'jkeiser'

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_client

Используйте ресурс chef_client для создания клиентов на вашем сервере Chef Infra изнутри кода кулинарии Chef Infra.

Синтаксис

Синтаксис использования ресурса chef_client в рецепте:

chef_client 'name' do
  attribute 'value' # see properties section below
  ...
  action :action # see actions section below
end

где:

• chef_client сообщает Chef Infra Client использовать поставщик Chef::Provider::ChefClient во время выполнения Chef Infra Client
• name — имя блока ресурсов; когда свойство name не указано в рецепте, name также является именем Chef Infra Client
• attribute — ноль (или более) доступных свойств этого ресурса
• action определяет шаги, которые Chef Infra Client предпримет для перевода узла в желаемое состояние

Действия

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

:create

По умолчанию. Используется для создания chef-клиента.

:delete

Используется для удаления chef-клиента.

:nothing

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

:regenerate_keys

Используется для перегенерации открытого ключа RSA для chef-клиента.

Свойства

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

admin

Указывает, является ли Chef Infra Client клиентом API.

chef_server

URL сервера Chef Infra.

complete

Указывает, определяет ли этот ресурс chef-клиента полностью. Когда true, все свойства, не указанные в этом ресурсе, будут сброшены до значений по умолчанию.

ignore_failure

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

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

name

Имя 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

output_key_format

Указывает формат открытого ключа. Возможные значения: pem, der или openssh. Значение по умолчанию: openssh.

output_key_path

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

raw_json

Chef Infra Client в формате JSON. Например:

{
  "clientname": "client_name",
  "orgname": "org_name",
  "validator": false,
  "certificate": "-----BEGIN CERTIFICATE-----\n
                  ...
                  1234567890abcdefghijklmnopq\n
                  ...
                  -----END CERTIFICATE-----\n",
  "name": "node_name"
}

source_key

Используется для копирования открытого или закрытого ключа, но применять другой format и password. Используется совместно с source_key_pass_phrase и source_key_path.

source_key_pass_phrase

Пароль к открытому ключу. Используется совместно с source_key и source_key_path.

source_key_path

Путь к открытому ключу. Используется совместно с source_key и source_key_pass_phrase.

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

validator

Указывает, является ли Chef Infra Client chef-валидатором.

Примеры

Этот ресурс не содержит примеров.

Ресурс chef_client_config

Используйте ресурс chef_client_config для создания файла client.rb в каталоге конфигурации Chef Infra Client. См. документацию по client.rb для получения дополнительной информации о параметрах, доступных в файле конфигурации client.rb.

Новое в Chef Infra Client 16.6.

Синтаксис

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

chef_client_config 'name' do
  additional_config              String
  chef_license                   String
  chef_server_url                String
  config_directory               String
  data_collector_server_url      String
  data_collector_token           String
  event_loggers                  Array # default value: []
  exception_handlers             Array # default value: []
  file_backup_path               String
  file_cache_path                String
  file_staging_uses_destdir      String
  formatters                     Array # default value: []
  ftp_proxy                      String
  group                          String
  http_proxy                     String
  https_proxy                    String
  log_level                      Symbol
  log_location                   String, Symbol
  minimal_ohai                   true, false
  named_run_list                 String
  no_proxy                       String, Array # default value: []
  node_name                      String
  ohai_disabled_plugins          Array # default value: []
  ohai_optional_plugins          Array # default value: []
  pid_file                       String
  policy_group                   String
  policy_name                    String
  policy_persist_run_list        true, false
  report_handlers                Array # default value: []
  ssl_verify_mode                Symbol, String
  start_handlers                 Array # default value: []
  user                           String
  action                         Symbol # defaults to :create if not specified
end

где:

• chef_client_config — ресурс.
• name — имя, данное блоку ресурсов.
• action определяет действия Chef Infra Client для перевода узла в желаемое состояние.
• additional_config, chef_license, chef_server_url, config_directory, data_collector_server_url, data_collector_token, event_loggers, exception_handlers, file_backup_path, file_cache_path, file_staging_uses_destdir, formatters, ftp_proxy, group, http_proxy, https_proxy, log_level, log_location, minimal_ohai, named_run_list, no_proxy, node_name, ohai_disabled_plugins, ohai_optional_plugins, pid_file, policy_group, policy_name, policy_persist_run_list, report_handlers, ssl_verify_mode, start_handlers и user — доступные свойства этого ресурса.

Действия

У ресурса chef_client_config следующие действия:

:create

Создаёт конфигурационный файл client.rb для настройки Chef Infra Client. (по умолчанию)

:nothing

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

:remove

Удаляет конфигурационный файл client.rb для настройки Chef Infra Client.

Свойства

У ресурса chef_client_config следующие свойства:

additional_config

Тип Ruby: Строка

Дополнительный текст, добавляемый в конец файла client.rb. Может использоваться для выполнения пользовательского Ruby-кода или добавления менее распространённых параметров конфигурации

chef_license

Тип Ruby: Строка Допустимые значения: "accept", "accept-no-persist", "accept-silent"

Принимайте Лицензионное соглашение Chef

chef_server_url

Тип Ruby: Строка | REQUIRED

URL сервера Chef Infra Server.

config_directory

Тип Ruby: Строка | Значение по умолчанию: `/etc/chef/` on *nix-like systems and `C:\chef\` on Windows

Директория для хранения файла client.rb.

data_collector_server_url

Тип Ruby: Строка

URL сбора данных (обычно automate) для отправки данных о узле, слиянии и соответствию.

Примечание

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

Новое в Chef Infra Client 17.8

data_collector_token

Тип Ruby: Строка

Токен сбора данных для взаимодействия с сервером сбора данных URL (Automate).

Примечание

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

Новое в Chef Infra Client 17.8

event_loggers

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

exception_handlers

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

Массив словарей, содержащих класс обработчика исключений и аргументы, которые нужно передать этому классу при инициализации. Словарь должен содержать ключи class и argument, где class — строка, а argument — массив строковых значений в кавычках. Например: [{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]

file_backup_path

Тип Ruby: Строка

Расположение, в котором хранятся резервные файлы. Если это значение пустое, резервные файлы хранятся в той же директории, что и целевой файл.

file_cache_path

Тип Ruby: Строка

Расположение, в котором хранятся файлы кулинарных книг (и другие временные данные) при синхронизации. Это значение также может использоваться в рецептах для загрузки файлов с помощью ресурса remote_file.

file_staging_uses_destdir

Тип Ruby: Строка

Способ размещения файлов (через временные файлы). При true, временные файлы создаются в директории, где будут храниться файлы. При false, временные файлы создаются в ENV['TMP']

formatters

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

Форматировщики протоколирования клиента, которые нужно загрузить.

ftp_proxy

Тип Ruby: Строка

Прокси-сервер для FTP-соединений.

group

Тип Ruby: Строка

Группа, которая должна владеть файлом client.rb и директорией конфигурации, если она должна быть создана.

Примечание

Директория конфигурации не будет создана, если она уже существует, что позволяет вам дополнительно контролировать настройку этой директории вне этого ресурса.

http_proxy

Тип Ruby: Строка

Прокси-сервер для HTTP-соединений.

https_proxy

Тип Ruby: Строка

Прокси-сервер для HTTPS-соединений.

log_level

Тип Ruby: Символ Допустимые значения: :auto, :debug, :fatal, :info, :trace, :warn

Уровень протоколирования, выполняемый Chef Infra Client.

log_location

Тип Ruby: Строка, Символ

Место сохранения логов. Может быть путём к файлу логов на диске :syslog, чтобы протоколировать в Syslog, :win_evt, чтобы протоколировать в журнал событий Windows, или 'STDERR'/'STDOUT', чтобы протоколировать в текстовые потоки *nix.

minimal_ohai

Тип Ruby: true, false

Запустить минимальный набор плагинов Ohai, предоставляющих данные, необходимые для выполнения встроенных ресурсов Chef Infra Client. Установка этого значения в true пропустит многие большие и трудоёмкие наборы данных, такие как cloud или packages. Установка этого значения в true может нарушить кулинарные книги, предполагающие наличие всех данных Ohai.

named_run_list

Тип Ruby: Строка

Конкретный именованный список выполнения, определённый в применённом Policyfile узла, который должен быть использован при запуске Chef Infra Client.

no_proxy

Тип Ruby: Строка, Массив | Значение по умолчанию: []

Список URL через запятую или массив URL, для которых не нужен прокси.

node_name

Тип Ruby: Строка | Значение по умолчанию: The `node.name` value reported by Chef Infra Client.

Имя узла. Эта конфигурация устанавливает значение node.name, используемое в кулинарных книгах, и значение client_name, используемое при аутентификации на сервере Chef Infra Server, чтобы определить, какую конфигурацию применить.

Примечание

По умолчанию эта конфигурация использует значение node.name, которое будет установлено во время загрузки. Жесткая кодировка этого значения в конфигурации client.rb избегает логики внутри Chef Infra Server, выполняющей DNS-поиски, и может завершиться неудачей в случае сбоя DNS. Чтобы пропустить это значение по умолчанию и вместо этого использовать встроенную логику Chef Infra Server, установите это свойство в nil

ohai_disabled_plugins

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

Плагины Ohai, которые должны быть отключены для ускорения выполнения Chef Infra Client и уменьшения размера данных узла, отправляемых в Chef Infra Client

ohai_optional_plugins

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

Необязательные плагины Ohai, которые следует включить, чтобы предоставить дополнительные данные Ohai для использования в кулинарных книгах.

pid_file

Тип Ruby: Строка

Расположение, в котором сохраняется идентификатор процесса (PID). Исполняемый файл, запущенный как демон, записывает PID в указанный файл.

policy_group

Тип Ruby: Строка

Имя policy group, которое существует на сервере Chef Infra Server. policy_name также должно быть указано при установке этого свойства.

policy_name

Тип Ruby: Строка

Имя политики, определённой в файле Policyfile.rb, как указано в настройке name. policy_group при установке этого свойства.

policy_persist_run_list

Тип Ruby: true, false

Переопределяет списки выполнения, определённые в Policyfile, с run_list, определённым на сервере Chef Infra Server.

Новое в Chef Infra Client 17.3

report_handlers

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

Массив словарей, содержащих класс обработчика отчётов и аргументы, которые нужно передать этому классу при инициализации. Словарь должен содержать ключи class и argument, где class — строка, а argument — массив строковых значений в кавычках. Например: [{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]

ssl_verify_mode

Тип Ruby: Символ, Строка Допустимые значения: :verify_none, :verify_peer

Установите режим проверки для HTTPS-запросов.

• Используйте :verify_none для отключения проверки сертификатов SSL.
• Используйте :verify_peer для проверки всех сертификатов SSL, включая подключения к серверу Chef Infra Server, подключения S3 и любые HTTPS-URL ресурсов remote_file, используемые в Chef Infra Client.

start_handlers

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

Массив словарей, содержащих класс обработчика отчётов и аргументы, которые нужно передать этому классу при инициализации. Словарь должен содержать ключи class и argument, где class — строка, а argument — массив строковых значений в кавычках. Например: [{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]

user

Тип Ruby: Строка

Пользователь, который должен владеть файлом client.rb и директорией конфигурации, если она должна быть создана.

Примечание

Директория конфигурации не будет создана, если она уже существует, что позволяет вам дополнительно контролировать настройку этой директории вне этого ресурса.

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

Ресурсы 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[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 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_client_config в рецептах:

Минимальная конфигурация клиента Chef Infra Client client.rb:

Абсолютно минимальной конфигурации, необходимой для связи узла с сервером Chef Infra Server, является URL-адрес сервера Chef Infra Server. Все остальные параметры конфигурации либо имеют значения на стороне сервера (файлы политики, роли, среды и т. д.), либо имеют значения по умолчанию, определяемые при запуске клиента.

chef_client_config 'Create client.rb' do
  chef_server_url 'https://chef.example.dmz'
end

Более сложная конфигурация клиента Chef Infra Client client.rb:

chef_client_config 'Create client.rb' do
  chef_server_url 'https://chef.example.dmz'
  log_level :info
  log_location :syslog
  http_proxy 'proxy.example.dmz'
  https_proxy 'proxy.example.dmz'
  no_proxy %w(internal.example.dmz)
end

Добавление дополнительного конфигурационного содержимого в client.rb:

Этот ресурс предназначен для предоставления общих параметров конфигурации. Некоторые параметры конфигурации отсутствуют, и некоторые пользователи могут захотеть использовать произвольный код Ruby в своей конфигурации. Для этого мы предлагаем свойство additional_config, которое можно использовать для добавления любой конфигурации или кода в конец файла client.rb. Также имейте в виду, что в каталоге конфигурации есть каталог client.d, где вы можете разместить дополнительные файлы .rb, содержащие параметры конфигурации. Их можно создавать с помощью ресурсов file или template в ваших кулинарных книгах по мере необходимости.

chef_client_config 'Create client.rb' do
  chef_server_url 'https://chef.example.dmz'
  additional_config <<~CONFIG
    # Extra config code to safely load a gem into the client run.
    # Since the config is Ruby you can run any Ruby code you want via the client.rb.
    # It's a great way to break things, so be careful
    begin
      require 'aws-sdk'
    rescue LoadError
      Chef::Log.warn "Failed to load aws-sdk."
    end
  CONFIG
end

Настройка двух обработчиков отчетов в client.rb:

chef_client_config 'Create client.rb' do
  chef_server_url 'https://chef.example.dmz'
  report_handlers [
    {
     'class' => 'ReportHandler1Class',
     'arguments' => ["'FirstArgument'", "'SecondArgument'"],
    },
    {
     'class' => 'ReportHandler2Class',
     'arguments' => ["'FirstArgument'", "'SecondArgument'"],
    },
  ]
end

Отчет напрямую в точку конечного сбора данных Chef Automate.

chef_client_config 'Create client.rb' do
  chef_server_url 'https://chef.example.dmz'
  data_collector_server_url 'https://automate.example.dmz'
  data_collector_token 'TEST_TOKEN_TEST'
end

Ресурс chef_client_cron

Используйте ресурс chef_client_cron для настройки запуска Chef Infra Client в качестве задачи cron. Этот ресурс также создаст указанный каталог журналов, если он еще не существует.

Новинка в Chef Infra Client 16.0.

Синтаксис

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

chef_client_cron 'name' do
  accept_chef_license      true, false # default value: false
  append_log_file          true, false # default value: true
  chef_binary_path         String # default value: "/opt/chef/bin/chef-client"
  comment                  String
  config_directory         String # default value: "/etc/chef"
  daemon_options           Array # default value: []
  day                      Integer, String # default value: "*"
  environment              Hash # default value: {}
  hour                     Integer, String # default value: "*"
  job_name                 String # default value: "chef-client"
  log_directory            String
  log_file_name            String # default value: "client.log"
  mailto                   String
  minute                   Integer, String # default value: "0,30"
  month                    Integer, String # default value: "*"
  nice                     Integer, String
  splay                    Integer, String # default value: 300
  user                     String # default value: "root"
  weekday                  Integer, String # default value: "*"
  action                   Symbol # defaults to :add if not specified
end

где:

• chef_client_cron — это ресурс.
• name — это имя, данное блоку ресурса.
• action определяет, какие шаги Chef Infra Client предпримет для перевода узла в желаемое состояние.
• accept_chef_license, append_log_file, chef_binary_path, comment, config_directory, daemon_options, day, environment, hour, job_name, log_directory, log_file_name, mailto, minute, month, nice, splay, user и weekday — доступные свойства этого ресурса.

Действия

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

:add

Добавить задачу cron для запуска Chef Infra Client. (по умолчанию)

:nothing

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

:remove

Удалить задачу cron для Chef Infra Client.

Свойства

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

accept_chef_license

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

Принять Соглашение о лицензии и услугах онлайн-мастера Chef. См. https://www.chef.io/online-master-agreement

append_log_file

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

Добавить в файл журнала, а не перезаписывать файл журнала при каждом запуске.

chef_binary_path

Тип Ruby: Строка | Значение по умолчанию: /opt/chef/bin/chef-client

Путь к исполняемому файлу chef-client.

comment

Тип Ruby: Строка

Комментарий для вставки в файл cron.d.

config_directory

Тип Ruby: Строка | Значение по умолчанию: /etc/chef

Путь к каталогу конфигурации.

daemon_options

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

Массив опций для передачи команде chef-client.

day

Тип Ruby: Целое число, строка | Значение по умолчанию: *

День месяца, в который Chef Infra Client должен запускаться (1-31) или шаблон cron, например, ‘1,7,14,21,28’.

environment

Тип Ruby: Словарь | Значение по умолчанию: {}

Словарь, содержащий дополнительные произвольные переменные среды, в которых будет выполняться задача cron, в формате ({'ENV_VARIABLE' => 'VALUE'}).

hour

Тип Ruby: Целое число, строка | Значение по умолчанию: *

Час, в который Chef Infra Client должен запускаться (0-23) или шаблон cron, например, ‘0,12’.

job_name

Тип Ruby: Строка | Значение по умолчанию: chef-client

Имя задачи cron, которую нужно создать.

log_directory

Тип Ruby: Строка | Значение по умолчанию: /Library/Logs/Chef on macOS and /var/log/chef otherwise

Путь к каталогу, в котором необходимо создать файл журнала.

log_file_name

Тип Ruby: Строка | Значение по умолчанию: client.log

Имя файла журнала, который нужно использовать.

mailto

Тип Ruby: Строка

Адрес электронной почты, на который нужно отправлять сообщения об ошибках задач cron.

minute

Тип Ruby: Целое число, строка | Значение по умолчанию: 0,30

Минута, в которую Chef Infra Client должен запускаться (0-59) или шаблон cron, например, ‘0,30’.

month

Тип Ruby: Целое число, строка | Значение по умолчанию: *

Месяц в году, в который Chef Infra Client должен запускаться (1-12, jan-dec или *).

nice

Тип Ruby: Целое число, строка

Приоритет процесса для запуска процесса chef-client. Значение -20 — наивысший приоритет, 19 — наименьший приоритет.

Новое в Chef Infra Client 16.5

splay

Тип Ruby: Целое число, строка | Значение по умолчанию: 300

Случайное число секунд от 0 до X, которое добавляется к интервалу, чтобы все команды chef-client не выполнялись одновременно.

user

Тип Ruby: Строка | Значение по умолчанию: root

Имя пользователя, от имени которого запускается Chef Infra Client.

weekday

Тип Ruby: Целое число, строка | Значение по умолчанию: *

День недели, в который Chef Infra Client должен запускаться (0-7, mon-sun или *), где воскресенье соответствует как 0, так и 7.

Функциональность общих ресурсов

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