powershell_script Ресурс

Эта страница сгенерирована из исходного кода Chef Infra Client. Чтобы предложить изменение, отредактируйте файл powershell_script.rb и отправьте запрос на вытягивание в репозиторий Chef Infra Client.

Все страницы ресурсов Infra

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

Ресурс 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
  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, timeout, и user — это доступные свойства этого ресурса.

Действия

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

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

Свойства

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

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

code: Тип Ruby: Строка | REQUIRED
Строка кода в кавычках, подлежащая выполнению.

command: Тип Ruby: Строка, массив | Значение по умолчанию: The resource block's name
Необязательное свойство для установки команды, подлежащей выполнению, если она отличается от имени блока ресурса.

convert_boolean_return

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

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

При установке общего атрибута 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: Строка
Препятствует созданию командой файла, если такой файл уже существует.

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

domain

Тип Ruby: Строка

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

Новое в Chef Client 12.21

elevated

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

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

Новое в Chef Client 13.3

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

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

group: Тип Ruby: Строка, целое число
Имя или идентификатор группы, которые должны быть изменены перед запуском команды.

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

input

Тип Ruby: Строка

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

Новое в Chef Infra Client 16.2

interpreter: Тип Ruby: Строка | Значение по умолчанию: powershell Разрешённые значения: "powershell", "pwsh"
Тип интерпретатора, powershell или pwsh (PowerShell Core)

live_stream: Тип Ruby: true, false | Значение по умолчанию: false
Отправить вывод команды, запущенной этим блоком ресурса execute, в поток событий Chef Infra Client.

password

Тип Ruby: Строка

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

Новое в Chef Client 12.21

returns: Тип Ruby: Целое число, массив | Значение по умолчанию: 0
Возвращаемое значение команды. Может быть массивом допустимых значений. Возникает исключение, если возвращаемое значение(я) не совпадают.

timeout: Тип Ruby: Целое число, строка, число с плавающей точкой | Значение по умолчанию: 3600
Время ожидания команды в секундах перед истечением времени.

user: Тип Ruby: Строка, целое число
Имя пользователя идентификатора пользователя, с которым будет запущен новый процесс. Имя пользователя может быть указано с доменным именем, например domain\user или user@my.dns.domain.com в формате Universal Principal Name (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 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, которые генерируют ошибку, если другой ресурс не существует.

: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

Оценивание на true и/или false

Используйте атрибут 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

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs.chef.io/resources/powershell_script/