Update Role
The Update Role operation updates the configuration of the specified Virtual Machine.
Request
The Update Role request may be specified as follows. Replace <subscription-id> with the subscription ID, <cloudservice-name> with the name of the cloud service, <deployment-name> with the name of the deployment, and <role-name> with the name of the Virtual Machine.
Method |
Request URI |
---|---|
PUT |
https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments/<deployment-name>/roles/<role-name> |
URI Parameters
None.
Request Headers
The following table describes the request headers.
Request Header |
Description |
---|---|
x-ms-version |
Required. Specifies the version of the operation to use for this request. This header should be set to 2012-03-01 or higher. |
Request Body
The format of the request body is as follows:
<PersistentVMRole xmlns="https://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ConfigurationSets>
<ConfigurationSet>
<ConfigurationSetType>NetworkConfiguration</ConfigurationSetType>
<InputEndpoints>
<InputEndpoint>
<LoadBalancedEndpointSetName>name-of-loadbalanced-set</LoadBalancedEndpointSetName>
<LocalPort>local-port-number</LocalPort>
<Name>name-of-endpoint</Name>
<Port>external-port-number</Port>
<LoadBalancerProbe>
<Path>path-of-probe</Path>
<Port>port-assigned-to-probe</Port>
<Protocol>probe-protocol</Protocol>
</LoadBalancerProbe>
<Protocol>endpoint-protocol</Protocol>
<EnableDirectServerReturn>enable-direct-server-return</EnableDirectServerReturn>
<EndpointAcl>
<Rules>
<Rule>
<Order>priority-of-the-rule</Order>
<Action>permit-rule</Action>
<RemoteSubnet>subnet-of-the-rule</RemoteSubnet>
<Description>description-of-the-rule</Description>
</Rule>
</Rules>
</EndpointAcl>
<LoadBalancerName>name-of-internal-loadbalancer</LoadBalancerName>
<IdleTimeoutInMinutes>timeout-for-tcp-idle-connection</IdleTimeoutInMinutes>
</InputEndpoint>
</InputEndpoints>
<SubnetNames>
<SubnetName>name-of-subnet</SubnetName>
</SubnetNames>
<StaticVirtualNetworkIPAddress>ip-address</StaticVirtualNetworkIPAddress>
<NetworkSecurityGroup>network-security-group</NetworkSecurityGroup>
<PublicIPs>
<PublicIP>
<Name>name-of-public-ip</Name>
<IdleTimeoutInMinutes>timeout-for-tcp-idle-connection</IdleTimeoutInMinutes>
<DomainNameLabel>domain-name</DomainNameLabel>
<PublicIP>
<PublicIPs>
<NetworkInterfaces>
<NetworkInterface>
<Name>interface-name</Name>
<IPConfigurations>
<IPConfiguration>
<SubnetName>subnet-name</SubnetName>
<StaticVirtualNetworkIPAddress>ip-address</StaticVirtualNetworkIPAddress>
</IPConfiguration>
</IPConfigurations>
</NetworkInterface>
<NetworkInterfaces>
<ConfigurationSet>
</ConfigurationSets>
<ResourceExtensionReferences>
<ResourceExtensionReference>
<ReferenceName>name-of-reference</ReferenceName>
<Publisher>name-of-publisher</Publisher>
<Name>name-of-extension</Name>
<Version>version-of-extension</Version>
<ResourceExtensionParameterValues>
<ResourceExtensionParameterValue>
<Key>name-of-parameter-key</Key>
<Value>parameter-value</Value>
<Type>type-of-parameter</Type>
</ResourceExtensionParameterValue>
</ResourceExtensionParameterValues>
<State>state-of-resource</State>
<Certificates>
<Certificate>
<Thumbprint>certificate-thumbprint</Thumbprint>
<ThumbprintAlgorithm>certificate-algorithm</ThumbprintAlgorithm>
</Certificate>
</Certificates>
</ResourceExtensionReference>
</ForceUpdate>force-update</ForceUpdate>
</ResourceExtensionReferences>
<AvailabilitySetName>name-of-availability-set</AvailabilitySetName>
<DataVirtualHardDisks>
<DataVirtualHardDisk>
<HostCaching>caching-mode</HostCaching>
<DiskName>name-of-disk</DiskName>
<Lun>logical-unit-number</Lun>
<LogicalDiskSizeInGB>size-in-gb-of-data-disk</LogicalDiskSizeInGB>
<MediaLink>path-to-vhd</MediaLink>
</DataVirtualHardDisk>
</DataVirtualHardDisks>
<OSVirtualHardDisk>
<HostCaching>caching-mode</HostCaching>
<DiskLabel>label-of-operating-system-disk</DiskLabel>
<MediaLink>path-to-vhd</MediaLink>
<SourceImageName>name-of-source-image</SourceImageName>
</OSVirtualHardDisk>
<RoleSize>size-of-virtual-machine</RoleSize>
<ProvisionGuestAgent>install-an-agent</ProvisionGuestAgent>
</PersistentVMRole>
The following table describes the elements of the request body.
Element name |
Description |
---|---|
ConfigurationSets |
Optional. Contains a collection of configuration sets that define system and application settings. |
ResourceExtensionReferences |
Optional. Contains a collection of resource extensions that are to be installed on the Virtual Machine. This element is used if ProvisionGuestAgent is set to true. The ResourceExtensionReferences element is only available using version 2013-11-01 or higher. |
AvailabilitySetName |
Optional. Specifies the name of a collection of Virtual Machines. Virtual Machines specified in the same availability set are allocated to different nodes to maximize availability. |
DataVirtualHardDisks |
Optional. Contains the parameters that are used to add a data disk to a Virtual Machine. |
OSVirtualHardDisk |
Required. Contains the parameters that are used to create the operating system disk for a Virtual Machine. |
RoleSize |
Optional. Specifies the size of the Virtual Machine. The default size is Small. |
ProvisionGuestAgent |
Optional. Indicates whether the VM Agent is installed on the Virtual Machine. To run a resource extension in a Virtual Machine, this agent must be installed. Possible values are:
If the VM Agent has already been installed on a Virtual Machine, the value cannot be false. |
ConfigurationSets
Contains a collection of configuration sets that define system and application settings.
Element name |
Description |
---|---|
ConfigurationSetType |
Required. You can only update settings in the NetworkConfiguration set. |
InputEndpoints |
Optional. Contains a collection of external endpoints for the Virtual Machine. |
SubnetNames |
List of Virtual Network Subnet Names that the deployment belongs to. Note: It is not permitted to update to an empty list. If this element is used with the StaticVirtualNetworkIPAddress element, then updates are not allowed to this parameter. |
StaticVirtualNetworkIPAddress |
Optional. Specifies the internal IP address for the Virtual Machine in a Virtual Network. If you specify this element, you must also specify the SubnetNames element with only one subnet defined. The IP address specified in this element must belong to the subnet that is defined in SubnetNames and it should not be the first four IP addresses or the last IP address in the subnet. The StaticVirtualNetworkIPAddress element is only available using version 2013-11-01 or higher. |
NetworkSecurityGroup |
Optional. Represents the name of the Network Security Group that will be associated with the Virtual Machine. Network Security Group must exist in the context of subscription and be created in same region to which the virtual machine will be deployed. The NetworkSecurityGroup element is only available using version 2014-10-01 or higher. |
PublicIPs |
Optional. Contains a public IP address that can be used in addition to default virtual IP address for the Virtual Machine. The PublicIPs element is only available using version 2014-05-01 or higher. |
NetworkInterfaces |
Optional, A set of secondary network interfaces. The number of secondary network interfaces allowed depends on the size of the virtual machine. The NetworkInterfaces element is only available using version 2014-08-01 or higher. |
InputEndpoints
Contains a collection of external endpoints for the Virtual Machine.
Element name |
Description |
---|---|
InputEndpoint |
Required. Specifies the properties that define an external endpoint for the Virtual Machine. |
LoadBalancedEndpointSetName |
Optional. Specifies a name for a set of load-balanced endpoints. Specifying this element for an endpoint adds it to the set. Do not set this property if you are adding the endpoint to connect to the Virtual Machine by using the Remote Desktop. The endpoint name must be unique within the scope of the Virtual Machine. |
LocalPort |
Required. Specifies the internal port on which the Virtual Machine is listening. |
Name |
Required. Specifies the name of the external endpoint. |
Port |
Required. Specifies the external port to use for the endpoint. |
Optional. Contains properties that define the endpoint settings that the load balancer uses to monitor the availability of the Virtual Machine before forwarding traffic to it. |
|
Protocol |
Required. Specifies the transport protocol for the endpoint. Possible values are:
The default value is false. |
EnableDirectServerReturn |
Optional. Specifies whether the endpoint uses Direct Server Return. The EnableDirectServerReturn element is not supported for RDP, SSH, or WinRM endpoints and it is not supported when the public port and local port of an endpoint are different. You cannot disable EnableDirectServerReturn on an endpoint. If EnableDirectServerReturn set to true, you cannot update the value of Protocol. It is recommended that this element is only used when setting up Virtual Machines for SQL Server and AlwaysOn Availability Groups. Possible values are:
The default value is false. |
Optional. Contains a collection of rules that control the network traffic to the endpoint. The EndpointAcl element is only available using version 2013-06-01 or higher. |
|
LoadBalancerName |
Optional. Specifies the name of the internal load balancer that is associated with this endpoint. The internal load balancer name is specified in LoadBalancers. The LoadBalancerName element is only available using version 2014-05-01 or higher. |
IdleTimeoutInMinutes |
Optional. Specifies the timeout for the TCP idle connection. The value can be set between 4 and 30 minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP. The IdleTimeoutInMinutes element is only available using version 2014-06-01 or higher. |
LoadBalancerProbe
Contains properties that define the endpoint settings that the load balancer uses to monitor the availability of the Virtual Machine before forwarding traffic to it.
Element name |
Description |
---|---|
Path |
Optional. Specifies the relative path to inspect to determine the availability status of the Virtual Machine. If Protocol is set to TCP, this value must be NULL. Example: path The probe will use https://example.com/path to perform the probe. |
Port |
Optional. Specifies the port to use to inspect the availability status of the Virtual Machine. |
Protocol |
Optional. Specifies the protocol to use to inspect the availability status of the Virtual Machine. Possible values are:
|
IntervalInSeconds |
Optional. Specifies the interval for the load balancer probe in seconds. The minimum value is 5 seconds. The default is 15 seconds. |
TimeoutInSeconds |
Optional. Specifies the timeout for the load balancer probe in seconds. The minimum value is 11 seconds. The default is 31 seconds. |
EndpointAcl
Contains a collection of rules that control the network traffic to the endpoint.
Element name |
Description |
---|---|
Rules |
Required. Specifies a collection of access control rules. A maximum of 50 rules are allowed. |
Rule |
Required. Specifies the definition of an access control rule. |
Order |
Required. Specifies the priority of the rule. The value can be between 0 and 65535. The order number must be unique for each rule in the collection. The lower the order number, the higher the priority of the rule. |
Action |
Required. Specifies whether traffic that matches the rule should be permitted or denied. Possible values are:
|
RemoteSubnet |
Required. Specifies the subnet for the rule. The subnet must be in IPV4 Classless Inter-Domain Routing (CIDR) notation, and must be a valid subnet. For example, 10.0.0.0/24 |
Description |
Optional. Specifies a description for the rule. The maximum length of the description is 256 characters. |
PublicIPs
Contains a public IP address that can be used in addition to default virtual IP address for the Virtual Machine.
Element name |
Description |
---|---|
PublicIP |
Required. Specifies an additional IP public address that can be used to communicate with the Virtual Machine. |
Name |
Required. Specifies the name of the public IP address. |
IdleTimeoutInMinutes |
Optional. Specifies the timeout for the TCP idle connection. The value can be set between 4 and 30 minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP. The IdleTimeoutInMinutes element is only available using version 2014-06-01 or higher. |
DomainNameLabel |
Optional. Specifies the domain name label for the public IP. The DomainNameLabel element is only available using version 2015-03-01 or higher. |
NetworkInterfaces
Contains a set of secondary network interfaces.
Element name |
Description |
---|---|
NetworkInterface |
Required. Specifies a secondary network interface. |
Name |
Required, Specifies the name of the secondary network interface. |
IPConfigurations |
Required. Specifies a set of IP address configurations for a secondary network interface. |
IPConfigurations
Specifies a set of IP address configurations for a secondary network interface.
Element name |
Description |
---|---|
IPConfiguration |
Required. Specifies an IP address configuration for a secondary network interface. Currently only one IP address configuration is supported for a secondary network interface. |
SubnetName |
Required. Specifies the name of the virtual network subnet that this IP address configuration belongs. |
Address |
Required, Specifies the internal IP address configured for a secondary network interface. |
SubnetNames
Contains a list of subnets to which the Virtual Machine belongs.
Element name |
Description |
---|---|
SubnetName |
Required. Specifies the name of a subnet to which the Virtual Machine belongs. |
DataVirtualHardDisks
Contains the parameters that are used to add a data disk to a Virtual Machine.
Element name |
Description |
---|---|
DataVirtualHardDisk |
Required. Specifies the properties that are used to create a data disk. |
HostCaching |
Optional. Specifies the caching behavior of the data disk for read/write efficiency. Setting this property impacts the consistency of the disk. Possible values are:
The default value is None. |
DiskName |
Optional. If the disk that is being added is already registered in the subscription, this element is used to identify the disk to add. If a new disk and the associated VHD is being created by Azure, this element is not used and Azure assigns a unique name that is a combination of the deployment name, role name, and identifying number. The name of the disk must contain only alphanumeric characters, underscores, periods, or dashes. The name must not be longer than 256 characters. The name must not end with period or dash. |
Lun |
Optional. Specifies the Logical Unit Number (LUN) for the data disk. If the disk is the first disk that is added, this element is optional and the default value of 0 is used. If more than one disk is being added, this element is required. Valid LUN values are 0 through 31. |
LogicalDiskSizeInGB |
Optional. Specifies the size, in GB, of an empty disk to be attached to the Virtual Machine. If the disk that is being added is already registered in the subscription, this element is ignored. If the disk and VHD is being created by Azure as it is added, this element defines the size of the new disk. The number of disks that can be added to a Virtual Machine is limited by the size of the machine. |
MediaLink |
Optional. If the disk that is being added is already registered in the subscription or the VHD for the disk already exists in blob storage, this element is ignored. If a VHD file does not exist in blob storage, this element defines the location of the new VHD that is created when the new disk is added. Example: http://example.blob.core.windows.net/disks/mydatadisk.vhd |
SourceMediaLink |
Optional. If the disk that is being added is already registered in the subscription or the VHD for the disk does not exist in blob storage, this element is ignored. If the VHD file exists in blob storage, this element defines the path to the VHD and a disk is registered from it and attached to the virtual machine. |
OSVirtualHardDisk
Contains the parameters that are used to create the operating system disk for a Virtual Machine.
Element name |
Description |
---|---|
HostCaching |
Optional. Specifies the caching mode of the operating system disk. This setting impacts the consistency and performance of the disk. Possible values are:
The default value is ReadWrite. Changing this value causes the Virtual Machine to reboot. |
DiskLabel |
Optional. Specifies the description of the disk. |
MediaLink |
Optional. Specifies the location of the VHD file that is created when SourceImageName specifies a platform image. Example: http://contoso.blob.core.windows.net/disks/mydisk.vhd |
SourceImageName |
Optional. Specifies the name of the image to use to create the Virtual Machine. You can specify a user image or a platform image. An image is always associated with a VHD, which is a .vhd file stored as a page blob in a storage account in Azure. If you specify a platform image, an associated VHD is created and you must use the MediaLink element to specify the location in storage where the VHD will be located. |
ResourceExtensionReferences
Contains a collection of resource extensions that are to be installed on the Virtual Machine. A resource extension is a software component that is installed on the Virtual Machine. The VM Agent must be installed on the Virtual Machine to install resource extensions.
Element name |
Description |
---|---|
ResourceExtensionReference |
Required. Specifies the properties of a resource extension that should be installed on the Virtual Machine. |
ReferenceName |
Required. Specifies the reference name of the resource extension. |
Publisher |
Required. Specifies the name of the publisher who created the resource extension. You can use List Resource Extensions to find the publisher name of a resource extension. |
Name |
Required. Specifies the name of the resource extension. You can use List Resource Extensions to find the names of available resource extensions. |
Version |
Required. Specifies the version of the resource extension. You can set this value to * to use the latest version of the extension. If the extension has been recently added or updated, you must make sure that the value of ReplicationCompleted is set to true before you can use the version of the extension. |
ResourceExtensionParameterValues |
Optional. Contains a collection of parameters that are passed to the resource extension when it is installed. |
State |
Optional. Specifies the state of the resource extension. Possible values are:
The default value is enable. A new extension must be added with the enable state. The uninstall state is only available using version 2014-04-01 or higher. |
Certificates |
Optional. Contains a collection of certificates that are installed on the Virtual Machine and used by the extension. Before certificates can be included in this request, they must be added to the cloud service. The Certificates element is only available using version 2014-06-01 or higher. |
ForceUpdate |
Optional. Boolean. Set to “true” if you want to reapply a configuration to an extension when the configuration has not been updated. The ForceUpdate element is only available using version 2014-10-01 or higher. |
ResourceExtensionParameterValues
Contains a collection of parameters that are passed to the resource extension when it is installed.
Element name |
Description |
---|---|
ResourceExtensionParameterValue |
Required. Specifies the key, value, and type of the parameter. |
Key |
Required. Specifies the key of the parameter. |
Value |
Required. Specifies the base-64 encoded value of the parameter. If the configuration of the extension is formatted in XML, this value is validated by using the public or private schema. The schema that is used depends on the value of Type. If the configuration of the extension is formatted in JSON, this value must contain a valid JSON object. The public or private schemas cannot be used to validate the object. To use a JSON object, the version must be 2014-04-01 or higher. |
Type |
Required. Specifies the type for the resource extension. Possible values are:
|
Response
The response includes an HTTP status code, a set of response headers, and a response body.
Status Code
A successful operation returns status code 202 (Accepted).
Response Headers
The response for this operation includes the following headers. The response may also include additional standard HTTP headers.
Response Header |
Description |
---|---|
x-ms-request-id |
A value that uniquely identifies a request made against the management service. |
Response Body
None.