This post is about actually using the cluster once it has been deployed to Azure. I chose the theme of a Development Cluster to justify making a few changes to how I previously configured the cluster and show some new techniques.

As a developer I expect easy access to the development cluster. The goal is to allow developers to safely connect to the cluster to deploy and debug their map/reduce jobs. SSH provides all the necessary tools for this – secure connection and tunneling. SSH not only allows developers to establish a secure session with the cluster in Azure but it also allows for full integration with IDEs making the typical development tasks a breeze.

I will be referring to two of my previous posts on Setting Up a Hadoop Cluster and Configuring SSH. It would be helpful to have them open as you follow the setup instructions below.

The Development Cluster

In this scenario of a development cluster I will use a single host to run both the Name Node and the Job Tracker. This is obviously not true for every development cluster but suffices for this demo. The number of slaves is initially set to 3. You can dynamically change the cluster size as I demonstrated in my previous post. If you are going to try it you might also want to adjust the VM size to meet your needs.

The procedure for deploying a Hadoop cluster has not changed. The dependencies are different though. First is the Hadoop version, I had previously used 0.21 which is not supported by many development tools since it’s an unstable release. I reverted to the stable versions and ended up using 0.20.2. At the time of this writing 0.20.203.0rc1 was out but did not work on Windows. Cygwin needs the OpenSSH package installed to provide the SSH Windows Service (instructions in the SSH post). Finally is YAJSW. That didn’t technically need to be updated, I just grabbed the latest drop for which is Beta-10.8.

Just follow the instructions from my previous post using the updated dependencies and grab this cluster configuration template and this Visual Studio 2010 project instead. You should have the following files in a container in your storage account:

You should be able to deploy your development cluster by publishing the HadoopAzure project directly from Visual Studio.

Connecting to the Cluster

A developer needs to connect to the cluster using SSH. I demonstrated how to do that using PuTTY, the only difference here is that we will need to setup a couple of tunnels. This screen shows the two tunnels required to access the Name Node and Job Tracker.

Once you connect and login you can minimize the PuTTY window. We won’t be using it but it must be open for the tunnels to remain open.

Accessing the Cluster

With the tunnels open to the development cluster you can use it as if it was local.

SSH is capable of more than just remote access – copying files and tunneling are a few of the extra features. I’ll show how to get a SSH daemon working and how to connect to it for a remote session. I haven’t tested other features, let me know if you try anything else.

Cygwin

There are many SSH servers available for Windows. I will use the OpenSSH from Cygwin in this post.

The first task is to install Cygwin. It’s better to install it locally and package Cygwin in the Azure deployment package or create a zip file of the local installation and upload it to your Azure Storage account. The only extra package required is “openssh”.

Role Configuration

There are a few steps to configure a role to run the SSH service. I’ll describe only the main ones here, refer to the sample project at the bottom of the post for a complete working example.

1. Endpoint

The default SSH port is 22 hence the role must define the following endpoint:

  <Endpoints>
    <InputEndpoint name="SSH" protocol="tcp" port="22" localPort="22" />
  </Endpoints>

2. Create a user

You need an account to log in via SSH. Since this account will also be used to run the SSH Windows Service it must be in the Administrators Group.

  net user <username> <password> /add
  net localgroup Administrators <username> /add

3. Grant Privileges

The user account you created must have the required privileges to be used by a Windows Service. I used ntright.exe^[2] for granting the SeServiceLogonRight privilege.

4. Fix Unix File Permissions

Because Cygwin was copied to the VM instead of installed the Unix permissions for a few critical files must be fixed. This must be done from within Cygwin via a script.

5. Add the New User to Cygwin

The user account you previously created must be added to the Cygwin users list. Once again this must be done from the Cygwin environment.

6. Create and Start the Service

Cygwin includes a script to configure SSH as a Windows Service - ssh-host-config. After running this script a new service will be available and can be started the regular way or using the cygrunsrv command from Cygwin. These commands must be run using the account created in step 2 ^[1].

Remote Access

With the SSH enabled service deployed it’s time to connect to it. Using PuTTY simply enter the DNS name of your deployment in the Host Name field:

And if you want to avoid being disconnected because of timeouts you can set PuTTY to keep a heartbeat using any value under 60 seconds:

Then opening a connection will get you access to the VM:

SSH will actually allow you to connect to a service with multiple instances. You will not be able to specify the exact instance though, every new connection will be established to any one of the instances in the service.

Sample Project

This project creates a service with SSH enabled. It expects to find a zip file called cygwin.zip in your storage account. The zip file should contain the Cygwin install directory (e.g. C:\Cygwin).

Before you publish the project you must edit the EnableSSH.cmd and startSSH.sh files and enter the new username and password at the top of both files. There was no easy way to share that information between the Windows batch and the Shell script so it must be entered twice. You must also edit the DownloadBlob.ps1 file and enter your storage account information in the second to last line. You will also need to enter the container name in the same line.

References

1. Running Azure startup tasks as a real user
2. Windows Server 2003 Resource Kit Tools

Although that is a fine solution it would be nice to be able to issue remote commands from my local machine.

Turns out you can do exactly that using PowerShell Remoting.I am not going to cover the details of PowerShell Remoting in this post, I’ll just show the configuration needed to make it work for the simple case. PowerShell Remoting is very flexible, I encourage you to read more about it if you are not familiar with all it can do.

Prerequisite

You need a user account to remote access a VM. When you configure Remote Desktop an account is automatically created for you. Since we are not going to use Remote Desktop we need to create an account manually and because the setup steps require an Administrator account we will  add it to the Administrator’s group.

An account can be created with these two commands. Simply run them as part of a startup task with elevated privileges.

net user <username> <password> /add
net localgroup Administrators <username> /add

Configuration

PowerShell Remoting needs the correct network configuration to allow for remote connectivity. Since we will be accessing the VM over the web we are required to use HTTPS to secure the communication channel. Skipping over the details of Windows Remote Management which is used by PowerShell Remoting, I will just say the default HTTPS port is 5986.

To allow connectivity to the VM this endpoint must be added to the ServiceDefinition.csdef:

 
<endpoints> 
  <inputendpoint localport="5986" port="5986" protocol="tcp" name="WinRM" /> 
</endpoints> 

With the proper port open it is just a matter of enabling PowerShell Remoting. Two issues need to be resolved before enabling it.

The first is using the correct user account to setup Remoting. You must use the account previously created to run the script to setup Remoting^[1]. With these commands the user you previously created will execute the script e:\approot\StartRemotingListener.ps1:

schtasks /CREATE /TN "StartRemotingListener" /SC ONCE /SD 01/01/2020 /ST 00:00:00 
              /RL HIGHEST /RU <username> /RP <password> 
              /TR "powershell -ExecutionPolicy unrestricted 
                              -Command e:\approot\StartRemotingListener.ps1 -Force" /F
schtasks /RUN /TN "StartRemotingListener"

The second issue is configuring the certificate needed for the HTTPS connection. Acquiring a certificate might not be a problem for a production environment. You might already have one for your service and could reuse it. It can be a problem if your service doesn’t require a certificate for normal operation or for non-production environments.

Fortunately it is possible to generate a certificate using a PowerShell script^[2]. This script generates a certificate associated with the hostname of the VM. If you are going to use this script in production you should change $certId the fully qualified URL of your service.

function Create-Certificate($hostname) {
	$name = new-object -com "X509Enrollment.CX500DistinguishedName.1"
	$name.Encode("CN=$hostname", 0)
 
	$key = new-object -com "X509Enrollment.CX509PrivateKey.1"
	$key.ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
	$key.KeySpec = 1
	$key.Length = 1024
	$key.SecurityDescriptor = 
                 "D:PAI(A;;0xd01f01ff;;;SY)(A;;0xd01f01ff;;;BA)(A;;0x80120089;;;NS)"
	$key.MachineContext = 1
	$key.Create()
 
	$serverauthoid = new-object -com "X509Enrollment.CObjectId.1"
	$serverauthoid.InitializeFromValue("1.3.6.1.5.5.7.3.1")
	$ekuoids = new-object -com "X509Enrollment.CObjectIds.1"
	$ekuoids.add($serverauthoid)
	$ekuext = new-object -com "X509Enrollment.CX509ExtensionEnhancedKeyUsage.1"
	$ekuext.InitializeEncode($ekuoids)
 
	$cert = new-object -com "X509Enrollment.CX509CertificateRequestCertificate.1"
	$cert.InitializeFromPrivateKey(2, $key, "")
	$cert.Subject = $name
	$cert.Issuer = $cert.Subject
	$cert.NotBefore = get-date
	$cert.NotAfter = $cert.NotBefore.AddDays(180)
	$cert.X509Extensions.Add($ekuext)
	$cert.Encode()
 
	$enrollment = new-object -com "X509Enrollment.CX509Enrollment.1"
	$enrollment.InitializeFromRequest($cert)
	$certdata = $enrollment.CreateRequest(0)
	$enrollment.InstallResponse(2, $certdata, 0, "")
}
 
function Find-Certificate($hostname) {
	foreach ($cert in Get-ChildItem cert:\LocalMachine\My) { 
		if ($cert.Subject -eq ("CN=" + $hostname)) {
			return $cert
		}
	}
}
 
# Using the machine name - ok for staging deployments
# In a production environment this should be set to the public URL
$certId = $env:computername

Create-Certificate $certId
$cert = Find-Certificate $certId

winrm create winrm/config/listener?Address=*+Transport=HTTPS 
      `@`{Hostname=`"($certId)`"`;CertificateThumbprint=`"($cert.Thumbprint)`"`}

Set-Item WSMan:\localhost\Shell\MaxMemoryPerShellMB 2000

After you deploy a service you can use any of the remoting enabled cmdlets or start a remote session using:

Enter-PSSession -ConnectionUri https://<service id>.cloudapp.net:5986 
                     -Credential $cred -SessionOption (New-PSSessionOption -SkipCACheck 
                     -SkipCNCheck -SkipRevocationCheck) -Authentication Negotiate

You should then be connected to the VM and able to run any command on the remote machine.

Limitations

This method will only allow connections to services with a single instance because there is no way to target a specific VM in a service. This limitation probably means this technique is mostly useful for non-production services.

Another problem that might affect you are timeouts. Azure will close inactive connections after a period of time. If you leave your PowerShell window inactive too long you will need to reconnect.

Sample Project

You can download this project to see it all working. Before you publish it you will need to edit the EnablePSRemoting.cmd file and add a username and password in the first two lines. Make sure the password is complex enough otherwise the user creation will fail.

References

1. Running Azure startup tasks as a real user
2. Generating a certificate (self-signed) using powershell and CertEnroll interfaces

In this post I will demonstrate how to create a typical cluster with a Name Node, a Job Tracker and a customizable number of Slaves. You will also be able to dynamically change the number of Slaves using the Azure Management Portal. I will save the explanation of the mechanics for another post.

Follow these steps to create an Azure package for your Hadoop cluster:

Download all dependencies

• This Visual Studio 2010 project is pre-configured with Roles for each Hadoop component. Don’t worry if you don’t have Visual Studio or don’t want to install the express edition, you can do everything from the command line.
• The cluster configuration templates.
• Install the latest Azure SDK. As of this writing the latest version was 1.4.
• The Hadoop binaries.  I used version 0.21. Hadoop is distributed in a tar.gz file, you will need to convert it to a ZIP file. You can use 7-zip for the task.
• Now install Cygwin and package it in a single ZIP file. Hadoop 0.21 requires Cygwin under Windows. It’s fine if you don’t know anything about it, Hadoop uses it behind the scenes so you won’t need to even launch it. There is an on-going effort to remove this dependency for Hadoop 0.22 but it’s not ready yet. Just run the Cygwin install and accept all defaults. You should end up with Cygwin installed in c:\cygwin. Create a compressed folder of c:\cygwin called cygwin.zip.
• Download the latest version of Yet Another Java Service Wrapper. Beta-10.6 was the current version as of this writing.
• The last dependency is a Java VM to host Hadoop and YAJSW. If you don’t want to update any of the configuration files in this guide you will need to bundle your favorite JVM in a zip file called jdk.zip. All JVM files must be in a folder also called jvm in the ZIP file. If you have your JVM installed under C:\Program Files\Java\jdk1.6.0_<revision>\ you will need to rename (or copy) the jdk1.6.0_<revision> folder to jdk and zip it.

Configure your cluster

The custer-config.zip you downloaded has all the files needed to configure your Hadoop cluster. You will find the familiar [core|hdfs|mapred]-site.xml files there. Ignore all other files for now, I’ll explain what they are for in a later post. Edit the *-site.xml files as needed for your cluster configuration. Make sure to only add and not change any of the properties.

Create a new cluster-config.zip if you updated any for the XML files.

Upload all dependencies to your Azure Storage account

Create a container called bin and upload all zip files to it. Use your favorite tool for the job, I like ClumsyLeaf’s CloudXplorer. You should end up with these files in the bin container

Configure your Azure Deployment

Unzip the Visual Studio 2010 project. You can either use Visual Studio from here or update the required files using any text editor. I included a batch file to package the deployment if you are going down the command line route.

If you are using Visual Studio the only file you must change is NameNode\SetEnvironment.cmd. The projects that require this file have links to it. If you are not using Visual Studio you have to change it in three other places NameNode\bin\Debug, JobTracker\bin\Debug and NameNode\bin\Debug. Get an access key from your storage account and construct a connection string then paste it in the first line replacing [your connection string]. An Azure connection string has this format:

DefaultEndpointsProtocol=http;AccountName=[your_account_name];AccountKey=[key]

 Unless you used different versions of any of the dependencies you won’t need to change anything else.

The Azure deployment is set to use 1 large VM for the Name Node, 1 large VM for the Job Tracker and 4 Extra Large nodes as Slaves. If you are ok with that configuration skip to the next step. If you like anything different change the Roles configuration directly in Visual Studio or edit both the HadoopAzure\ServiceDefinition.csdef and HadoopAzure\ServiceConfiguration.cscfg to the desired VM sizes and count.

Deploy your cluster

Create a new service to host your Hadoop cluster. The project is pre-configured for remote access to the machines in the cluster. If you didn’t change the project configuration you will need to upload the certificate AzureHadoop.pfx in the root of the project to your service. The certificate password is hadoop. The deployment will fail if you don’t have this certificate.

If you are using Visual Studio 2010 you can deploy by right-clicking on the Cloud project and selecting deploy. If you are not just run the buildPackage.cmd from the root of the project using a Windows Azure SDK Command Prompt. You will get the Azure package Hadoop.cspkg to deploy using the Azure Management Portal.

Deploy your service (you can ignore the warning message). Wait for it to complete, you should see something like this:

Using your Hadoop cluster

Now that everything is up and running you can navigate to the Name Node Summary page. The URL is http://<your service name>.cloudapp.net:50070.

If you click on “Browse the filesystem” Hadoop will construct a URL with the IP address of one of the Slaves. That IP address is not accessible from the Internet so you will need to replace it in the URL with <your service name>.cloudapp.net and you will be able to browse the file system:

Let’s run one of the example jobs Hadoop provides to confirm the cluster is working. As it is configured right now you must log in to the Job Tracker to start a new job. I will present alternatives in a future post (hint Azure Connect).

Go back to the Azure Management Portal and RDP into the Job Tracker by selecting it and clicking “Connect” in the toolbar. The username is hadoop and the password is H1Doop. After you log in open a command prompt window and execute the following commands:

E:\AppRoot\SetEnvironment.cmd

cd /d %HADOOP_HOME%

Now you are ready to run a job. I put together a hadoop script so you don’t have to deal with Cygwin for launching jobs. The syntax is the same as the regular hadoop scripts. Let’s launch a small job:

bin\hadoop jar hadoop-mapred-examples-0.21.0.jar pi 20 200

If you navigate to the Job Tracker page you will see the job running. The URL is http://<your service name>.cloudapp.net:50030.

Congratulations, you just ran your first Hadoop job in Azure!

What can I do with my Hadoop cluster?

The cluster is fully operational. You can run any job you would like. You can also use the Azure Management Portal to dynamically change the number of Slaves. Hadoop will discover the new node(s) or find out nodes were removed and reconfigure the cluster accordingly.

I added an extra Slave node

And my cluster changed to

If you used Hadoop in production you know you must take extra steps to prepare the Name Node, mostly around high availability. That’s a topic in itself which I plan to discuss in another post. If you can’t wait and want setup a backup and/or a checkpoint node go ahead, that’s certainly part of the solution. Azure Drive is probably another piece.

Let me know your experiences using Hadoop in Azure.

One option is to rewrite parts of the legacy application to directly use Azure Storage instead of Shared Folders. This is the ideal way of migrating an application to the cloud. Your application will get all benefits of cloud storage, such as infinite storage and automatic replication, but more importantly I/O will be distributed in the cloud which can give some applications a significant performance boost.

Rewriting legacy applications is not always possible. You can still move these legacy applications to the cloud as-is but it requires some understanding of Azure to setup the environment correctly.

Enabling Shared Folders

The default Azure environment is locked down to reduce security exposure of each role. A role can only use the ports specified in the role definition, and that includes the ports needed for Shared Folders to work. The first step in enabling Shared Folders is to define two internal endpoints:

    <Endpoints> 

      <InternalEndpoint name="NetBIOSSession" protocol="tcp" port="139" />

      <InternalEndpoint name="SMB" protocol="tcp" port="445" />

    </Endpoints>

Keep in mind there is a limit to the number of endpoints a role can define. Currently a single role can define up to 5 endpoints.

Defining the required endpoints is not enough for SMB to work properly. The firewall must also be configured to enable file sharing. It can be done with this command:

netsh firewall set service type=fileandprint mode=enable profile=Current

These changes will allow SMB between roles but sharing folders will not be possible yet. The reason is the user account roles execute as – the SYSTEM account. Because your role is running under SYSTEM a new account must be created for all shared folder operations. You can use any programmatic way of creating an account, I like to use PowerShell for this purpose. The following script creates an account, it uses two variables set elsewhere $netuser and $password, for the account name and password, respectively.

# Create a user to manage shared folders

$server = "WinNT://" + $env:computername + ",computer"

$computer = [ADSI] $server

$newUser = $computer.Create("user", $netuser)

$newUser.put("Description", "Owner of shared folders in Azure")

$newUser.SetPassword($password)

$newUser.SetInfo()

All that is left is for the shared folder to be created. You must grant the required permissions to the account previously created for the share to be accessible remotely. The simplest way to share a folder is via the net share command. When you grant access to an account via net share you don’t automatically give permissions to access the local directory being shared so you will also need to grant the appropriate permissions to the local directory. Here is a PowerShell function that grants full permissions to a local folder to the $netuser account and creates a network share for this account to use:

function share_folder($folder, $label) {

  $acl = get-acl $folder

  $accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($netuser,"FullControl","Allow")

  $acl.SetAccessRule($accessRule)

  set-acl -path $folder -AclObject $acl

  $full_perm = "/GRANT:" + $netuser + ",FULL"

  net share $label`=$folder "$full_perm"

}

These commands must be executed with elevated privileges hence they must be in a startup task. The sample project at the end of this post has all these scripts bundled in the solution to demonstrate how to create and use shared folders.

Allocating Space

You should create all folders intended for sharing in the C: drive where you will find the bulk of the free disk space for a role.

You must also choose a virtual machine size with enough local disk space to support your application. This page lists the VM sizes and the amount of local storage in each one - http://msdn.microsoft.com/library/ee814754.aspx

Using Shared Folders

All Azure VMs accessing network drives must have the same network configuration applied, i.e. endpoints defined and firewall rules updated. They must also have the account created with the exact same credentials as the file server(s).

Before a shared folder can be used it must be discovered. Unfortunately it is not possible to use network discovery in Azure. To make matters worse both IP addresses and hostnames are dynamically assigned by Azure at each deployment. Some strategy is needed to make this possible.

Creating two separate roles makes the discovery simple. A “File Server Role” containing a single instance can be discovered through the Azure runtime API.

            var fileServer = RoleEnvironment.Roles["FileServerRole"].Instances[0];

            var ipaddress = fileServer.InstanceEndpoints["SMB"].IPEndpoint.Address;

The discovery logic can be added to the Application Role’s OnStart() and made available to the application logic via environment variable or injected in the application configuration before it is launched. Alternatively the file server(s) could write their IP address(es) to an Azure Table or Blob at start up. Each client would look up servers in the well-known storage location at startup. I will use the two-role configuration as an example for the rest of this post, all concepts should apply regardless of deployment topology.

Azure roles are started as services. The best practice for services is not to mount shared drives but Instead use UNC paths. Assuming the drive letter your application uses is configurable you should change it for the UNC path constructed using the IP address discovered through the Azure runtime API. So instead of X:\ your application should be configured with \\10.x.x.x\.

The last piece of the puzzle is the credentials your application uses to access the network drive. By default it will be using SYSTEM but it needs to authenticate with the file share using the account created at startup time otherwise it will be denied access. The programmatic way to switch identities is impersonation, you can read more about it here http://msdn.microsoft.com/en-us/library/aa376391(VS.85).aspx. Using impersonation from C# is easy but it takes multiple steps. Instead of showing the entire code here you can download the sample solution below to see how it works.

Sample Project

This solution puts it all together, it demonstrates the file sharing and access to the network drive. It is available here: http://cid-76556b7fc951f312.office.live.com/self.aspx/Public/SharedFolder.zip

The File Share Role is a Web Role so you can have some visual feedback for how it works. Navigating to the default page for the project will present you with a list of all clients' names and IP addresses. What's interesting is how this list is created - each instance in the Application Role writes a single file to the shared drive in the format hostname-IP address. The page simply lists of all files in the shared folder.

The point of this solution is to demonstrate sharing and accessing network drives. If you create additional tests post your results in the comments. I am sure I/O results will be popular.

I used ExtraSmall VMs in the solution. If you didn't sign up for the beta you will have to change the VM size to at least Small.

Final Thoughts

It does takes some effort to make Shared Folders work in Azure. Most if not all of it is boilerplate code that can be added to any Role as startup logic.

The main drawback of this approach is the single point of failure in the File Server Role. Worse yet, if something happens to that single instance or Azure needs to move it to another physical host all data will be lost. One way to solve this problem is to use Azure Drive and share a folder from it. This way all data will be persisted in Azure Storage and in case of a server failure or relocation no data will be lost.

In Azure you simply upload your application and the plumbing is all put in place for you. No need to manage Operating System installs or patches. Understanding how to package a Java application for deployment in Azure and the options you have in that process is what I will discuss here.

I am assuming you have a basic understanding of Azure so I won’t introduce any concepts here. If that is not the case you might want to visit http://www.microsoft.com/windowsazure/ to get an overview of Azure prior to reading this page.

How to run a Java Application in Azure

Azure requires a ‘Role’ to run your application. The Worker Role is the best type of Role to host a Java application. Instances of a Worker Role can be seen as fresh installs of Windows Server ready to run an application.

The Worker Role configuration is included in the deployment package you upload to Azure along with your application. The Role provides hooks to launch a Java application and ways to communicate with the Azure runtime.

Creating a Role involves adding it to the service definition file, setting attributes in the service configuration file and providing a class to handle the Role lifecycle. Let’s look into the main options in each of these files as it relates to deploying Java applications. I am using the Azure SDK 1.3 and will be talking about features introduced in that release.

Service Definition

The service definition file lists all Roles in your Azure service. I will cover Port Reservation and Startup Tasks.

Port Reservation

Of critical importance to Java applications running in the cloud is the specification of the required TCP ports the application uses. Azure will block communications to any port you don’t explicitly list in your service definition. You will need to add a InputEndpoint entry for every public port your application uses to receive requests. These ports will be configured both as a Windows Firewall rule and programmed in the Load Balancer. Remember you can have any number of instances of the same Role and they will all be configured behind a load balancer.

This is an example of how you would configure a Role that hosts a Java application which uses port 80 to accept HTTP requests:

<InputEndpoint name="Http" protocol="tcp" port="80" localPort="8080" />

Notice the protocol is set to "tcp" even though the application is actually using HTTP. "http" is a valid value for the protocol attribute but you must never use it for Java applications. The "http" value has a specific meaning in Azure and is reserved for .NET applications.

The port attribute specifies the public port that will be available for client requests. The localPort tells Azure the port your application is actually listening on. Azure will map the public port on the load balancer to the local port your application is using. Those values don’t need to be different, in fact most applications will likely use the same local and external port.

It is also important to know that localPort is an optional attribute. If you don’t define it Azure will dynamically open a port for your application. Since all requests will be mapped to that port your application must inquire the Azure runtime for the assigned port number to receive requests. Although optional you should probably always set the localPort.

The local port reservation has some limitations when it comes to the Compute Emulator (or Development Fabric). Because the Compute Emulator is running on your desktop it may not be able to bind to the port you requested because another application might have reserved the port. That is always the case for port 80 because IIS is already using it. If you intend on using the Compute Emulator you will need to get the dynamically assigned port at runtime, at least in development.

Startup Tasks

Startup Tasks are commands launched before your Role is initialized. They were created to allow a Role to perform any configuration before requests are forwarded to the Role instance.

A unique feature of Startup Tasks is the ability to run with elevated (administrator) privileges. This is usually required if your application needs to launch an installer. All installers must also run in silent or unattended mode. In fact the Oracle JVM installer does require administrator privileges to run and does support silent mode. If you plan on installing it you will have to use a Startup Task.

Another characteristic of Startup Tasks is the ability to write to any folder. Regular Azure applications must define working directories and can only write to them. That limitation does not apply to Startup Tasks. That facilitates the job of some installers and can also be beneficial to some Java application servers.

By now you must be thinking that you can just launch your Java application as a Startup Task and be done. In fact that is one option for launching Java applications but as usual is has some drawbacks. I will talk about this option shortly.

Service Configuration

Configurations are companions to Service Definitions. For every Role you define you must have a configuration entry.

Here is where you specify how many instances of your Role you would like to have. You will also define various settings for your Role.

One such setting of interest is the version of Windows Server. You can choose between Windows Server 2008 and Windows Server 2008 R2. For the most part the underlying operating system is irrelevant to a Java application. That continues to be true in Azure. If your application doesn’t rely directly on a specific Windows feature nor it depends on a 3^rd party tool that does you can ignore this setting.

There are important differences between these Windows Server families though. The one I am interested in is Power Shell. Windows Server 2008 R2 includes Power Shell 2.0 which – as I’ll soon demonstrate – can be used to greatly simply the deployment of Java applications.

Azure Role Entry Point

The Role Entry Point is the interface between your application and the Azure runtime. Azure will instantiate and call your Role Entry Point providing you with the opportunity to take actions at different stages of the Role lifecycle.

This is where you will be doing some .NET programming. At this point Azure requires the Role Entry Point to be written in either C# or VB.NET. The amount of code in your Role Entry Point will vary based on the complexity of your application. It can be as simple as a few lines of code.

Three methods define the role lifecycle: OnStart, OnStop and Run. OnStart is called before your application receives live traffic. You should do any initialization in this step. To a certain extent this is akin to a synchronous Startup Task. OnStop is called when Azure is shutting down your role to allow for a graceful shutdown. Run is called when Azure is ready to forward live traffic to your application. The call to Run must not return while your Role is operational. If it returns Azure will interpret it as a failure of your application and will recycle your Role instance. This behavior can be of interest to certain applications and should be used to request Azure to recycle your Role instance in case of a failure. You can envision a heartbeat check on the JVM being executed from Run and returning in case of either application or JVM failure, causing Azure to restart your Role and bring your application back to a running state.

Java Virtual Machine, Libraries and Resources

Now that you understand how to configure a Role to run your Java application you need to provide it with a JVM. The best way to do it is to upload the JVM to Azure Blob Storage and install it during Role initialization, either as a Startup Task or in the Role Entry Point’s OnStart.

Most Java runtimes can be simply copied to a new machine, no install is necessary. If your JVM can be installed this way you should create a ZIP archive and upload it to Azure Blob Storage. Because you may need to maintain multiple versions of the JVM I recommend creating a separate container to hold all the JVMs you need. Inside that container you can keep JDKs and/or JREs named after the corresponding Java version.

If you need to run an installer which requires administrator privileges you have to use a Startup Task. If you can copy the JVM you have a choice.

Depending on your build process you might want to use the same strategy for other dependencies. Libraries like Spring, Log4J, Apache Commons can also be in the cloud and pulled from Azure Blob Storage before your application starts. Imagine doing the same for the application server or web server your application uses. I personally like to create a separate container called ‘apps’ for Jetty, Tomcat and other servers.

Launching the Java application

With everything in place the only step left is to launch the Java application. It can also be done from either the Role Entry Point or from a Startup Task.

Believe it or not there is enough to discuss in each of these alternatives that will save them for future posts.

As a cliffhanger I will tell you the high level differences between the two options. Using the Role Entry Point to launch your Java application will give you full control over the lifecycle of the role and allows for your application to react to environment changes (e.g. discover when instances are added or removed). It does require you to write.NET code. Using Startup Tasks requires potentially no .NET knowledge plus gives you the ability to run with elevated privileges at the cost of having little to no access to the role lifecycle.

The path you take will vary based on your application.

Packaging and Deploying the Java application

The Azure SDK includes tools to package an application along with the Service Definition and Configuration. The Windows Azure Packaging Tool (cspack.exe) is the main tool to use for this job. Visual Studio provides a convenient frontend for cspack and is also capable of initiating a deployment.

Cspack.exe is more desirable for integrating with exiting Java builds. It is only available on Windows so you will have to do the packaging of the Azure deployment on a Windows box. I will also save the explanation on using cpspack for a future post.

Putting it all together: Jetty 7 in Azure

I did not want to finish without showing how all of this can work. I will demonstrate how to get Jetty 7 working with the minimum amount of effort. Running a full web application on Jetty will require extra steps like deploying your own WAR/EAR but for demonstration purposes I will deploy Jetty as is and access the ROOT web app.

I picked Jetty because I wanted to show an application that uses NIO working in Azure. You should be able to deploy any other web server the same way. David Chou has previously posted a great article on running Jetty in Azure. He wrote it for the SDK 1.2 but a lot of the information there still applies.

You will need a Java 6 compatible JVM, the latest Jetty 7 distribution in zip format, the Azure SDK 1.3 (or later) and Visual Studio 2010. The free edition of Visual Studio 2010 will do. You will also need a .NET library to handle ZIP files. I used http://www.icsharpcode.net/OpenSource/SharpZipLib/ but other popular libraries exist and can be used with little change to the deployment scripts.

Start by installing Visual Studio and the Azure SDK. If you are using Oracle’s JVM you will need to install it locally then create a zip file of the JRE. If you installed the JDK in the default location you can navigate to C:\Program Files\Java\jdk1.6.0_<update #>, right click on the JRE directory and create a zip folder. The deployment script expects this file to be named jre1.6.0_22.zip.

Upload both the JRE.zip and Jetty to your Azure Storage account. Put the jre.zip in a container called ‘java’ and the jetty-distribution-7.x.x.<date>.zip in a container called ‘apps’. You can change these container and file names but you will need to update the Launch.ps1 script.

You can download this Visual Studio 2010 project (almost) ready to be deployed. You will need to enter your storage account credentials to get it to work.

If you decide to create the project from scratch you should add the SharpZipLib DLL to a ‘lib’ folder in your project.

Minimal role code

This example will launch Jetty from a Startup Task. The only requirement for the Role Entry Point is to not return from Run so this code blocks indefinitely.

using System.Threading;

using Microsoft.WindowsAzure.ServiceRuntime;

namespace JettyWorkerRole

{

    public class WorkerRole : RoleEntryPoint

    {

        public override void Run()

        {

            while (true)

                Thread.Sleep(10000);

        }

    }

}

Service definition

There is a single Startup Task to execute ‘Run.cmd’ with regular user (limited) privileges. The task type ‘background’ decouples the execution of the task from the Role lifecycle.

I also specify the public port 80 to accept request but internally Jetty will use port 8080.

<?xml version="1.0" encoding="utf-8"?>

<ServiceDefinition name="MinimalJavaWorkerRole" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition">

  <WorkerRole name="JettyWorkerRole">

    <Startup> 

      <Task commandLine="Run.cmd" executionContext="limited" taskType="background" />

    </Startup> 

    <Endpoints> 

      <InputEndpoint name="Http" protocol="tcp" port="80" localPort="8080" />

    </Endpoints>

  </WorkerRole>

</ServiceDefinition>

Service configuration

The default service configuration sets the number of instances for the role to 1. Feel free to increase it if you’d like, this example will work with any number of instances.

A little hidden in this configuration is the osFamily. This is where you specify the family of Windows Server you would like to use. It must be set to Windows Server 2008 R2 which is indicated by the family 2. This is needed because I use PowerShell 2.0 in this example.

<?xml version="1.0" encoding="utf-8"?>

<ServiceConfiguration serviceName="MinimalJavaWorkerRole" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="2" osVersion="*">

  <Role name="JettyWorkerRole">

    <Instances count="1" />

  </Role>

</ServiceConfiguration>

Run.cmd

This is a command used to launch the PowerShell script which contains the actual deployment logic. This file is not strictly needed but Visual Studio makes checks for the existence of the commandLine. So if you use Visual Studio you must have it.

I’m relaxing the security on the PowerShell script execution. In production you should sign the PowerShell script instead.

powershell -executionpolicy unrestricted -file .\Launch.ps1

A word of caution if you are new to Visual Studio – text files are saved in UTF-8 by default. It should be otherwise fine with this content if it wasn’t for the byte order mark. Because of that you must make sure to change the encoding for this file. You can do this in the “Save As..” option, here are the steps.

Launch.ps1

This is an overly simplified version of a deployment script. I will expand on it and explain the details of how it works on the post on using Startup Tasks. Basically this script downloads both JRE and Jetty from your storage account, unzips both and launches Jetty.

You must change the $connection_string to use your Storage Account credentials. You might also need to change $jre and $jetty to match the versions you used.

function unzip ($zip, $destination) {

       Add-Type -Path ((Get-Location).Path + '\lib\ICSharpCode.SharpZipLib.dll')

       $fs = New-Object ICSharpCode.SharpZipLib.Zip.FastZip

       $fs.ExtractZip($zip, $destination, '')

}

function download_from_storage ($container, $blob, $connection, $destination) {

    Add-Type -Path ((Get-Location).Path + '\Microsoft.WindowsAzure.StorageClient.dll')

    $storageAccount = [Microsoft.WindowsAzure.CloudStorageAccount]::Parse($connection)

    $blobClient = New-Object Microsoft.WindowsAzure.StorageClient.CloudBlobClient($storageAccount.BlobEndpoint, $storageAccount.Credentials)  

    $remoteBlob = $blobClient.GetBlobReference($container + '/' + $blob)

    $remoteBlob.DownloadToFile($destination + "\" + $blob)

}

$connection_string = 'DefaultEndpointsProtocol=http;AccountName=<YOUR_ACCOUNT>;AccountKey=<YOUR_KEY>'

# JRE

$jre = 'jre1.6.0_22.zip'

download_from_storage 'java' $jre $connection_string (Get-Location).Path

unzip ((Get-Location).Path + "\" + $jre) (Get-Location).Path

# Jetty

$jetty = 'jetty-distribution-7.2.2.v20101205.zip'

download_from_storage 'apps' $jetty $connection_string (Get-Location).Path

unzip ((Get-Location).Path + "\" + $jetty) (Get-Location).Path

# Launch Jetty

cd jetty-distribution-7.2.2.v20101205

..\jre\bin\java `-jar start.jar

You must also tell Visual Studio do include this script in your build. Right-click on Launch.ps1 and select Properties. Make sure the ‘Copy to Output Directory’ option is set to ‘Copy Always’. You will need to do the same thing for Run.cmd and the Zip library.

Now you are ready to deploy. You can deploy the app directly from Visual Studio, information on how to set it up on this page http://msdn.microsoft.com/en-us/library/ee460772.aspx. Once your Azure account is configured in Visual Studio right-click on the cloud project and select ‘Publish…’.

Once the deployment is complete you can navigate to your cloudapp.net domain to see Jetty running. You will be greeted by the welcome page.

Remember Jetty defaults to the SelectChannelConnector showing your NIO application can run fine in Azure.