Ресурс batch

Изменить эту страницу в репозитории Chef

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

Используйте ресурс batch для выполнения пакетного сценария с помощью интерпретатора cmd.exe в Windows. Ресурс batch создает и выполняет временный файл (аналогично поведению ресурса script), а не выполняет команду в строке. Команды, выполняемые с помощью этого ресурса, (по своей природе) не являются идемпотентными, поскольку они обычно уникальны для среды, в которой они выполняются. Используйте 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 для приведения узла в желаемое состояние.
• architecture, code, command, creates, cwd, flags, group, guard_interpreter, interpreter, returns, timeout, user, password и domain — это свойства этого ресурса с указанным типом Ruby. См. раздел «Свойства» ниже для получения дополнительной информации обо всех свойствах, которые могут использоваться с этим ресурсом.

Действия

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

:nothing

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

:run

Запуск пакетного файла.

Свойства

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

architecture

Тип Ruby: Symbol

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

code

Тип Ruby: String | REQUIRED

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

command

Тип Ruby: String, Array

Имя команды для выполнения.

creates

Тип Ruby: String

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

cwd

Тип Ruby: String

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

flags

Тип Ruby: String

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

group

Тип Ruby: String, Integer

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

guard_interpreter

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

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

interpreter

Тип Ruby: String

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

returns

Тип Ruby: Integer, Array | Значение по умолчанию: 0

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

timeout

Тип Ruby: Integer, Float | Значение по умолчанию: 3600

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

user

Тип Ruby: String

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

password

Тип Ruby: String

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

domain

Тип Ruby: String

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

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

Ресурсы 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: Integer | Значение по умолчанию: 0

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

retry_delay

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

Задержка повтора (в секундах).

sensitive

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

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

Уведомления

notifies

Тип Ruby: Symbol, 'Chef::Resource[String]'

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

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

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

:before

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

:delayed

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

:immediate, :immediately

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

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

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

subscribes

Тип Ruby: Symbol, '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.

Примеры

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