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, но может использовать как интерпретатор 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
  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. При указании чего-либо, кроме :i386 для 32-разрядного процесса, возникает исключение. Возможные значения: :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: Hash
Хеш-таблица переменных среды в формате ({'ENV_VARIABLE' => 'VALUE'}). Примечание: эти переменные должны существовать для успешного выполнения команды.

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

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

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

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

© 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/