Настройка интерпретатора

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

Требования к путям:

• Windows: поддерживаются как абсолютные пути (C:\Program Files\PowerShell\7\pwsh.exe), так и относительные пути/имена исполняемых файлов (pwsh, выполняется поиск в PATH)
• Linux/macOS: поддерживаются только абсолютные пути (/usr/bin/pwsh, /opt/microsoft/powershell/7/pwsh)

Поведение по умолчанию:

Интерпретатор по умолчанию определяется строкой shebang модуля и целевой платформой:

• Windows:

  • Модули со строкой shebang #!powershell → C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe (Windows PowerShell 5.1)
  • Модули со строкой shebang #!/usr/bin/pwsh → pwsh (PowerShell 7, выполняется поиск в PATH)
  • Это обеспечивает обратную совместимость с существующими модулями и позволяет при желании перейти на PowerShell 7

• Linux/macOS:

  • Для всех модулей по умолчанию используется /usr/bin/pwsh (PowerShell 7) независимо от строки shebang

Примеры:

Переменную можно задать для play или задачи, как показано ниже:

# Use PowerShell 7 on Windows (relative path)
- hosts: windows_servers
  vars:
    ansible_pwsh_interpreter: pwsh

# Use PowerShell 7 on Windows (absolute path)
- hosts: windows_servers
  vars:
    ansible_pwsh_interpreter: C:\Program Files\PowerShell\7\pwsh.exe

# Use PowerShell 7 on Linux (absolute path required)
- hosts: linux_servers
  vars:
    ansible_pwsh_interpreter: /usr/bin/pwsh

# Use custom PowerShell installation on Linux
- hosts: linux_servers
  vars:
    ansible_pwsh_interpreter: /opt/microsoft/powershell/7/pwsh

# Use Windows PowerShell 5.1 explicitly on Windows
- hosts: windows_legacy
  vars:
    ansible_pwsh_interpreter: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

При задании переменной в ini-файле инвентаризации значение следует заключать в кавычки, если оно содержит пробелы и указано в объявлении хоста, но не заключать в кавычки, если оно задано отдельно. Например:

[windows]
# Quotes required for host variable since it contains spaces
win-host  ansible_pwsh_interpreter="C:\Program Files\PowerShell\7\pwsh.exe"

[windows:vars]
# Quotes not required for group variable since it is the only variable on the line
ansible_pwsh_interpreter=C:\Program Files\PowerShell\7\pwsh.exe

Поддержка shebang в модулях

Модули PowerShell задают используемый интерпретатор с помощью строк shebang, которые определяют версию PowerShell по умолчанию, если переменная ansible_pwsh_interpreter не задана. Официально поддерживаются два формата shebang для модулей PowerShell:

#!powershell
#!/usr/bin/pwsh

• #!powershell: обеспечивает совместимость с Windows PowerShell 5.1

  • Windows: по умолчанию используется powershell.exe (5.1)
  • Linux/macOS: по-прежнему используется /usr/bin/pwsh (кроссплатформенный PowerShell 7)
  • Используйте для модулей, которые должны работать на старых системах Windows без PowerShell 7

• #!/usr/bin/pwsh: предназначен для PowerShell 7

  • Windows: по умолчанию используется pwsh.exe (PowerShell 7)
  • Linux/macOS: используется /usr/bin/pwsh (PowerShell 7)
  • Используйте для модулей, которым нужны возможности PowerShell 7+ или кроссплатформенная совместимость

На платформах, отличных от Windows, для модулей PowerShell можно использовать пользовательскую строку shebang, если указанное в ней имя файла является pwsh, однако такой вариант официально не поддерживается и не прошёл тщательное тестирование. Для обеспечения единообразного поведения на платформах, отличных от Windows, рекомендуется использовать #!/usr/bin/pwsh и задавать используемый интерпретатор с помощью переменной ansible_pwsh_interpreter.

Кроссплатформенные модули PowerShell

Поскольку модули PowerShell могут выполняться как в Windows, так и на других платформах, есть несколько приёмов, которые упрощают создание кроссплатформенных модулей, совместимых и с Windows PowerShell 5.1, и с PowerShell 7:

Проверяйте платформу:

#!powershell

#AnsibleRequires -CSharpUtil Ansible.Basic

$spec = @{
    options = @{
        path = @{ type = "str"; required = $true }
    }
}

$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)

# Set $IsWindows for PowerShell 5.1 to simplify future platform checks.
if (-not (Get-Variable -Name IsWindows -ErrorAction Ignore)) {
    $IsWindows = $true
}

# Check platform using PowerShell 7 automatic variables
if ($IsWindows) {
    # Windows-specific logic
} elseif ($IsLinux) {
    # Linux-specific logic
} elseif ($IsMacOS) {
    # macOS-specific logic
}

# Check if running on WinPS or Pwsh 7
if ($IsCoreCLR) {
    # PowerShell 7 specific logic
} else {
    # Windows PowerShell 5.1 specific logic
}

if ($PSVersionTable.PSVersion -lt '6.0') {
    # Windows PowerShell 5.1 specific logic
} else {
    # PowerShell 7 specific logic
}

Избегайте командлетов и API, специфичных для Windows:

• Многие командлеты Windows (например, Get-WmiObject, Get-ComputerInfo) недоступны на платформах, отличных от Windows
• По возможности используйте кроссплатформенные альтернативы
• Используйте API .NET, поддерживаемые на целевых платформах
• Проводите тестирование на нескольких платформах
• Чётко указывайте требования к платформе в документации модуля
• При необходимости используйте проверки платформы для условного выполнения платформозависимых участков кода

Проверка конфигурации

Проще всего узнать, какую версию PowerShell использует Ansible, запустив ansible.windows.win_powershell для вывода значения переменной $PSVersionTable.PSVersion:

- name: Display PowerShell version info
  ansible.windows.win_powershell:
    script: $PSVersionTable.PSVersion.ToString()
  register:
    ps_version: _task.result.output[0]

- debug:
    var: ps_version

По умолчанию модуль ansible.windows.win_powershell выполняется в том же контексте интерпретатора, что и остальные модули PowerShell, поэтому с его помощью можно проверить любые сведения о среде PowerShell на целевом узле, например установленные модули, доступные командлеты и многое другое.

Имя конфигурации PSRP

При использовании подключаемого модуля соединения ansible.builtin.psrp соответствие конфигурации сеанса PSRemoting выбранному интерпретатору PowerShell значительно повышает производительность.

Если конфигурация сеанса PSRemoting не соответствует интерпретатору PowerShell, заданному переменной ansible_pwsh_interpreter, PSRP вынужден запускать новый процесс PowerShell для каждой задачи. Это приводит к дополнительным накладным расходам и замедляет выполнение playbook. Если конфигурация сеанса соответствует интерпретатору, модули выполняются непосредственно в нужной среде PowerShell без запуска новых процессов.

Настройка:

Используйте переменную ansible_psrp_configuration_name, чтобы указать конфигурацию сеанса PowerShell:

• Microsoft.PowerShell (по умолчанию): используется Windows PowerShell 5.1
• PowerShell.7: используется PowerShell 7

PowerShell 7 обычно регистрирует конфигурацию сеанса PowerShell.7 во время установки, если выбран соответствующий параметр, либо при запуске Enable-PSRemoting из интерпретатора PowerShell 7.

Пример для PowerShell 7:

[windows:vars]
ansible_connection=psrp
ansible_pwsh_interpreter=C:\Program Files\PowerShell\7\pwsh.exe
ansible_psrp_configuration_name=PowerShell.7

Проверка конфигураций сеансов:

Чтобы просмотреть доступные конфигурации сеансов на узле Windows:

Get-PSSessionConfiguration | Select-Object Name, PSVersion