VirtualMachineRole Schema
Updated: June 7, 2012
[This topic contains preliminary content for the current release of Windows Azure.]
The Windows Azure Virtual Machine role is a special type of role that enables you to define the configuration and updates of the operating system for the virtual machine.
 Note |
|---|
| The virtualMachine role is only available using the Windows Azure SDK version 1.3 or higher. |
The default extension for the service definition file is .csdef.
Basic service definition schema for a VM role
The basic format of the service definition file is as follows.
<ServiceDefinition …> <VirtualMachineRole name="<vm-role-name>" vmsize="[ExtraSmall|Small|Medium|Large|ExtraLarge]"> <Certificates> <Certificate name="<certificate-name>" storeLocation="<certificate-store>" storeName="<store-name>" /> </Certificates> <ConfigurationSettings> <Setting name="<setting-name>" /> </ConfigurationSettings> <Imports> <Import moduleName="<import-module>"/> </Imports> <Endpoints> <InputEndpoint certificate="<certificate-name>" ignoreRoleInstanceStatus="[true|false]" name="<input-endpoint-name>" protocol="[http|https|tcp|udp]" localPort="<port-number>" port="<port-number>" loadBalancerProbe="<load-balancer-probe-name>" /> <InternalEndpoint name="<internal-endpoint-name>" protocol="[http|tcp|udp|any]" port="<port-number>"> <FixedPort port="<port-number>"/> <FixedPortRange min="<minimum-port-number>" max="<maximum-port-number>"/> </InternalEndpoint> <InstanceInputEndpoint name="<instance-input-endpoint-name>" localPort="<port-number>" protocol="[udp|tcp]"> <AllocatePublicPortFrom> <FixedPortRange min="<minimum-port-number>" max="<maximum-port-number>"/> </AllocatePublicPortFrom> </InstanceInputEndpoint> </Endpoints> <LocalResources> <LocalStorage name="<local-store-name>"/> </LocalResources> </VirtualMachineRole> </ServiceDefinition>
Schema elements
The VirtualMachineRole node of the service definition file includes these elements, described in detail in subsequent sections in this topic:
VirtualMachineRole Element
The VirtualMachineRole element describes a role in which you can control the configuration and updates of the operating system for the virtual machine in a more granular manner. A service may contain zero or more Virtual Machine roles.
The following table describes the attributes of the VirtualMachineRole element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. The name for the virtual machine role. The role's name must be unique. |
|
vmsize |
string |
Optional. Set this value to change the size of the VM allotted to this role. The default value is Small. Other possible values are ExtraSmall, Medium, Large, and ExtraLarge. For more information on configuring the virtual machine size, see Configure Virtual Machine Sizes. |
ConfigurationSettings Element
The ConfigurationSettings element describes the collection of configuration settings for a virtual machine role. This element is the parent element of the Setting Element.
Setting Element
The Setting element describes a name/value pair that specifies a configuration setting for an instance of a role.
The following table describes the attributes of the Setting element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A unique name for the configuration setting. |
The configuration settings for a role are name/value pairs that are declared in the service definition file and set in the service configuration file.
LocalResources Element
The LocalResources element describes the collection of local storage resources for a virtual machine role. This element is the parent element of the LocalStorage Element.
LocalStorage Element
The LocalStorage element identifies a local storage resource that provides file system space for the service at runtime. A role may define zero or more local storage resources.
The following table describes the attributes of the LocalStorage element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A unique name for the local store.
|
The name of the directory allocated to the local storage resource corresponds to the value provided for the name attribute. For more information on accessing a local storage resource from code running within a role instance, see Configure Local Storage Resources.
Endpoints Element
The Endpoints element describes the collection of input (external), internal, and instance input endpoints for a role. This element is the parent element of the InputEndpoint, InternalEndpoint, and InstanceInputEndpoint elements.
Input and Internal endpoints are allocated separately. A service can have a total of 25 input, internal, and instance input endpoints which can be allocated across the 25 roles allowed in a service. For example, if have 5 roles you can allocate 5 input endpoints per role or you can allocate 25 input endpoints to a single role or you can allocate 1 input endpoint each to 25 roles.
|
Note |
|---|
| Each role deployed requires one instance per role. The default provisioning for a subscription is limited to 20 cores and thus is limited to 20 instances of a role. If your application requires more instances than is provided by the default provisioning see Billing, Subscription Management and Quota Support for more information on increasing your quota. |
InputEndpoint Element
The InputEndpoint element describes an external endpoint for a Virtual Machine Role.
You can define multiple endpoints that are a combination of HTTP, HTTPS, UDP, and TCP endpoints.
The parent element of the InputEndpoint element is either the Endpoints Elementelement or the InputEndpoint element.
The following table describes the attributes of the InputEndpoint element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A unique name for the external endpoint. |
|
protocol |
string |
Required. The transport protocol for the external endpoint. For a virtual machine role, possible values are HTTP, HTTPS, UDP, and TCP. |
|
port |
int |
Required. The port for the external endpoint. You can specify any port number you choose, but the port numbers specified for each role in the service must be unique. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
|
certificate |
string |
Required for an HTTPS endpoint. The name of a certificate defined by a Certificate Element. |
|
localPort |
int |
Optional. Specifies a port used for internal connections on the endpoint. The localPort attribute maps the external port on the endpoint to an internal port on a role. This is useful in scenarios where a role must communicate to an internal component on a port that different from the one that is exposed externally. If not specified, the value of Set localPort is the same as the one set in the port attribute. Set localPort to “*” to allow the Windows Azure fabric is assigns an unallocated port that is discoverable using the runtime API. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
|
ignoreRoleInstanceStatus |
boolean |
Optional. When the value of this attribute is set to true, the status of a service is ignored and that the endpoint will not be removed by the load balancer. The default value is false. Setting this value true useful for debugging busy instances of a service. |
|
loadBalancerProbe |
string |
Optional. The name of the load balancer probe associated with the input endpoint. For more information, see LoadBalancerProbe Schema.
|
InternalEndpoint Element
The InternalEndpoint element describes an internal endpoint to a virtual machine role. An internal endpoint is available only to other role instances running within the service; it is not available to clients outside the service.
The following table describes the attributes of the InternalEndpoint element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A unique name for the internal endpoint. |
|
protocol |
string |
Required. The transport protocol for the internal endpoint. For a virtual machine role, possible values are HTTP, TCP, UDP, or ANY. A value of ANY specifies that any protocol, any port is allowed. |
|
port |
int |
Optional. The port used for internal load balanced connections on the endpoint. A Load balanced endpoint uses two ports. The port used for the public IP address, and the port used on the private IP address. Typically these are these are set to the same, but you can choose to use different ports. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
InstanceInputEndpoint Element
The InstanceInputEndpoint element describes an instance input endpoint to a web role. An instance input endpoint is associated with a specific role instance by using port forwarding in the load balancer. Each instance input endpoint is mapped to a specific port from a range of possible ports. The AllocatePublicPortFrom element is a child element and describes the public port range that can be used by external customers to access each instance input endpoint.
|
Note |
|---|
| The InstanceInputEndpoint element is only available using the Windows Azure SDK version 1.7 or higher. |
The following table describes the attributes of the InstanceInputEndpoint element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A unique name for the endpoint. |
|
localPort |
int |
Required. Specifies the internal port that all role instances will listen to in order to receive incoming traffic forwarded from the load balancer. Possible values range between 1 and 65535, inclusive. |
|
protocol |
string |
Required. The transport protocol for the internal endpoint. Possible values are udp or tcp. Note: use "tcp" for http/https based traffic. |
AllocatePublicPortFrom Element
The AllocatePublicPortFrom element describes the public port range that can be used by external customers to access each instance input endpoint. The public (VIP) port number is allocated from this range and assigned to each individual role instance endpoint during tenant deployment and update.
This element is the parent of the FixedPortRange Element element.
|
Note |
|---|
| The AllocatePublicPortFrom element is only available using the Windows Azure SDK version 1.7 or higher. |
FixedPort Element
The FixedPort element specifies the port for the internal endpoint. The FixedPort element sets the port used for load balanced connections on the endpoint.
| Attribute | Type | Description |
|---|---|---|
|
port |
int |
Required. The port for the internal endpoint. This has the same effect as setting the FixedPortRange min and max to the same port. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
FixedPortRange Element
The FixedPortRange element specifies the range of ports for the Windows Azure fabric to use to assign the internal endpoint or instance input endpoint. The FixedPortRange element sets the port used for load balanced connections on the endpoint.
|
Note |
|---|
| The FixedPortRange element works differently depending on the element in which the FixedPortRange element resides. When the FixedPortRange element is in the InternalEndPoint element, the FixedPortRange element opens all ports on the Azure Load Balancer within the range of the min and max attributes for all virtual machines on which the role runs. When the FixedPortRange element is in the InstanceInputEndpoint element, the FixedPortRange element opens only one port within the range of the min and max attributes on each virtual machine running the role. |
| Attribute | Type | Description |
|---|---|---|
|
min |
int |
Required. The minimum port in the range. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
|
max |
string |
Required. The maximum port in the range. Possible values range between 1 and 65535, inclusive (Windows Azure SDK version 1.7 or higher). |
Certificates Element
The Certificates element describes the collection of certificates for a virtual machine role. It is the parent element of the Certificate element. A role may have any number of associated certificates. For more information on using the certificates element, see Associate a Certificate with a Service.
Certificate Element
The Certificate element describes a certificate that is associated with a virtual machine role.
The following table describes the attributes of the Certificate element:
| Attribute | Type | Description |
|---|---|---|
|
name |
string |
Required. A name for this certificate, which is used to refer to it when it is associated with an HTTPS InputEndpoint element. |
|
storeLocation |
string |
Required. The location of the certificate store where this certificate may be found on the local machine. Possible values are CurrentUser and LocalMachine. |
|
storeName |
string |
Required. The name of the certificate store where this certificate resides on the local machine. Possible values include the built-in store names My, Root, CA, Trust, Disallowed, TrustedPeople, TrustedPublisher, AuthRoot, AddressBook, or any custom store name. If a custom store name is specified, the store is automatically created. |
|
permissionLevel |
string |
Optional. Specifies the access permissions given to the role processes. If you want only elevated processes to be able to access the private key, then specify elevated permission. limitedOrElevated permission allows all role processes to access the private key. Possible values are limitedOrElevated or elevated. The default value is limitedOrElevated. |
Imports Element
The Imports element describes a collection of import modules for a virtual machine role that add components to the guest operating system. It is the parent element of the import element. This element is optional and a role can have only one runtime block.
|
Note |
|---|
| The Imports element is only available using the Windows Azure SDK version 1.3 or higher. |
Import Element
The Import element specifies a module to add to the guest operating system.
|
Note |
|---|
| The Import element is only available using the Windows Azure SDK version 1.3 or higher. |
The following table describes the attributes of the Import element:
| Attribute | Type | Description |
|---|---|---|
|
moduleName |
string |
Required. The name of the module to import. Valid import modules are:
The RemoteAccess and RemoteForwarder modules allow you to configure your role instance for remote desktop connections. For more information see Set Up a Remote Desktop Connection for a Role. The Diagnostics module allows you to collect diagnostic data for a role instance. For more information see Initialize the Windows Azure Diagnostic Monitor. The Connect module allows you to configure IPsec protected connections between computers or virtual machines (VMs) in your organization’s network, and roles running in Windows Azure. For more information see Configure Windows Azure Connect. |
See Also
