diff --git a/website/pages/docs/provisioners/powershell.mdx b/website/pages/docs/provisioners/powershell.mdx index bac7e6cc4..928886ec2 100644 --- a/website/pages/docs/provisioners/powershell.mdx +++ b/website/pages/docs/provisioners/powershell.mdx @@ -22,6 +22,9 @@ for details. The example below is fully functional. + + + ```json { "type": "powershell", @@ -29,6 +32,18 @@ The example below is fully functional. } ``` + + + +```hcl +provisioner "powershell" { + inline = ["dir c:\\"] +} +``` + + + + ## Configuration Reference @include 'provisioners/shell-config.mdx' @@ -63,17 +78,34 @@ The example below is fully functional. This is a [template engine](/docs/templates/engine). Therefore, you may use user variables and template functions in this field. If you are running on AWS, Azure, Google Compute, or OpenStack and would like to access - the generated password that Packer uses to connect to the instance via WinRM, - you can use the template variable `{{.WinRMPassword}}` to set this as an - environment variable. For example: + the autogenerated password that Packer uses to connect to the instance via + WinRM, you can use the `build` template engine to inject it using + `{{ build `Password`}}`. In HCL templates, you can do the same thing by + accessing the `build` variables For example: - ```json - { - "type": "powershell", - "environment_vars": "WINRMPASS={{.WinRMPassword}}", - "inline": ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""] - }, - ``` + + + +```json +{ + "type": "powershell", + "environment_vars": ["WINRMPASS={{ build `Password`}}"], + "inline": ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""] +}, +``` + + + + +```hcl +provisioner "powershell" { + environment_vars = ["WINRMPASS=${build.Password}"] + inline = ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""] +} +``` + + + - `execute_command` (string) - The command to use to execute the script. By default this is as follows: @@ -103,23 +135,64 @@ The example below is fully functional. This is a [template engine](/docs/templates/engine). Therefore, you may use user variables and template functions in this field. If you are - running a build on AWS, Azure, Google Compute, - or OpenStack and would like to run using the generated password that Packer - uses to connect to the instance via WinRM, you may do so by using the - template variable {{.WinRMPassword}}. For example: + running on AWS, Azure, Google Compute, or OpenStack and would like to access + the autogenerated password that Packer uses to connect to the instance via + WinRM, you can use the `build` template engine to inject it using + `{{ build `Password`}}`. In HCL templates, you can do the same thing by + accessing the `build` variables For example: + + + - ```json +```json +{ + "type": "powershell", "elevated_user": "Administrator", - "elevated_password": "{{.WinRMPassword}}", - ``` + "elevated_password": "{{ build `Password`}}", + ... +}, +``` + + + + +```hcl +provisioner "powershell" { + elevated_user = "Administrator" + elevated_password = build.Password +} +``` + + + If you specify an empty `elevated_password` value then the PowerShell script is run as a service account. For example: - ```json + + + +```json +{ + "type": "powershell", "elevated_user": "SYSTEM", "elevated_password": "", - ``` + ... +}, +``` + + + + +```hcl +provisioner "powershell" { + elevated_user = "SYSTEM" + elevated_password = "" +} +``` + + + - `execution_policy` - To run ps scripts on windows packer defaults this to "bypass" and wraps the command to run. Setting this to "none" will prevent @@ -204,18 +277,32 @@ reconfigured to work on a remote system with dollar sign backslash escaped so that it is not interpreted by the remote Bash shell - Bash being the default shell for Cygwin environments. + + + ```json - "provisioners": [ - { - "type": "powershell", - "execute_command": "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\"", - "inline": [ - "Write-Host \"Hello from PowerShell\"", - ] - } - ] +"provisioners": [ + { + "type": "powershell", + "execute_command": "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\"", + "inline": ["Write-Host \"Hello from PowerShell\""] + } +] +``` + + + + +```hcl +provisioner "powershell" { + execute_command = "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\"" + inline = [ "Write-Host \"Hello from PowerShell\""] +} ``` + + + ## Packer's Handling of Characters Special to PowerShell The escape character in PowerShell is the `backtick`, also sometimes referred @@ -230,6 +317,9 @@ when they appear _directly_ in the users own scripts. Note that where double quotes appear within double quotes, the addition of a backslash escape is required for the JSON template to be parsed correctly. + + + ```json "provisioners": [ { @@ -239,11 +329,30 @@ required for the JSON template to be parsed correctly. "Write-Host \"A literal backtick `` must be escaped\"", "Write-Host \"Here `\"double quotes`\" must be escaped\"", "Write-Host \"Here `'single quotes`' don`'t really need to be\"", - "Write-Host \"escaped... but it doesn`'t hurt to do so.\"", + "Write-Host \"escaped... but it doesn`'t hurt to do so.\"" ] - }, + } + ] +``` + + + + +```hcl +provisioner "powershell" { + inline = [ + "Write-Host \"A literal dollar `$ must be escaped\"", + "Write-Host \"A literal backtick `` must be escaped\"", + "Write-Host \"Here `\"double quotes`\" must be escaped\"", + "Write-Host \"Here `'single quotes`' don`'t really need to be\"", + "Write-Host \"escaped... but it doesn`'t hurt to do so.\"", + ] +} ``` + + + The above snippet should result in the following output on the Packer console: ```shell-session @@ -262,6 +371,9 @@ Special characters appearing in user environment variable values and in the `elevated_user` and `elevated_password` fields will be automatically dealt with for the user. There is no need to use escapes in these instances. + + + ```json { "variables": { @@ -298,6 +410,46 @@ for the user. There is no need to use escapes in these instances. } ``` + + + +```hcl +variable "psvar" { + type = string + default = "My$tring" +} + +build { + sources = ["source.amazon-ebs.example"] + + provisioner "powershell" { + elevated_user = "Administrator" + elevated_password = "Super$3cr3t!" + inline = ["Write-Output \"The dollar in the elevated_password is interpreted correctly\""] + } + provisioner "powershell" { + environment_vars = [ + "VAR1=A$Dollar", + "VAR2=A`Backtick", + "VAR3=A'SingleQuote", + "VAR4=A\"DoubleQuote", + "VAR5=${var.psvar}", + ] + inline = [ + "Write-Output \"In the following examples the special character is interpreted correctly:\"", + "Write-Output \"The dollar in VAR1: $Env:VAR1\"", + "Write-Output \"The backtick in VAR2: $Env:VAR2\"", + "Write-Output \"The single quote in VAR3: $Env:VAR3\"", + "Write-Output \"The double quote in VAR4: $Env:VAR4\"", + "Write-Output \"The dollar in VAR5 (expanded from a user var): $Env:VAR5\"", + ] + } +} +``` + + + + The above snippet should result in the following output on the Packer console: ```shell-session