powershell_script Ресурс

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

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

Используйте ресурс powershell_script для выполнения скрипта с использованием интерпретатора Windows PowerShell, аналогично тому, как используются ресурсы bash, csh, perl, python и ruby. powershell_script специфичен для платформы Microsoft Windows, но может использовать как интерпретатор Windows PowerShell, так и интерпретатор PowerShell Core (pwsh), начиная с Chef Infra Client 16.6 и выше.

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

Синтаксис

Блок ресурсов powershell_script выполняет пакетный скрипт с использованием интерпретатора Windows PowerShell. Например, запись в интерполированный путь:

powershell_script 'write-to-interpolated-path' do
  code <<-EOH
  $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
  $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
  $stream.close()
  EOH
end

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

powershell_script 'name' do
  code                        String
  command                     String, Array # default value: 'name' unless specified
  convert_boolean_return      true, false # default value: false
  creates                     String
  cwd                         String
  domain                      String
  elevated                    true, false # default value: false
  environment                 Hash
  flags                       String
  group                       String, Integer
  input                       String
  interpreter                 String # default value: "powershell"
  live_stream                 true, false # default value: false
  password                    String
  returns                     Integer, Array # default value: 0
  sensitive                   true, false
  timeout                     Integer, String, Float # default value: 3600
  user                        String, Integer
  action                      Symbol # defaults to :run if not specified
end

где:

• powershell_script это ресурс.
• name это имя, данное блоку ресурсов.
• action определяет, какие действия выполнит Chef Infra Client, чтобы привести узел в желаемое состояние.
• code, command, convert_boolean_return, creates, cwd, domain, elevated, environment, flags, group, input, interpreter, live_stream, password, returns, sensitive, timeout и user это свойства, доступные для этого ресурса.

Действия

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

:nothing

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

:run

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

Свойства

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

architecture

Тип Ruby: Symbol

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

code

Тип Ruby: String | REQUIRED

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

command

Тип Ruby: String, Array | Значение по умолчанию: The resource block's name

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

convert_boolean_return

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

Возвращает 0, если последняя строка команды оценивается как истина, или возвращает 1, если последняя строка оценивается как ложь.

Когда общий атрибут guard_interpreter установлен в :powershell_script, строковая команда будет оцениваться так, как будто это значение было установлено в true. Это связано с тем, что поведение этого атрибута аналогично значению выражения "$?", распространенного в UNIX-интерпретаторах. Например, это:

powershell_script 'make_safe_backup' do
  guard_interpreter :powershell_script
  code 'cp ~/data/nodes.json ~/data/nodes.bak'
  not_if 'test-path ~/data/nodes.bak'
end

аналогично:

bash 'make_safe_backup' do
  code 'cp ~/data/nodes.json ~/data/nodes.bak'
  not_if 'test -e ~/data/nodes.bak'
end

creates

Тип Ruby: String

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

cwd

Тип Ruby: String

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

domain

Тип Ruby: String

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

Новое в Chef Client 12.21

elevated

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

Определяет, будет ли скрипт выполняться с повышенными правами для обхода контроля учетных записей пользователей (UAC), который интерактивно блокирует процесс. Это приведет к запуску процесса под учетной записью пакетного входа вместо интерактивного входа. Пользователь, запускающий chef-client, должен иметь права «Замена токена уровня процесса» и «Регулировка квот памяти для процесса». Пользователь, запускающий команду, должен иметь разрешение «Вход в качестве пакетной задачи». Поскольку это требует входа в систему, необходимы свойства user и password.

Новое в Chef Client 13.3

environment

Тип Ruby: Hash

Хэш переменных среды в формате ({‘ENV_VARIABLE’ => ‘VALUE’}).

flags

Тип Ruby: String

Строка, передаваемая в команду Windows PowerShell. Значение по умолчанию (Windows PowerShell 3.0+): -NoLogo, -NonInteractive, -NoProfile, -ExecutionPolicy Bypass, -InputFormat None.

group

Тип Ruby: String, Integer

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

guard_interpreter

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

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

input

Тип Ruby: String

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

Новое в Chef Infra Client 16.2

interpreter

Тип Ruby: String | Значение по умолчанию: powershellДопустимые значения: "powershell", "pwsh"

Тип интерпретатора, powershell или pwsh (PowerShell Core)

live_stream

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

Отправляет вывод команды, выполняемой этим блоком ресурса execute, в поток событий Chef Infra Client.

password

Тип Ruby: String

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

Новое в Chef Client 12.21

returns

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

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

timeout

Тип Ruby: Integer, Float

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

user

Тип Ruby: String

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

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

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

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

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

compile_time

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

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

ignore_failure

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

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

retries

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

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

retry_delay

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

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

sensitive

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

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

Уведомления

notifies

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

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

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

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

:before

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

:delayed

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

:immediate, :immediately

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

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

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

subscribes

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

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

Обратите внимание, что subscribes не применяет указанное действие к ресурсу, на который он подписывается — например:

file '/etc/nginx/ssl/example.crt' do
  mode '0600'
  owner 'root'
end

service 'nginx' do
  subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end

В этом случае свойство subscribes перезагружает службу nginx всякий раз, когда файл сертификата, расположенный в /etc/nginx/ssl/example.crt, обновляется. subscribes не вносит никаких изменений в сам файл сертификата, а просто прослушивает изменения файла и выполняет действие :reload для своего ресурса (в данном примере nginx) при обнаружении изменений.

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

Таймер указывает момент выполнения уведомления во время работы Chef Infra 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.

Примеры

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

Запись в интерполированный путь

powershell_script 'write-to-interpolated-path' do
  code <<-EOH
  $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
  $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
  $stream.close()
  EOH
end

Изменение рабочей директории

powershell_script 'cwd-then-write' do
  cwd Chef::Config[:file_cache_path]
  code <<-EOH
  $stream = [System.IO.StreamWriter] "C:/powershell-test2.txt"
  $pwd = pwd
  $stream.WriteLine("This is the contents of: $pwd")
  $dirs = dir
  foreach ($dir in $dirs) {
    $stream.WriteLine($dir.fullname)
  }
  $stream.close()
  EOH
end

Изменение рабочей директории в Microsoft Windows

powershell_script 'cwd-to-win-env-var' do
  cwd '%TEMP%'
  code <<-EOH
  $stream = [System.IO.StreamWriter] "./temp-write-from-chef.txt"
  $stream.WriteLine("chef on windows rox yo!")
  $stream.close()
  EOH
end

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

powershell_script 'read-env-var' do
  cwd Chef::Config[:file_cache_path]
  environment ({'foo' => 'BAZ'})
  code <<-EOH
  $stream = [System.IO.StreamWriter] "./test-read-env-var.txt"
  $stream.WriteLine("FOO is $env:foo")
  $stream.close()
  EOH
end

Оценивать на истинность и/или ложность

Используйте атрибут convert_boolean_return, чтобы вызывать исключение при выполнении определённых условий. Например, следующие фрагменты будут работать без ошибок:

powershell_script 'false' do
  code '$false'
end

и:

powershell_script 'true' do
  code '$true'
end

в то время как следующее вызовет исключение:

powershell_script 'false' do
  convert_boolean_return true
  code '$false'
end

Использование атрибута флагов

powershell_script 'Install IIS' do
  code <<-EOH
  Import-Module ServerManager
  Add-WindowsFeature Web-Server
  EOH
  flags '-NoLogo, -NonInteractive, -NoProfile, -ExecutionPolicy Unrestricted, -InputFormat None, -File'
  guard_interpreter :powershell_script
  not_if '(Get-WindowsFeature -Name Web-Server).Installed'
end

Переименование компьютера, присоединение к домену, перезагрузка

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

reboot 'Restart Computer' do
  action :nothing
end

powershell_script 'Rename and Join Domain' do
  code <<-EOH
    ...your rename and domain join logic here...
  EOH
  not_if <<-EOH
    $ComputerSystem = gwmi win32_computersystem
    ($ComputerSystem.Name -like '#{node['some_attribute_that_has_the_new_name']}') -and
      $ComputerSystem.partofdomain)
  EOH
  notifies :reboot_now, 'reboot[Restart Computer]', :immediately
end

где:

• Блок ресурса powershell_script переименовывает компьютер и подключается к домену
• Ресурс reboot перезапускает компьютер
• Защита not_if предотвращает выполнение скрипта Windows PowerShell, когда настройки защиты not_if соответствуют желаемому состоянию
• Инструкция notifies указывает блоку ресурса reboot на выполнение, если блок powershell_script был выполнен во время работы Chef Infra Client

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

Примечание: Когда 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
powershell_script 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "username"
 password "password"
end

# Passing username and domain
powershell_script '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
powershell_script '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
powershell_script 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "username@domain-name"
 password "password"
end

# Work around User Access Control (UAC)
powershell_script 'mkdir test_dir' do
 code "mkdir test_dir"
 cwd Chef::Config[:file_cache_path]
 user "username"
 password "password"
 elevated true
end