docs/powershell: Add struct-markdown to provisioner config

provisioner/powershell/provisioner.go

@@ -1,3 +1,4 @@
+//go:generate struct-markdown
 //go:generate mapstructure-to-hcl2 -type Config
 
 // This package implements a provisioner for Packer that executes powershell
@@ -50,6 +51,15 @@ type Config struct {
 	// The command used to execute the elevated script. The '{{ .Path }}'
 	// variable should be used to specify where the script goes, {{ .Vars }}
 	// can be used to inject the environment_vars into the environment.
+	// ```powershell
+	// powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
+	// ```
+	// This is a [template engine](/docs/templates/engine). Therefore, you
+	// may use user variables and template functions in this field. In addition,
+	// you may use two extra variables:
+	// - `Path`: The path to the script to run
+	// - `Vars`: The location of a temp file containing the list of
+	// `environment_vars`, if configured.
 	ElevatedExecuteCommand string `mapstructure:"elevated_execute_command"`
 
 	// Whether to clean scripts up after executing the provisioner.
@@ -59,9 +69,10 @@ type Config struct {
 	// value set for `skip_clean`.
 	SkipClean bool `mapstructure:"skip_clean"`
 
-	// The timeout for retrying to start the process. Until this timeout is
+	// The amount of time to attempt to _start_
-	// reached, if the provisioner can't start a process, it retries.  This
+	// the remote process. By default this is "5m" or 5 minutes. This setting
-	// can be set high to allow for reboots.
+	// exists in order to deal with times when SSH may restart, such as a system
+	// reboot. Set this to a higher value if reboots take a longer amount of time.
 	StartRetryTimeout time.Duration `mapstructure:"start_retry_timeout"`
 
 	// This is used in the template generation to format environment variables
@@ -74,6 +85,11 @@ type Config struct {
 	ElevatedUser     string `mapstructure:"elevated_user"`
 	ElevatedPassword string `mapstructure:"elevated_password"`
 
+	// To run ps scripts on windows packer defaults this to
+	// "bypass" and wraps the command to run. Setting this to "none" will prevent
+	// wrapping, allowing to see exit codes on docker for windows. Possible values
+	// are "bypass", "allsigned", "default", "remotesigned", "restricted",
+	// "undefined", "unrestricted", "none".
 	ExecutionPolicy ExecutionPolicy `mapstructure:"execution_policy"`
 
 	remoteCleanUpScriptPath string

website/pages/docs/provisioners/powershell.mdx

@@ -46,42 +46,16 @@ provisioner "powershell" {
 
 ## Configuration Reference
 
+### Required
+
 @include 'provisioners/shell-config.mdx'
 
-- `debug_mode` - If set, sets PowerShell's [PSDebug mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/set-psdebug?view=powershell-7)
+### Optional
-  in order to make script debugging easier. For instance, setting the value to 1 results in adding this to the execute command:
+@include 'provisioner/powershell/Config-not-required.mdx'
 
-  ```powershell
+@include 'provisioners/common-config.mdx'
-  Set-PSDebug -Trace 1
-  ```
 
-- `elevated_execute_command` (string) - The command to use to execute the
+## Default Environmental Variables
-  elevated script. By default this is as follows:
-
-  ```powershell
-  powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
-  ```
-
-  This is a [template engine](/docs/templates/engine). Therefore, you
-  may use user variables and template functions in this field. In addition,
-  you may use two extra variables:
-
-  - `Path`: The path to the script to run
-  - `Vars`: The location of a temp file containing the list of
-    `environment_vars`, if configured.
-
-- `environment_vars` (array of strings) - An array of key/value pairs to
-  inject prior to the execute_command. The format should be `key=value`.
-  Packer injects some environmental variables by default into the
-  environment, as well, which are covered in the section below.
-
-  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 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:
 
 <Tabs>
 <Tab heading="JSON">
@@ -107,39 +81,29 @@ provisioner "powershell" {
 </Tab>
 </Tabs>
 
-- `execute_command` (string) - The command to use to execute the script. By
+In addition to being able to specify custom environmental variables using the
-  default this is as follows:
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
 
-  ```powershell
+- `PACKER_BUILD_NAME` is set to the [name of the
-  powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
+  build](/docs/templates/builders#named-builds) that Packer is running.
-  ```
+  This is most useful when Packer is making multiple builds and you want to
+  distinguish them slightly from a common provisioning script.
 
-  This is a [template engine](/docs/templates/engine). Therefore, you
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
-  may use user variables and template functions in this field. In addition,
+  the machine that the script is running on. This is useful if you want to
-  you may use two extra variables:
+  run only certain parts of the script on systems built with certain
+  builders.
 
-  - `Path`: The path to the script to run
+- `PACKER_HTTP_ADDR` If using a builder that provides an http server for file
-  - `Vars`: The location of a temp file containing the list of
+  transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this
-    `environment_vars`, if configured.
+  will be set to the address. You can use this address in your provisioner to
-    The value of both `Path` and `Vars` can be manually configured by setting
+  download large files over http. This may be useful if you're experiencing
-    the values for `remote_path` and `remote_env_var_path` respectively.
+  slower speeds using the default file provisioner. A file provisioner using
+  the `winrm` communicator may experience these types of difficulties.
 
-  If you use the SSH communicator and have changed your default shell, you
-  may need to modify your `execute_command` to make sure that the command is
-  valid and properly escaped; the default assumes that you have not changed
-  the default shell away from cmd.
 
-- `elevated_user` and `elevated_password` (string) - If specified, the
+## Setting Elevated User and Password
-  PowerShell script will be run with elevated privileges using the given
-  Windows user.
-
-  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 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:
 
 <Tabs>
 <Tab heading="JSON">
@@ -194,69 +158,6 @@ provisioner "powershell" {
 </Tab>
 </Tabs>
 
-- `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
-  wrapping, allowing to see exit codes on docker for windows. Possible values
-  are "bypass", "allsigned", "default", "remotesigned", "restricted",
-  "undefined", "unrestricted", "none".
-
-- `remote_path` (string) - The path where the PowerShell script will be
-  uploaded to within the target build machine. This defaults to
-  `C:/Windows/Temp/script-UUID.ps1` where UUID is replaced with a dynamically
-  generated string that uniquely identifies the script.
-
-  This setting allows users to override the default upload location. The
-  value must be a writable location and any parent directories must already
-  exist.
-
-- `remote_env_var_path` (string) - Environment variables required within the
-  remote environment are uploaded within a PowerShell script and then enabled
-  by 'dot sourcing' the script immediately prior to execution of the main
-  command or script.
-
-  The path the environment variables script will be uploaded to defaults to
-  `C:/Windows/Temp/packer-ps-env-vars-UUID.ps1` where UUID is replaced with a
-  dynamically generated string that uniquely identifies the script.
-
-  This setting allows users to override the location the environment variable
-  script is uploaded to. The value must be a writable location and any parent
-  directories must already exist.
-
-- `skip_clean` (bool) - Whether to clean scripts up after executing the provisioner.
-  Defaults to false. When true any script created by a non-elevated Powershell
-  provisioner will be removed from the remote machine. Elevated scripts,
-  along with the scheduled tasks, will always be removed regardless of the
-  value set for `skip_clean`.
-
-- `start_retry_timeout` (string) - The amount of time to attempt to _start_
-  the remote process. By default this is "5m" or 5 minutes. This setting
-  exists in order to deal with times when SSH may restart, such as a system
-  reboot. Set this to a higher value if reboots take a longer amount of time.
-
-@include 'provisioners/common-config.mdx'
-
-## Default Environmental Variables
-
-In addition to being able to specify custom environmental variables using the
-`environment_vars` configuration, the provisioner automatically defines certain
-commonly useful environmental variables:
-
-- `PACKER_BUILD_NAME` is set to the [name of the
-  build](/docs/templates/builders#named-builds) that Packer is running.
-  This is most useful when Packer is making multiple builds and you want to
-  distinguish them slightly from a common provisioning script.
-
-- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
-  the machine that the script is running on. This is useful if you want to
-  run only certain parts of the script on systems built with certain
-  builders.
-
-- `PACKER_HTTP_ADDR` If using a builder that provides an http server for file
-  transfer (such as hyperv, parallels, qemu, virtualbox, and vmware), this
-  will be set to the address. You can use this address in your provisioner to
-  download large files over http. This may be useful if you're experiencing
-  slower speeds using the default file provisioner. A file provisioner using
-  the `winrm` communicator may experience these types of difficulties.
 
 ## Combining the PowerShell Provisioner with the SSH Communicator
 

website/pages/partials/provisioner/powershell/Config-not-required.mdx

@@ -0,0 +1,52 @@
+<!-- Code generated from the comments of the Config struct in provisioner/powershell/provisioner.go; DO NOT EDIT MANUALLY -->
+
+- `remote_env_var_path` (string) - The remote path where the file containing the environment variables
+  will be uploaded to. This should be set to a writable file that is in a
+  pre-existing directory.
+
+- `elevated_execute_command` (string) - The command used to execute the elevated script. The '{{ .Path }}'
+  variable should be used to specify where the script goes, {{ .Vars }}
+  can be used to inject the environment_vars into the environment.
+  ```powershell
+  powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
+  ```
+  This is a [template engine](/docs/templates/engine). Therefore, you
+  may use user variables and template functions in this field. In addition,
+  you may use two extra variables:
+  - `Path`: The path to the script to run
+  - `Vars`: The location of a temp file containing the list of
+  `environment_vars`, if configured.
+
+- `skip_clean` (bool) - Whether to clean scripts up after executing the provisioner.
+  Defaults to false. When true any script created by a non-elevated Powershell
+  provisioner will be removed from the remote machine. Elevated scripts,
+  along with the scheduled tasks, will always be removed regardless of the
+  value set for `skip_clean`.
+
+- `start_retry_timeout` (duration string | ex: "1h5m2s") - The amount of time to attempt to _start_
+  the remote process. By default this is "5m" or 5 minutes. This setting
+  exists in order to deal with times when SSH may restart, such as a system
+  reboot. Set this to a higher value if reboots take a longer amount of time.
+
+- `elevated_env_var_format` (string) - This is used in the template generation to format environment variables
+  inside the `ElevatedExecuteCommand` template.
+
+- `elevated_user` (string) - Instructs the communicator to run the remote script as a Windows
+  scheduled task, effectively elevating the remote user by impersonating
+  a logged-in user
+
+- `elevated_password` (string) - Elevated Password
+
+- `execution_policy` (ExecutionPolicy) - To run ps scripts on windows packer defaults this to
+  "bypass" and wraps the command to run. Setting this to "none" will prevent
+  wrapping, allowing to see exit codes on docker for windows. Possible values
+  are "bypass", "allsigned", "default", "remotesigned", "restricted",
+  "undefined", "unrestricted", "none".
+
+- `debug_mode` (int) - If set, sets PowerShell's [PSDebug mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/set-psdebug?view=powershell-7)
+   in order to make script debugging easier. For instance, setting the
+     value to 1 results in adding this to the execute command:
+  
+     ``` powershell
+     Set-PSDebug -Trace 1
+     ```