1 out of 2 rated this helpful - Rate this topic

Create and Deploy the VM Role Service Model

Updated: April 6, 2011

[The VM Role feature of Windows Azure is being retired on May 15th, 2013. After the retirement date, VM role deployments will be deleted. To move forward with your existing applications, you can use Windows Azure Virtual Machines. For more information about using Virtual Machines for your application, see Moving from VM Role to Windows Azure Virtual Machines.

A VM Role is the same as the other roles in needing the service definition and service configuration files to be included in cloud service in Windows Azure. To create instances of a VM Role, you must deploy a service model package to Windows Azure. For more information about creating the service model files, see Cloud Services (Hosted Services).

For more information about the elements that are used in a service definition file for a VM Role, see VirtualMachineRole Schema. For more information about the elements that are used in a service configuration file for a VM Role, see Service Configuration Schema.

Before you complete this task, you must have completed Upload a VHD to Windows Azure.

Define the service model files

Using a text editor to create the service model files

You can use your favorite text editor to create the service model files. Complete the following steps to create the ServiceDefinition.csdef file:

To create the service definition file

Open a text editor, such as Notepad.

The .csdef file must have a ServiceDefinition element. The following code example shows the definition of this element:


<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
</ServiceDefinition>

You must add the VirtualMachineRole element to the ServiceDefinition element. The following example shows the addition of the VirtualMachineRole element:


<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
   <VirtualMachineRole name="MyVMRole" vmsize="Small">
   </VirtualMachineRole>
</ServiceDefinition>

Where name is the name of the VM Role that is displayed in the Management Portal, and vmsize is the size that Windows Azure assigns for the VM Role instances. The vmsize attribute is optional, if you do not specify the size, the default size of Small is used. If you specify the vmsize attribute, you must ensure that the size corresponds to the size that you chose for the base VHD. The following table lists the allowable sizes of VHDs in Windows Azure.

Important
For dynamic disks, the sizes in the table are the maximum sizes that the VHD can grow to as additional space is required.

Windows Azure VM size	Maximum mounted VHD size
Extra Small	15 GB
Small	35 GB
Medium, Large, or Extra Large	65 GB

(Optional) Import the modules for diagnostics, remote desktop connections, or Windows Azure Connect. The following example shows the addition of the Imports element with the Import elements:


<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
   <VirtualMachineRole name="MyVMRole" vmsize="Small">
   <Imports>
      <Import moduleName="Diagnostics" />
      <Import moduleName="RemoteAccess" />
      <Import moduleName="RemoteForwarder" />
      <Import moduleName="Connect" />
   </Imports>
   </VirtualMachineRole>
</ServiceDefinition>

For more information about using these modules, see:

Add the endpoints that you need for your application. The following example shows the addition of the Endpoints element with an InputEndpoint defined for the http protocol on port 8080:


<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
   <VirtualMachineRole name="MyVMRole" vmsize="Small">
      <Imports>
         <Import moduleName="Diagnostics" />
         <Import moduleName="RemoteAccess" />
         <Import moduleName="RemoteForwarder" />
         <Import moduleName="Connect" />
      </Imports>
      <Endpoints>
         <InputEndpoint name="Endpoint1" protocol="http" port="8080" localPort="8080" />
      </Endpoints>
   </VirtualMachineRole>
</ServiceDefinition>

Save the file in the root folder of the application as ServiceDefinition.csdef.

To create the service configuration file

Open a text editor, such as Notepad.

The .cscfg file must have a ServiceConfiguration element. The following code example shows the definition of this element:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
</ServiceConfiguration>

You must add the Role element to the ServiceConfiguration element. The following example shows the addition of the Role element:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
   </Role>
</ServiceConfiguration>

Important
The value for the name attribute must match the name that was defined for the VirtualMachineRole element that was defined in the service definition file.

Define the number of instances that are needed for the VM Role. The following example shows the addition of the Instances element:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="2" />
   </Role>
</ServiceConfiguration>

You should set the count value to at least 2 to ensure availability of your application.

Specify the VHD file that you want to use to initialize VM Role instances. This can either be a base VHD or a differencing VHD. The following example shows the addition of the OsImage element:
Copy
<?xml version="1.0" encoding="utf-8"?> <ServiceConfiguration serviceName="MyServiceName" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration"> <Role name="MyVMRole"> <Instances count="2" /> <OsImage href="base.vhd" /> </Role> </ServiceConfiguration>
For more information about creating the base VHD, see Create a Server Image for a VM Role in Windows Azure. For more information about using a differencing VHD, see Change the Server Image for a VM Role in Windows Azure.

(Optional) If you added the Diagnostics module to the service definition file, define the configuration settings for the module. The following example shows the configuration settings for the Diagnostics module:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="2" />
      <OsImage href="base.vhd" />
      <ConfigurationSettings>
         <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
            value="DefaultEndpointsProtocol=https;AccountName=AccountName;AccountKey=AccountKey" />
      </ConfigurationSettings>
   </Role>
</ServiceConfiguration>

(Optional) If you added the RemoteAccess and the RemoteForwarder modules, define the configuration settings for the modules. The following example shows the configuration settings for the RemoteAccess and RemoteForwarder modules:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="2" />
      <OsImage href="base.vhd" />
      <ConfigurationSettings>
         <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
            value="DefaultEndpointsProtocol=https;AccountName=AccountName;AccountKey=AccountKey" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername" 
            value="UserAccountName" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword" 
            value="EncryptedPassword" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountExpiration" 
            value="ExpirationDate" /> 
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteForwarder.Enabled" value="true" />
      </ConfigurationSettings>
   </Role>
</ServiceConfiguration>

AccountUserName is the name of a user account that is created when the VM Role instance is created. AccountEncryptedPassword is the encrypted password for the user account that is created. AccountExpiration is the date that the user account expires. For more information about configuring a remote desktop connection, see Set Up a Remote Desktop Connection for a Role in Windows Azure.

(Optional) If you added the Connect module, define the configuration settings for the module. The following example shows the configuration settings for the Connect module:


<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="2" />
      <OsImage href="base.vhd" />
      <ConfigurationSettings>
         <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
            value="DefaultEndpointsProtocol=https;AccountName=AccountName;AccountKey=AccountKey" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername" 
            value="UserAccountName" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword" 
            value="EncryptedPassword" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountExpiration" 
            value="ExpirationDate" /> 
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteForwarder.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.ActivationToken" 
            value="ActivationToken"/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Refresh" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Diagnostics" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.WaitForConnectivity" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.EnableDomainJoin" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainFQDN" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainControllerFQDN" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainAccountName" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainPassword" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainOU" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DNSServers" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Administrators" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainSiteName" value=""/>
      </ConfigurationSettings>
   </Role>
</ServiceConfiguration>

ActivationToken is the token that you retrieved from the Management Portal. The remainder of the required and optional settings are used for joining role instances to a domain. For more information about configuring a VM Role for Windows Azure Connect, see Enable Windows Azure Connect for a VM Role.

Add the configuration information for the certificates that are used by the cloud service. The following example shows the addition of the certificate for remote access:

<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="2" />
      <OsImage href="base.vhd" />
      <ConfigurationSettings>
         <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
            value="DefaultEndpointsProtocol=https;AccountName=AccountName;AccountKey=AccountKey" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername" 
            value="UserAccountName" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword" 
            value="EncryptedPassword" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountExpiration" 
            value="ExpirationDate" /> 
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteForwarder.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.ActivationToken" 
            value="ActivationToken"/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Refresh" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Diagnostics" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.WaitForConnectivity" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.EnableDomainJoin" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainFQDN" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainControllerFQDN" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainAccountName" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainPassword" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainOU" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DNSServers" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.Administrators" value=""/>
         <Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainSiteName" value=""/>
      </ConfigurationSettings>
      <Certificates>
         <Certificate name="Microsoft.WindowsAzure.Plugins.RemoteAccess.PasswordEncryption" 
            thumbprint="CertificateThumbprint" thumbprintAlgorithm="sha1" />
      </Certificates>
   </Role>
   

</ServiceConfiguration>

For more information about creating and using certificates with a VM Role, see Use Certificates With a VM Role in Windows Azure.

Save the file in the root folder of the application as ServiceConfiguration.cscfg.

Using Visual Studio to create the service model files

Note
You must install the Windows Azure Tools for Visual Studio 2010 to complete the steps in this section. To download the tools, see Windows Azure Downloads.

To define and configure the settings for a VM Role in Visual Studio

Open Visual Studio 2010 as an administrator.
Create a new project by using the Windows Azure Project template.
Specify a name for your project and proceed through the wizard without selecting a role template. By doing this, you will create a project that contains only a service definition file and a service configuration file.
To add the VM Role elements, right-click Roles, click Add, and then click Add New Virtual Machine Role.
You must enter the credentials that are used for the VM Role, which are the certificate thumbprint and the subscription identifier. You can find this information in the Properties pane of the Management Portal.

After entering the credentials, you select the base VHD that you previously uploaded.

At this point in the process, the service definition contains the following information for the VM Role:

<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyServiceName"
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
   <VirtualMachineRole name="VMRole1" />
</ServiceDefinition>

And the service configuration contains the following information:

  
<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyServiceName" 
   xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="MyVMRole">
      <Instances count="1" />
   </Role>
</ServiceConfiguration>

Ensure that you set the instances count to at least 2 and that the appropriate VM size is selected. To do this:
1. In Solution Explorer, right-click the role node, and then click Properties.
2. On the Configuration page, change the Instance count to 2 and select the VM size. The following table lists the allowable sizes of VHDs in Windows Azure.
  
  Important
  For dynamic disks, the sizes in the table are the maximum sizes that the VHD can grow to as additional space is required.
  
  Windows Azure VM size Maximum mounted VHD size
  Extra Small
  15 GB
  Small
  35 GB
  Medium, Large, or Extra Large
  65 GB
(Optional) Enable Diagnostics. You can collect diagnostic data related to the running role instances.
1. In Solution Explorer, right-click the role node, and then click Properties.
2. On the Configuration page, select Enable Diagnostics.
  
  If you enable diagnostic data collection, you must provide the credentials for a storage account. The default is to use the local storage account, but for deploying to Windows Azure you must define the settings for a Windows Azure storage account.
Add an input endpoint for communication with the role instance. To do this, on the Endpoints page, click Add Endpoint, enter the name for the endpoint, select the type and the protocol, and then specify the port number.

(Optional) Enable Windows Azure Connect for the role instances.

In Solution Explorer, right-click the role, and then click Properties.
In the Properties sheet, select the Virtual Network tab.

Select the Activate Windows Azure Connect check box, and then paste the activation token in the text box.

The following line is added to the service definition file for importing the Connect module:

<Import moduleName="Connect" />

The following information is also added to the service configuration file:


<Setting name="Microsoft.WindowsAzure.Plugins.Connect.ActivationToken" value="ActivationToken"/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.Refresh" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.Diagnostics" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.WaitForConnectivity" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.EnableDomainJoin" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainFQDN" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainControllerFQDN" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainAccountName" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainPassword" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainOU" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DNSServers" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.Administrators" value=""/>
<Setting name="Microsoft.WindowsAzure.Plugins.Connect.DomainSiteName" value=""/>

The only setting value that is needed for a connection that is not domain joined is the ActivationToken. If you intend to join the VM Role instance to a domain, you must provide required and optional values for the remainder of the settings.

(Optional) Configure the remote desktop connection while publishing the package. Right click the project, click Publish, and then click Configure Remote Desktop connections.

Select Enable connections for all roles.
Select the certificate that you added to the cloud service.

Enter the name and password of the account that is used for the remote desktop connection.

The service definition now looks like the following:


<ServiceDefinition name="MyVMRole" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">
   <VirtualMachineRole name="VMRole1" vmsize="Medium">
      <Imports>
         <Import moduleName="Diagnostics" />
         <Import moduleName="RemoteAccess" />
         <Import moduleName="RemoteForwarder" />
      </Imports>
      <Endpoints>
         <InputEndpoint name="Endpoint1" protocol="http" port="80" />
      </Endpoints>
   </VirtualMachineRole>
</ServiceDefinition>

And the service configuration looks like the following:


<ServiceConfiguration serviceName="MyVMRole" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
   <Role name="VMRole1">
      <Instances count="2" />
      <OsImage href="base.vhd" />
      <ConfigurationSettings>
         <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" 
                  value=" DefaultEndpointsProtocol=https;AccountName=AccountName;AccountNumber=AcountNumber" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.Enabled" value="true" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountUsername" 
                  value="AccountName" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountEncryptedPassword" 
                  value="EncryptedPassword" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountExpiration" 
                  value="ExpirationDate" />
         <Setting name="Microsoft.WindowsAzure.Plugins.RemoteForwarder.Enabled" value="true" />
      </ConfigurationSettings>
      <Certificates>
         <Certificate name="Microsoft.WindowsAzure.Plugins.RemoteAccess.PasswordEncryption" 
                      thumbprint="CertThumbprint" thumbprintAlgorithm="sha1" />
      </Certificates>
   </Role>
</ServiceConfiguration>

Note
When you deploy the package to Windows Azure and you have enabled diagnostics, you must ensure that valid Windows Storage account credentials are used for the diagnostics connection string.

Click OK. You will see the VM Role instances start and the status move to Ready in the portal.

Package and deploy the service model

You can use the CSPack Command Line Tool to package a service model for a VM Role application and then deploy the package using the Management Portal. You can also use Visual Studio 2010 to package and deploy the application. Before you start the procedures in this section, you must ensure that you have created a cloud service and a storage account in Windows Azure.

Using the CSPack Command-Line Tool and the Management Portal to package and deploy the service model

To deploy an application that contains a VM Role to Windows Azure, you must first upload the VHD and then you must package and deploy the service model, which consists of the service definition file and the service configuration file. To package the service mode files, you use the CSPack Command-Line Tool. After you create the service model package, you deploy the package to Windows Azure by using the Windows Azure Management Portal.

To package the service model files

Click Start, point to All Programs, and then click Windows Azure SDK.
Right-click Windows Azure SDK Command Prompt, and then click Run as administrator.
In the Windows Azure SDK Command Prompt window, change the directory to where your application files are located.
Type the following command:
Copy
cspack ServiceDefinition.csdef
Where ServiceDefinition is the name of your ServiceDefinition.csdef file.

To deploy the service model package

Open the Management Portal.
Create a new cloud service if you do not already have one.
You can deploy your application to the staging deployment environment or the production deployment environment. Click the cloud service in the center pane, and then click either New Staging Deployment, or New Production Deployment.
On the Create a New Deployment page, enter the name of the new deployment, browse to and select the package file that you previously created, browse to and select the configuration file of the service model, and then click OK.

Using Visual Studio to package and deploy the service model

To package and deploy the service model

Open Visual Studio 2010 as an administrator, and then open Windows Azure Project that you previously created.
In Solution Explorer, right-click the VM Role project, and then click Publish.
In the Deploy Windows Azure Project dialog, click the Credentials drop-down and select <Add…> to add a new credential. In the Windows Azure Project Management Authentication dialog:
1. Select the management certificate that you created and added to Windows Azure.
2. Enter the subscription ID. You can copy and paste this value from the Properties pane of the Management Portal.
3. Type a name that is used to identify the credentials, and then click OK.
After the credentials are verified in Windows Azure, you select the Deployment environment to deploy to.
Select the storage account to use for deployment.
Type a name to identify the deployment in the Management Portal.
Click OK.

Community Additions

ADD

Create and Deploy the VM Role Service Model

See Also

Concepts

Community Additions