Tricks for Deleting Windows Azure Virtual Machines via the REST API

While I call this post “tricks” for deleting a Windows Azure Virtual Machine it really is not a trick.  It does require a little deeper understanding of how Windows Azure creates and hosts Virtual Machines in order to use the REST API to delete them.

Let us start with some background.  When you use the Windows Azure Portal to create a new Virtual Machine, a hidden service is created for you that will host the virtual machine role.  This will allow more than one Role (i.e. Virtual Machine) to be connected to this service to allow for the automatic round-robin of calls made to the exposed ports.

Below is a list of the Services in one of my Azure Account.

Using the REST API to list all Services, I see that not all of the services returned are shown on the screen in the portal.  The service named Test0206D is not listed inside the portal.

  <HostedService>
    <Url>https://management.core.windows.net/<subscription-id>/services/hostedservices/Test0206D</Url>
    <ServiceName>Test0206D</ServiceName>
    <HostedServiceProperties>
      <Description>Implicitly created hosted service2013-02-07 01:20</Description>
      <Location>West US</Location>
      <Label>VGVzdDAyMqZE</Label>
      <Status>Created</Status>
      <DateCreated>2013-02-07T01:20:58Z</DateCreated>
      <DateLastModified>2013-02-07T01:21:32Z</DateLastModified>
      <ExtendedProperties />
    </HostedServiceProperties>
  </HostedService>

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

In this case the Description clearly tells us this was created for us and when.  When we delete a Virtual Machine, the service will start to show up inside the portal.  If you never want to deploy a new Virtual Machine to that service again, it can be deleted.  Otherwise, keeping the service allows the DNS Name to be reserved and allows a new Virtual Machine Role to be added to this service at a later point. 

In order to Add a new Role (i.e. Virtual Machine) to an existing service, use the From Gallery option to create the Virtual Machine. Then, on step 4, Virtual Machine mode, select the Connect To An Existing Virtual Machine option. You will get a drop down of available options.

This background leads to the reason it might be tricky to delete a Virtual Machine using the REST API.

To Delete a stand-alone Virtual Machine

In an earlier blog post I listed the way to delete a Virtual Machine was to do an HTTP DELETE to the following URL.

https://management.core.windows.net/<Subscription-ID>/services/hostedservices/<Service-Name>/deploymentslots/Production

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

While this work, it only works in the case of a strand-alone Virtual Machine.  If you do not know if the Virtual Machine is stand-along or attached, do an HTTP GET to the URL above.  If you only have one <Role> element than it is a stand-alone Virtual Machine.

To Delete a Virtual Machine that is attached to another Virtual Machine

In order to Delete a Virtual Machine that is part of another service, you need to Remove the PersistentVMRole.  This is done by an HTTP DELETE to the following URL.

https://management.core.windows.net/<subscription-id>/services/hostedservices/<service-name>/deployments/<deployment-name>/roles/<vm-name>

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

The service name and virtual machine name are straight forward but the deployment name is tricky.  The deployment name is usually the Service Name but it can also be the name of the first virtual machine you put into the service.  To find out for sure, do an HTTP GET to the following URL to get the details of the service deployment.

https://management.core.windows.net/<subscription-id>/services/hostedservices/<service-name>/deploymentslots/Production

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

This will return an XML response that looks like the following.

<Deployment xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Name>Test0202A</Name>
  <DeploymentSlot>Production</DeploymentSlot>
  ...removed...
</Deployment>

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

The Name element is the name of the Deployment. 

In summary, a single call can be made to delete a stand-alone Virtual Machine.  For scenarios that join several Virtual Machines together inside a single service it takes a deeper understanding of that service’s properties in order to remove a Virtual Machine from that service.

Looking for a simple tool to work with the Windows Azure REST APIs?  I have a free tool here that greatly simplifies making REST calls.

How to Create a Windows Azure Virtual Machine Image without using the Windows Azure Management Portal

Currently the Windows Azure Management Portal is having some difficulty using the UI to create an Image from an existing Virtual Machine.

You have two different options to create an Image without using the UI.  The two options are using the REST API or PowerShell.  The details of each approach our outlined below.  I have tested both approaches and was able to create an Image and use that Image to create a new Virtual Machine.

Options 1:  Using Windows Azure REST API

1.  Sysprep the Virtual Machine and ensure it is shut down according to the instructions here.

2.  Download my REST API Helper Tool or use your own.

3.  Update the VM-CaptureImage.xml file to have the label name as the name of the Virtual Machine (it can really be anything) and the Image Name as the name of your output image.

4.  Set your Management Certificate, Subscription ID, and working folder path inside the App.config file as outlined in the blog post.

5.  Make an HTTP POST to: https://management.core.windows.net/<Subscription-ID>/services/hostedservices/<VM-Name>/deployments/<VM-Name>/roleInstances/<VM-Name>/Operations  (assumes the Service Name and VM Name are the same).

6.  Select the updated VM-CreateImage.xml as the POST Body.

7.  This is an Async call and the tool will return an Operations Request ID and auto populate the ability to check the status of that request.

8.  In about 3 to 5 minutes click on “Make REST Service Call” to check the status of the Async Request created above.  You will eventually see a HttpStatusCode 200 and Status Succeeded (rather than Status In Progress).

Options 2: Using Windows Azure PowerShell

1. Sysprep the Virtual Machine and ensure it is shut down according to the instructions here.

2. Setup and configure PowerShell as outlined here.  This takes about 10 minutes.

3. Run the following command: Save-AzureVMImage -ServiceName <Service-Name / Usually VM Name> -Name <Vm-Name> -NewImageName <New-Image-Name>  -NewImageLabel <SomeLabel>

4. In about 3 to 5 minutes the screen will update to show the process was successful.

Keep in mind that Windows Azure Virtual Machines are a Preview Feature so from time to time things like this will happen.  I am sure the Portal will be corrected soon to allow Images via the UI.  Never the less, it is always good to know how to do them programmatically.  Enjoy.

Windows Azure REST API Simple Sample and Tool

Windows Azure REST API Simple Sample and Tool

Download this sample using the download button below.

This tool is intended to get you moving in the right direction and not intended to solve all your problems out of the box. You will need to use the Windows Azure REST API Reference guide when working with this tool.

I have provided a few sample Request Body templates for Creating a Hosted Service, Creating an Azure Storage Account, Adding a Virtual Machine Disk, and Creating a Virtual Machine (note to create a VM is a multi-step process, see below). Others can easily be added by using the online reference guide.

To use this sample tool you need to configure some basic information inside the App.Config file. You need to set the path to your management certificate, your subscription id, and the path to the folder location of your POST bodies.

    <!--  Enter the full path to the Windows Azure Management Certificate. More details at http://msdn.microsoft.com/en-us/library/windowsazure/ee460782.aspx -->
    <add key='CertificatePath' value='C:\DemoFolder\yourcert.cer'/>

    <!-- Subscription ID for the account and must match Management Certificate -->
    <add key='Subscription' value='your account id' />

    <!--  Default folder location of REST API Post Bodies.  This exists to save time selecting the Post Body file. -->
    <add key='PostBodiesFolder' value='C:\DemoFolder\WindowsAzureRESTApiHelper\WindowsAzureRESTApiHelper\RESTAPIBodies\'/>


How to Use this Sample Tool

1. Once the App.config is setup simply launch the tool. It was built with Visual Studios 2010 but should upgrade to 2012 without issues.

2. Select one of the GET, POST, or DELETE radio buttons.

3. Select your basic action from the drop down or paste in your URL into the text box.

 

4. Click on “Make A REST Service Call” to complete your request.

 

5. If you are doing a POST, you will be prompted to select the body of your request.

 

6. If you do a POST or a DELTE that is an asynchronous process a Request ID is returned in the Response Header. The tool will detect this and auto populate a URL to check the result of the request.

 

7. You can keep clicking the “Make REST Service Call” button to check the results of the submitted operation until it is competed.

 

It is that simple!!! Like I said before, this tool is intended to be a starting point for someone new to working with the Windows Azure REST API’s.


Other useful pieces of information

1. To create a new Virtual Machine you need to do the following: First, create the Service using Create Hosted Service. Second, you can use the Quick Create using that Service to create the Virtual Machine.

2. If you plan to work with Virtual Machines using the API, read this blog post about the URLs.

3. If you run into issues the best way to confirm the URL and Post Body is to perform the actions using PowerShell with Fiddler running. This will show the URL and exact Post Body.

Windows Azure REST API Sample and Tool – GET, POST, & DELETE with One Click

Windows Azure has a few different, somewhat disjointed, toolsets available to create new artifacts and maintain existing ones.  The best known is the Web Portal.  Very quickly when working with the web portal you discover the portal is not able to do all the tasks needed to support development and maintenance.  This brings into play Windows Azure PowerShell Commands, a .Net SDK, and REST API. 

If you are new to working with the Windows Azure REST API or if you are looking for sample code working with the Windows Azure REST API, this tool can help you.

This tool is intended to get you moving in the right direction and not intended to solve all your problems out of the box.  You will need to use the Windows Azure REST API Reference guide when working with this tool. 

I have provided a few sample Request Body templates for Creating a Hosted Service, Creating an Azure Storage Account, Adding a Virtual Machine Disk, and Creating a Virtual Machine (note to create a VM is a multi-step process, see below).  Others can easily be added by using the online reference guide.

Download: Windows Azure REST API Sample Tool

To use this sample tool you need to configure some basic information inside the App.Config file.  You need to set the path to your management certificate, your subscription id, and the path to the folder location of your POST bodies. 

    <!--  Enter the full path to the Windows Azure Management Certificate. More details at http://msdn.microsoft.com/en-us/library/windowsazure/ee460782.aspx -->
    <add key='CertificatePath' value='C:\DemoFolder\yourcert.cer'/>

    <!-- Subscription ID for the account and must match Management Certificate -->
    <add key='Subscription' value='your account id' />

    <!--  Default folder location of REST API Post Bodies.  This exists to save time selecting the Post Body file. -->
    <add key='PostBodiesFolder' value='C:\DemoFolder\WindowsAzureRESTApiHelper\WindowsAzureRESTApiHelper\RESTAPIBodies\'/>

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }



How to Use this Sample Tool

1.  Once the App.config is setup simply launch the tool.  It was built with Visual Studios 2010 but should upgrade to 2012 without issues.

2.  Select one of the GET, POST, or DELETE radio buttons. 

3.  Select your basic action from the drop down or paste in your URL into the text box.

4.  Click on “Make A REST Service Call” to complete your request. 

5.  If you are doing a POST, you will be prompted to select the body of your request.

6.  If you do a POST or a DELTE that is an asynchronous process a Request ID is returned in the Response Header.  The tool will detect this and auto populate a URL to check the result of the request.

7.  You can keep clicking the “Make REST Service Call” button to check the results of the submitted operation until it is competed. 

It is that simple!!!  Like I said before, this tool is intended to be a starting point for someone new to working with the Windows Azure REST API’s. 



Download:
Windows Azure REST API Sample Tool



Other useful pieces of information

1.  To create a new Virtual Machine you need to do the following: First, create the Service using Create Hosted Service.  Second, you can use the Quick Create using that Service to create the Virtual Machine.

2.  If you plan to work with Virtual Machines using the API, read this blog post about the URLs.

3.  If you run into issues the best way to confirm the URL and Post Body is to perform the actions using PowerShell with Fiddler running.  This will show the URL and exact Post Body. 

Working with the Add Disk Operation of the Windows Azure REST API

Recently I was looking at a forum question of someone trying to add a disk to the Azure Virtual Machines using the Windows Azure REST API.

You have two types of Disks.  You have a Data Disk that do not have an operating system and are used to store user files.  You also have OS Disks.  The OS Disks contain the operation system and is the main disk used when creating an Azure Virtual Machine.

These can be created using the REST API, PowerShell, or the Management Portal. 

The REST API documentation outlines the following body for the post to create a new disk.

<Disk xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <HasOperatingSystem>true|false</HasOperatingSystem> 
   <Label>disk-description</Label>
   <MediaLink>uri-of-the-containing-blob</MediaLink>
   <Name>disk-mame</Name>
<OS>Linux|Windows</OS>
</Disk>

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

While these are the right items to send to create the Disk, the order matters if you want to create an OS Disk.  I found that the OS Element needed to be first in order to create an OS Disk vs. a Data Disk.

The correct body for the post to create an OS Disk should be:

<Disk xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <OS>Linux|Windows</OS>
   <HasOperatingSystem>true|false</HasOperatingSystem> 
   <Label>disk-description</Label>
   <MediaLink>uri-of-the-containing-blob</MediaLink>
   <Name>disk-mame</Name> 
</Disk>

Hope this helps someone out.  More to come in the next few days on working with the Windows Azure REST API.