ansible.windows.win_powershell – Run PowerShell scripts
Note
This plugin is part of the ansible.windows collection (version 1.7.3).
You might already have this collection installed if you are using the ansible
package. It is not included in ansible-core
. To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_powershell
.
New in version 1.5.0: of ansible.windows
Synopsis
- Runs a PowerShell script and outputs the data in a structured format.
- Use ansible.windows.win_command or ansible.windows.win_shell to run a tranditional PowerShell process with stdout, stderr, and rc results.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
arguments list / elements=string | A list of arguments to pass to executable when running a script in another PowerShell process. These are not arguments to pass to script, use parameters for that purpose. | |
chdir string | The PowerShell location to set when starting the script. This can be a location in any of the PowerShell providers. The default location is dependent on many factors, if relative paths are used then set this option. | |
creates string | A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. | |
depth integer | Default: 2 | How deep the return values are serialized for result , output , and information[x].message_data .Setting this to a higher value can dramatically increase the amount of data that needs to be returned. |
error_action string |
| The $ErrorActionPreference to set before executing script.silently_continue will ignore any errors and exceptions raised.continue is the default behaviour in PowerShell, errors are present in the error return value but only terminating exceptions will stop the script from continuing and set it as failed.stop will treat errors like exceptions, will stop the script and set it as failed. |
executable string | A custom PowerShell executable to run the script in. When not defined the script will run in the current module PowerShell interpreter. Both the remote PowerShell and the one specified by executable must be running on PowerShell v5.1 or newer. Setting this value may change the values returned in the output return value depending on the underlying .NET type. | |
parameters dictionary | Parameters to pass into the script as key value pairs. The key corresponds to the parameter name and the value is the value for that parameter. | |
removes string | A path or path filter pattern; when the referenced path does not exist on the target host, the task will be skipped. | |
script string / required | The PowerShell script to run. |
Notes
Note
- The module is set as failed when a terminating exception is throw, or
error_action=stop
and a normal error record is raised. - The output values are processed using a custom filter and while it mostly matches the
ConvertTo-Json
result the following value types are different. -
DateTime
will be an ISO 8601 string in UTC,DateTimeOffset
will have the offset as specified by the value. -
Enum
will contain a dictionary withType
,String
,Value
being the type name, string representation and raw integer value respectively. -
Type
will contain a dictionary withName
,FullName
,AssemblyQualifiedName
,BaseType
being the type name, the type name including the namespace, the full assembly name the type was defined in and the base type it derives from. - The script has access to the
$Ansible
variable where it can setResult
,Changed
,Failed
, or accessTmpdir
. -
$Ansible.Result
is a value that is returned back to the controller as is. -
$Ansible.Changed
can be set totrue
orfalse
to reflect whether the module made a change or not. By default this is set totrue
. -
$Ansible.Failed
can be set totrue
if the script wants to return the failure back to the controller. -
$Ansible.Tmpdir
is the path to a temporary directory to use as a scratch location that is cleaned up after the module has finished. - Any host/console output like
Write-Host
or[Console]::WriteLine
is not considered an output object, they are returned as a string in host_out and host_err. - The module will skip running the script when in check mode unless the script defines
[CmdletBinding(SupportsShouldProcess
]).
See Also
See also
- ansible.windows.win_command
-
The official documentation on the ansible.windows.win_command module.
- ansible.windows.win_shell
-
The official documentation on the ansible.windows.win_shell module.
Examples
- name: Run basic PowerShell script
ansible.windows.win_powershell:
script: |
echo "Hello World"
- name: Run PowerShell script with parameters
ansible.windows.win_powershell:
script: |
[CmdletBinding()]
param (
[String]
$Path,
[Switch]
$Force
)
New-Item -Path $Path -ItemType Direcotry -Force:$Force
parameters:
Path: C:\temp
Force: true
- name: Run PowerShell script that modifies the module changed result
ansible.windows.win_powershell:
script: |
if (Get-Service -Name test -ErrorAction SilentlyContinue) {
Remove-Service -Name test
}
else {
$Ansible.Changed = $false
}
- name: Run PowerShell script in PowerShell 7
ansible.windows.win_powershell:
script: |
$PSVersionTable.PSVersion.Major
executable: pwsh.exe
arguments:
- -ExecutionPolicy
- ByPass
register: pwsh_output
failed_when:
- pwsh_output.output[0] != 7
- name: Run code in check mode
ansible.windows.win_powershell:
script: |
[CmdletBinding(SupportsShouldProcess)]
param ()
# Use $Ansible to detect check mode
if ($Ansible.CheckMode) {
echo 'running in check mode'
}
else {
echo 'running in normal mode'
}
# Use builtin ShouldProcess (-WhatIf)
if ($PSCmdlet.ShouldProcess('target')) {
echo 'also running in normal mode'
}
else {
echo 'also running in check mode'
}
check_mode: yes
- name: Return a failure back to Ansible
ansible.windows.win_powershell:
script: |
if (Test-Path C:\bad.file) {
$Ansible.Failed = $true
}
- name: Define when the script made a change or not
ansible.windows.win_powershell:
script: |
if ((Get-Item WSMan:\localhost\Service\Auth\Basic).Value -eq 'true') {
Set-Item WSMan:\localhost\Service\Auth\Basic -Value false
}
else {
$Ansible.Changed = $true
}
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description | ||
---|---|---|---|---|
debug list / elements=string | always | A list of warning messages created by the script. Debug messages only appear when $DebugPreference = 'Continue' .Sample: ['debug record'] | ||
error list / elements=dictionary | always | A list of error records created by the script. | ||
category_info dictionary | success | More information about the error record. | ||
activity string | always | Description of the operation which encountered the error. Sample: Write-Error | ||
category string | always | The category name of the error record. Sample: NotSpecified | ||
category_id integer | always | The integer representation of the category. | ||
reason string | always | Description of the error. Sample: WriteErrorException | ||
target_name string | always | Description of the target object. Can be an empty string if no target was specified. Sample: C:\Windows | ||
target_type string | always | Description of the type of the target object. Can be an empty string if no target object was specified. Sample: String | ||
error_details dictionary | success | Additional details about an ErrorRecord. Can be null if there are not additional details. | ||
message string | always | Message for the error record. Sample: Specific error message | ||
recommended_action string | always | Recommended action in the even that this error occurs. This is empty unless the code which generates the error adds this explicitly. Sample: Delete file | ||
exception dictionary | success | Details about the exception behind the error record. | ||
help_link string | always | A link to the help details for the exception. May not be set as it's dependent on whether the .NET exception class provides this info. Sample: http://docs.ansible.com/ | ||
hresult integer | always | The signed integer assigned to this exception. May not be set as it's dependent on whether the .NET exception class provides this info. Sample: -1 | ||
inner_exception dictionary | always | The inner exception details if there is one present. The dict contains the same keys as a normal exception. | ||
message string | always | The exception message. Sample: The method ran into an error | ||
source string | always | Name of the application or object that causes the error. This may be an empty string as it's dependent on the code that raises the exception. Sample: C:\Windows | ||
type string | always | The full .NET type of the Exception class. Sample: System.Exception | ||
fully_qualified_error_id string | always | The unique identifier for the error condition May be null if no id was specified when the record was created. Sample: ParameterBindingFailed | ||
output string | always | The formatted error record message as typically seen in a PowerShell console. Sample: Write-Error "error" : error + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException | ||
pipeline_iteration_info list / elements=integer | always | The status of the pipeline when this record was created. The values are 0 index based. Each element entry represents the command index in a pipeline statement. The value of each element represents the pipeline input idx in that command. For Example 'C:\Windows', 'C:\temp' | Get-ChildItem | Get-Item , [1, 2, 9] represents an error occured with the 2nd output, 3rd, and 9th output of the 1st, 2nd, and 3rd command in that pipeline respectively.Sample: [0, 0] | ||
script_stack_trace string | always | The script stack trace for the error record. Sample: at <ScriptBlock>, <No file>: line 1 | ||
target_object string | always | The object which the error occured. May be null if no object was specified when the record was created. Sample: C:\Windows | ||
host_err string | always | The strings written to the host error output, typically the stderr. This is not the same as objects sent to the error stream in PowerShell. Sample: Error 1 Error 2 | ||
host_out string | always | The strings written to the host output, typically the stdout. This is not the same as objects sent to the output stream in PowerShell. Sample: Line 1 Line 2 | ||
information list / elements=dictionary | always | A list of information records created by the script. The information stream was only added in PowerShell v5, older versions will always have an empty list as a value. | ||
message_data complex | always | Message data associated with the record. The value here can be of any type. Sample: information record | ||
source string | always | The source of the record. Sample: Write-Information | ||
tags list / elements=string | always | A list of tags associated with the record. Sample: ['Host'] | ||
time_generated string | always | The time the record was generated. This is the time in UTC as an ISO 8601 formatted string. Sample: 2021-02-11T04:46:00.4694240Z | ||
output list / elements=string | always | A list containing all the objects outputted by the script. The list elements can be anything as it is based on what was ran. Sample: ['output 1', 2, ['inner list'], {'key': 'value'}, 'None'] | ||
result complex | always | The values that were set by $Ansible.Result in the script.Defaults to an empty dict but can be set to anything by the script. Sample: {'key': 'value', 'other key': 1} | ||
verbose list / elements=string | always | A list of warning messages created by the script. Verbose messages only appear when $VerbosePreference = 'Continue' .Sample: ['verbose record'] | ||
warning list / elements=string | always | A list of warning messages created by the script. Warning messages only appear when $WarningPreference = 'Continue' .Sample: ['warning record'] |
Authors
- Jordan Borean (@jborean93)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_powershell_module.html