Documentation on Invoke-AzVmRunCommand unclear

[caroysMSFT]

Description

src/Compute/Compute/help/Invoke-AzVMRunCommand.md

This video and examples show several details which are not mentioned in the documentation:

https://techcommunity.microsoft.com/t5/itops-talk-blog/how-to-run-scripts-in-your-azure-vm-by-using-run-command/ba-p/1362360

Cost

The things mentioned which are not clear in the documentation:

1. That the script is expected to exist on the source machine (and it gets parsed in memory and sent to the VM)
2. The existence of a --scripts parameter you can send a single command into (this may not be in the latest version)
3. How exactly the hashtable works with regards to the input script. Is it passed as simple command line parameters to the resultant script, or does it do a replacement inside the script?

Some concrete examples would save a lot of customer confusion as well.

[ghost]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @Drewm3, @avirishuv.

Issue Details

---

Description

src/Compute/Compute/help/Invoke-AzVMRunCommand.md

This video and examples show several details which are not mentioned in the documentation:

https://techcommunity.microsoft.com/t5/itops-talk-blog/how-to-run-scripts-in-your-azure-vm-by-using-run-command/ba-p/1362360

Cost

The things mentioned which are not clear in the documentation:

1. That the script is expected to exist on the source machine (and it gets parsed in memory and sent to the VM)
2. The existence of a --scripts parameter you can send a single command into (this may not be in the latest version)
3. How exactly the hashtable works with regards to the input script. Is it passed as simple command line parameters to the resultant script, or does it do a replacement inside the script?

Some concrete examples would save a lot of customer confusion as well.

Author:	caroysMSFT
Assignees:	-
Labels:	Engineering, Doc - Reference, Compute - VM, Service Attention
Milestone:	-

[jaylabell]

@avirishuv can you take a look at this issue?

[jaylabell]

@amjads1 can you take a look at this issue?

[amjads1]

Looking into the issue.

[amjads1]

Working with @koralski to add additional clarity with examples in the existing documentation: https://github.com/Azure/azure-powershell/blob/main/src/Compute/Compute/help/Invoke-AzVMRunCommand.md

[koralski]

https://github.com/Azure/azure-powershell/blob/main/src/Compute/Compute/help/Invoke-AzVMRunCommand.md
Powershell doc needs to add:
-ScriptPath
Path of the script to be executed. When this value is given, the given script will override the default script of the command.
Path should point to a file from a local file system. The command will load it and send it for execution.

-Parameter
Specify parameters as key/value pairs to be passed at script execution.
Example (Windows VM):
Invoke-AzVMRunCommand -ResourceGroupName 'rgname' -Name 'vmname' -CommandId 'RunPowerShellScript' -ScriptPath 'sample.ps1' -Parameter @{"first" = "value1";"second" = "value2"}
Where arg1 and arg2 are defined as parameters in the sample.ps1:
param(
[string]$first,
[string]$second
)
Write-Host This is a sample script with parameters $first $second
Parameter value can be string type only and script is responsible for converting them to other types if needed.

For linux the parameters get converted to environment variables:
export first=value1 second=value2
set -- value1 value2 value3
These exports get added to the top of the bash script before execution.
Example (linux VM):
Invoke-AzVMRunCommand -ResourceGroupName 'rgname' -Name 'vmname' -CommandId 'RunShellScript' -ScriptPath 'sample.bash' -Parameter @{"first" = "value1";"second" = "value2"}
echo This is a sample bash script
echo Usage 1: Ordered parameters: $0 $1
echo Usage 2: Named exports: $first $second

Azure CLI:
--script
String should contain the script content to execute.
Example:
az vm run-command invoke -g myResourceGroup -n myVm --command-id RunShellScript --scripts "sudo apt-get update && sudo apt-get install -y nginx"

REST API
Reference to the spec to construct your URL and json body:
https://github.com/Azure/azure-rest-api-specs/blob/main/specification/compute/resource-manager/Microsoft.Compute/stable/2021-07-01/runCommands.json#L944

Example:
POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommand
{
"commandId": "RunPowerShellScript",
"script": [
"param(",
" [string]$first,",
" [string]$second",
")",
"Write-Host This is a sample script with parameters $first $second",
"Write-Host Done."
],
"parameters": [
{
"name": "first",
"value": "value1"
},
{
"name": "second",
"value": "value2"
}
]
}

[amjads1]

Thanks @koralski for the updates!

[mimckitt]

@amjads1 @koralski does the powershell update look correct?

https://github.com/Azure/azure-powershell/pull/16000/files

[amjads1]

@mimckitt Looks good to me. Thanks for the updates Micah!

@caroysMSFT I will go ahead and closed this issue now with the assumption that document will be updated in next week or so.