453 lines
15 KiB
Python
453 lines
15 KiB
Python
#!/usr/bin/python
|
|
# -*- coding: utf-8 -*-
|
|
|
|
# Copyright: (c) 2021, Ansible Project
|
|
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
|
|
|
|
|
DOCUMENTATION = r'''
|
|
---
|
|
module: win_powershell
|
|
version_added: 1.5.0
|
|
short_description: Run PowerShell scripts
|
|
description:
|
|
- Runs a PowerShell script and outputs the data in a structured format.
|
|
- Use M(ansible.windows.win_command) or M(ansible.windows.win_shell) to run a tranditional PowerShell process with
|
|
stdout, stderr, and rc results.
|
|
options:
|
|
arguments:
|
|
description:
|
|
- A list of arguments to pass to I(executable) when running a script in another PowerShell process.
|
|
- These are not arguments to pass to I(script), use I(parameters) for that purpose.
|
|
type: list
|
|
elements: str
|
|
chdir:
|
|
description:
|
|
- 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.
|
|
type: str
|
|
creates:
|
|
description:
|
|
- A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
|
|
type: str
|
|
depth:
|
|
description:
|
|
- How deep the return values are serialized for C(result), C(output), and C(information[x].message_data).
|
|
- Setting this to a higher value can dramatically increase the amount of data that needs to be returned.
|
|
default: 2
|
|
type: int
|
|
error_action:
|
|
description:
|
|
- The C($ErrorActionPreference) to set before executing I(script).
|
|
- C(silently_continue) will ignore any errors and exceptions raised.
|
|
- C(continue) is the default behaviour in PowerShell, errors are present in the I(error) return value but only
|
|
terminating exceptions will stop the script from continuing and set it as failed.
|
|
- C(stop) will treat errors like exceptions, will stop the script and set it as failed.
|
|
choices:
|
|
- silently_continue
|
|
- continue
|
|
- stop
|
|
default: continue
|
|
type: str
|
|
executable:
|
|
description:
|
|
- 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 I(executable) must be running on PowerShell v5.1 or newer.
|
|
- Setting this value may change the values returned in the C(output) return value depending on the underlying .NET
|
|
type.
|
|
type: str
|
|
parameters:
|
|
description:
|
|
- 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.
|
|
type: dict
|
|
removes:
|
|
description:
|
|
- A path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be
|
|
skipped.
|
|
type: str
|
|
script:
|
|
description:
|
|
- The PowerShell script to run.
|
|
type: str
|
|
required: true
|
|
seealso:
|
|
- module: ansible.windows.win_command
|
|
- module: ansible.windows.win_shell
|
|
notes:
|
|
- The module is set as failed when a terminating exception is throw, or C(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 C(ConvertTo-Json) result the
|
|
following value types are different.
|
|
- C(DateTime) will be an ISO 8601 string in UTC, C(DateTimeOffset) will have the offset as specified by the value.
|
|
- C(Enum) will contain a dictionary with C(Type), C(String), C(Value) being the type name, string representation and
|
|
raw integer value respectively.
|
|
- C(Type) will contain a dictionary with C(Name), C(FullName), C(AssemblyQualifiedName), C(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 C($Ansible) variable where it can set C(Result), C(Changed), C(Failed), or access
|
|
C(Tmpdir).
|
|
- C($Ansible.Result) is a value that is returned back to the controller as is.
|
|
- C($Ansible.Changed) can be set to C(true) or C(false) to reflect whether the module made a change or not. By default
|
|
this is set to C(true).
|
|
- C($Ansible.Failed) can be set to C(true) if the script wants to return the failure back to the controller.
|
|
- C($Ansible.Tmpdir) is the path to a temporary directory to use as a scratch location that is cleaned up after the
|
|
module has finished.
|
|
- C($Ansible.Verbosity) reveals Ansible's verbosity level for this play. Allows the script to set VerbosePreference/DebugPreference
|
|
based on verbosity. Added in C(1.9.0).
|
|
- Any host/console output like C(Write-Host) or C([Console]::WriteLine) is not considered an output object, they are
|
|
returned as a string in I(host_out) and I(host_err).
|
|
- The module will skip running the script when in check mode unless the script defines
|
|
C([CmdletBinding(SupportsShouldProcess)]).
|
|
author:
|
|
- Jordan Borean (@jborean93)
|
|
'''
|
|
|
|
EXAMPLES = r'''
|
|
- 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
|
|
}
|
|
|
|
- name: Define when to enable Verbose/Debug output
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
if ($Ansible.Verbosity -ge 3) {
|
|
$VerbosePreference = "Continue"
|
|
}
|
|
if ($Ansible.Verbosity -eq 5) {
|
|
$DebugPreference = "Continue"
|
|
}
|
|
Write-Output "Hello World!"
|
|
Write-Verbose "Hello World!"
|
|
Write-Debug "Hello World!"
|
|
|
|
'''
|
|
|
|
RETURN = r'''
|
|
result:
|
|
description:
|
|
- The values that were set by C($Ansible.Result) in the script.
|
|
- Defaults to an empty dict but can be set to anything by the script.
|
|
returned: always
|
|
type: complex
|
|
sample: {'key': 'value', 'other key': 1}
|
|
contains: {} # Satisfy the validate-modules sanity check
|
|
host_out:
|
|
description:
|
|
- The strings written to the host output, typically the stdout.
|
|
- This is not the same as objects sent to the output stream in PowerShell.
|
|
returned: always
|
|
type: str
|
|
sample: "Line 1\nLine 2"
|
|
host_err:
|
|
description:
|
|
- 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.
|
|
returned: always
|
|
type: str
|
|
sample: "Error 1\nError 2"
|
|
output:
|
|
description:
|
|
- A list containing all the objects outputted by the script.
|
|
- The list elements can be anything as it is based on what was ran.
|
|
returned: always
|
|
type: list
|
|
sample: ['output 1', 2, ['inner list'], {'key': 'value'}, None]
|
|
error:
|
|
description:
|
|
- A list of error records created by the script.
|
|
returned: always
|
|
type: list
|
|
elements: dict
|
|
contains:
|
|
output:
|
|
description:
|
|
- The formatted error record message as typically seen in a PowerShell console.
|
|
type: str
|
|
returned: always
|
|
sample: |
|
|
Write-Error "error" : error
|
|
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
|
|
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
|
|
error_details:
|
|
description:
|
|
- Additional details about an ErrorRecord.
|
|
- Can be null if there are not additional details.
|
|
type: dict
|
|
contains:
|
|
message:
|
|
description:
|
|
- Message for the error record.
|
|
returned: always
|
|
type: str
|
|
sample: Specific error message
|
|
recommended_action:
|
|
description:
|
|
- Recommended action in the even that this error occurs.
|
|
- This is empty unless the code which generates the error adds this explicitly.
|
|
returned: always
|
|
type: str
|
|
sample: Delete file
|
|
exception:
|
|
description:
|
|
- Details about the exception behind the error record.
|
|
type: dict
|
|
contains:
|
|
message:
|
|
description:
|
|
- The exception message.
|
|
type: str
|
|
returned: always
|
|
sample: The method ran into an error
|
|
type:
|
|
description:
|
|
- The full .NET type of the Exception class.
|
|
type: str
|
|
returned: always
|
|
sample: System.Exception
|
|
help_link:
|
|
description:
|
|
- 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.
|
|
type: str
|
|
returned: always
|
|
sample: http://docs.ansible.com/
|
|
source:
|
|
description:
|
|
- 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.
|
|
type: str
|
|
returned: always
|
|
sample: C:\Windows
|
|
hresult:
|
|
description:
|
|
- The signed integer assigned to this exception.
|
|
- May not be set as it's dependent on whether the .NET exception class provides this info.
|
|
type: int
|
|
returned: always
|
|
sample: -1
|
|
inner_exception:
|
|
description:
|
|
- The inner exception details if there is one present.
|
|
- The dict contains the same keys as a normal exception.
|
|
returned: always
|
|
type: dict
|
|
target_object:
|
|
description:
|
|
- The object which the error occured.
|
|
- May be null if no object was specified when the record was created.
|
|
type: str
|
|
returned: always
|
|
sample: C:\Windows
|
|
category_info:
|
|
description:
|
|
- More information about the error record.
|
|
type: dict
|
|
contains:
|
|
category:
|
|
description:
|
|
- The category name of the error record.
|
|
type: str
|
|
returned: always
|
|
sample: NotSpecified
|
|
category_id:
|
|
description:
|
|
- The integer representation of the category.
|
|
type: int
|
|
returned: always
|
|
sample: 0
|
|
activity:
|
|
description:
|
|
- Description of the operation which encountered the error.
|
|
type: str
|
|
returned: always
|
|
sample: Write-Error
|
|
reason:
|
|
description:
|
|
- Description of the error.
|
|
type: str
|
|
returned: always
|
|
sample: WriteErrorException
|
|
target_name:
|
|
description:
|
|
- Description of the target object.
|
|
- Can be an empty string if no target was specified.
|
|
type: str
|
|
returned: always
|
|
sample: C:\Windows
|
|
target_type:
|
|
description:
|
|
- Description of the type of the target object.
|
|
- Can be an empty string if no target object was specified.
|
|
type: str
|
|
returned: always
|
|
sample: String
|
|
fully_qualified_error_id:
|
|
description:
|
|
- The unique identifier for the error condition
|
|
- May be null if no id was specified when the record was created.
|
|
type: str
|
|
returned: always
|
|
sample: ParameterBindingFailed
|
|
script_stack_trace:
|
|
description:
|
|
- The script stack trace for the error record.
|
|
type: str
|
|
returned: always
|
|
sample: 'at <ScriptBlock>, <No file>: line 1'
|
|
pipeline_iteration_info:
|
|
description:
|
|
- 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('C:\Windows', 'C:\temp' | Get-ChildItem | Get-Item), C([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.
|
|
type: list
|
|
elements: int
|
|
returned: always
|
|
sample: [0, 0]
|
|
warning:
|
|
description:
|
|
- A list of warning messages created by the script.
|
|
- Warning messages only appear when C($WarningPreference = 'Continue').
|
|
returned: always
|
|
type: list
|
|
elements: str
|
|
sample: ['warning record']
|
|
verbose:
|
|
description:
|
|
- A list of warning messages created by the script.
|
|
- Verbose messages only appear when C($VerbosePreference = 'Continue').
|
|
returned: always
|
|
type: list
|
|
elements: str
|
|
sample: ['verbose record']
|
|
debug:
|
|
description:
|
|
- A list of warning messages created by the script.
|
|
- Debug messages only appear when C($DebugPreference = 'Continue').
|
|
returned: always
|
|
type: list
|
|
elements: str
|
|
sample: ['debug record']
|
|
information:
|
|
description:
|
|
- 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.
|
|
returned: always
|
|
type: list
|
|
elements: dict
|
|
contains:
|
|
message_data:
|
|
description:
|
|
- Message data associated with the record.
|
|
- The value here can be of any type.
|
|
type: complex
|
|
returned: always
|
|
sample: information record
|
|
contains: {} # Satisfy the validate-modules sanity check
|
|
source:
|
|
description:
|
|
- The source of the record.
|
|
type: str
|
|
returned: always
|
|
sample: Write-Information
|
|
time_generated:
|
|
description:
|
|
- The time the record was generated.
|
|
- This is the time in UTC as an ISO 8601 formatted string.
|
|
type: str
|
|
returned: always
|
|
sample: '2021-02-11T04:46:00.4694240Z'
|
|
tags:
|
|
description:
|
|
- A list of tags associated with the record.
|
|
type: list
|
|
elements: str
|
|
returned: always
|
|
sample: ['Host']
|
|
'''
|