Virtual Machine Scale Set VM Run Commands - Update

The operation to update the VMSS VM run command.

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmScaleSetName}/virtualMachines/{instanceId}/runCommands/{runCommandName}?api-version=2023-09-01

URI Parameters

Name In Required Type Description
instanceId
path True

string

The instance ID of the virtual machine.

resourceGroupName
path True

string

The name of the resource group.

runCommandName
path True

string

The name of the virtual machine run command.

subscriptionId
path True

string

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

vmScaleSetName
path True

string

The name of the VM scale set.

api-version
query True

string

Client Api Version.

Request Body

Media Types: "application/json", "text/json"

Name Type Description
properties.asyncExecution

boolean

Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.

properties.errorBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to errorBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.errorBlobUri

string

Specifies the Azure storage blob where script error stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer errorBlobManagedIdentity parameter.

properties.outputBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to outputBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.outputBlobUri

string

Specifies the Azure storage blob where script output stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer outputBlobManagedIdentity parameter.

properties.parameters

RunCommandInputParameter[]

The parameters used by the script.

properties.protectedParameters

RunCommandInputParameter[]

The parameters used by the script.

properties.runAsPassword

string

Specifies the user account password on the VM when executing the run command.

properties.runAsUser

string

Specifies the user account on the VM when executing the run command.

properties.source

VirtualMachineRunCommandScriptSource

The source of the run command script.

properties.timeoutInSeconds

integer

The timeout in seconds to execute the run command.

properties.treatFailureAsDeploymentFailure

boolean

Optional. If set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results

tags

object

Resource tags

Responses

Name Type Description
200 OK

VirtualMachineRunCommand

OK

Media Types: "application/json", "text/json"

Other Status Codes

CloudError

Error response describing why the operation failed.

Media Types: "application/json", "text/json"

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Update VirtualMachineScaleSet VM run command.

Sample Request

PATCH https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/runCommands/myRunCommand?api-version=2023-09-01

{
  "properties": {
    "source": {
      "scriptUri": "https://mystorageaccount.blob.core.windows.net/scriptcontainer/MyScript.ps1",
      "scriptUriManagedIdentity": {
        "objectId": "4231e4d2-33e4-4e23-96b2-17888afa6072"
      }
    }
  }
}

Sample Response

{
  "name": "myRunCommand",
  "type": "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/runCommands",
  "id": "/subscriptions/{subscription-id}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/runCommands/myRunCommand",
  "location": "westus",
  "tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "properties": {
    "source": {
      "scriptUri": "https://mystorageaccount.blob.core.windows.net/scriptcontainer/MyScript.ps1"
    },
    "parameters": [
      {
        "name": "param1",
        "value": "value1"
      },
      {
        "name": "param2",
        "value": "value2"
      }
    ],
    "asyncExecution": false,
    "treatFailureAsDeploymentFailure": false,
    "runAsUser": "user1",
    "timeoutInSeconds": 3600,
    "provisioningState": "Updating",
    "outputBlobUri": "https://mystorageaccount.blob.core.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt"
  }
}

Definitions

Name Description
ApiError

Api error.

ApiErrorBase

Api error base.

CloudError

An error response from the Compute service.

ExecutionState

Script execution status.

InnerError

Inner error details.

InstanceViewStatus

Instance view status.

RunCommandInputParameter

Describes the properties of a run command parameter.

RunCommandManagedIdentity

Contains clientId or objectId (use only one, not both) of a user-assigned managed identity that has access to storage blob used in Run Command. Use an empty RunCommandManagedIdentity object in case of system-assigned identity. Make sure the Azure storage blob exists in case of scriptUri, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment with scriptUri blob and 'Storage Blob Data Contributor' for Append blobs(outputBlobUri, errorBlobUri). In case of user assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.

StatusLevelTypes

The level code.

VirtualMachineRunCommand

Describes a Virtual Machine run command.

VirtualMachineRunCommandInstanceView

The instance view of a virtual machine run command.

VirtualMachineRunCommandScriptSource

Describes the script sources for run command. Use only one of script, scriptUri, commandId.

VirtualMachineRunCommandUpdate

Describes a Virtual Machine run command.

ApiError

Api error.

Name Type Description
code

string

The error code.

details

ApiErrorBase[]

The Api error details

innererror

InnerError

The Api inner error

message

string

The error message.

target

string

The target of the particular error.

ApiErrorBase

Api error base.

Name Type Description
code

string

The error code.

message

string

The error message.

target

string

The target of the particular error.

CloudError

An error response from the Compute service.

Name Type Description
error

ApiError

Api error.

ExecutionState

Script execution status.

Name Type Description
Canceled

string

Failed

string

Pending

string

Running

string

Succeeded

string

TimedOut

string

Unknown

string

InnerError

Inner error details.

Name Type Description
errordetail

string

The internal error message or exception dump.

exceptiontype

string

The exception type.

InstanceViewStatus

Instance view status.

Name Type Description
code

string

The status code.

displayStatus

string

The short localizable label for the status.

level

StatusLevelTypes

The level code.

message

string

The detailed status message, including for alerts and error messages.

time

string

The time of the status.

RunCommandInputParameter

Describes the properties of a run command parameter.

Name Type Description
name

string

The run command parameter name.

value

string

The run command parameter value.

RunCommandManagedIdentity

Contains clientId or objectId (use only one, not both) of a user-assigned managed identity that has access to storage blob used in Run Command. Use an empty RunCommandManagedIdentity object in case of system-assigned identity. Make sure the Azure storage blob exists in case of scriptUri, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment with scriptUri blob and 'Storage Blob Data Contributor' for Append blobs(outputBlobUri, errorBlobUri). In case of user assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.

Name Type Description
clientId

string

Client Id (GUID value) of the user-assigned managed identity. ObjectId should not be used if this is provided.

objectId

string

Object Id (GUID value) of the user-assigned managed identity. ClientId should not be used if this is provided.

StatusLevelTypes

The level code.

Name Type Description
Error

string

Info

string

Warning

string

VirtualMachineRunCommand

Describes a Virtual Machine run command.

Name Type Default Value Description
id

string

Resource Id

location

string

Resource location

name

string

Resource name

properties.asyncExecution

boolean

False

Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.

properties.errorBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to errorBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.errorBlobUri

string

Specifies the Azure storage blob where script error stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer errorBlobManagedIdentity parameter.

properties.instanceView

VirtualMachineRunCommandInstanceView

The virtual machine run command instance view.

properties.outputBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to outputBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.outputBlobUri

string

Specifies the Azure storage blob where script output stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer outputBlobManagedIdentity parameter.

properties.parameters

RunCommandInputParameter[]

The parameters used by the script.

properties.protectedParameters

RunCommandInputParameter[]

The parameters used by the script.

properties.provisioningState

string

The provisioning state, which only appears in the response. If treatFailureAsDeploymentFailure set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If treatFailureAsDeploymentFailure set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results

properties.runAsPassword

string

Specifies the user account password on the VM when executing the run command.

properties.runAsUser

string

Specifies the user account on the VM when executing the run command.

properties.source

VirtualMachineRunCommandScriptSource

The source of the run command script.

properties.timeoutInSeconds

integer

The timeout in seconds to execute the run command.

properties.treatFailureAsDeploymentFailure

boolean

False

Optional. If set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results

tags

object

Resource tags

type

string

Resource type

VirtualMachineRunCommandInstanceView

The instance view of a virtual machine run command.

Name Type Description
endTime

string

Script end time.

error

string

Script error stream.

executionMessage

string

Communicate script configuration errors or execution messages.

executionState

ExecutionState

Script execution status.

exitCode

integer

Exit code returned from script execution.

output

string

Script output stream.

startTime

string

Script start time.

statuses

InstanceViewStatus[]

The resource status information.

VirtualMachineRunCommandScriptSource

Describes the script sources for run command. Use only one of script, scriptUri, commandId.

Name Type Description
commandId

string

Specifies a commandId of predefined built-in script.

script

string

Specifies the script content to be executed on the VM.

scriptUri

string

Specifies the script download location. It can be either SAS URI of an Azure storage blob with read access or public URI.

scriptUriManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to scriptUri in case of Azure storage blob. Use an empty object in case of system-assigned identity. Make sure the Azure storage blob exists, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.

VirtualMachineRunCommandUpdate

Describes a Virtual Machine run command.

Name Type Default Value Description
properties.asyncExecution

boolean

False

Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.

properties.errorBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to errorBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.errorBlobUri

string

Specifies the Azure storage blob where script error stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer errorBlobManagedIdentity parameter.

properties.instanceView

VirtualMachineRunCommandInstanceView

The virtual machine run command instance view.

properties.outputBlobManagedIdentity

RunCommandManagedIdentity

User-assigned managed identity that has access to outputBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged

properties.outputBlobUri

string

Specifies the Azure storage blob where script output stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer outputBlobManagedIdentity parameter.

properties.parameters

RunCommandInputParameter[]

The parameters used by the script.

properties.protectedParameters

RunCommandInputParameter[]

The parameters used by the script.

properties.provisioningState

string

The provisioning state, which only appears in the response. If treatFailureAsDeploymentFailure set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If treatFailureAsDeploymentFailure set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results

properties.runAsPassword

string

Specifies the user account password on the VM when executing the run command.

properties.runAsUser

string

Specifies the user account on the VM when executing the run command.

properties.source

VirtualMachineRunCommandScriptSource

The source of the run command script.

properties.timeoutInSeconds

integer

The timeout in seconds to execute the run command.

properties.treatFailureAsDeploymentFailure

boolean

False

Optional. If set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results

tags

object

Resource tags