windows azure rest api - creating a virtual machine

Question

I am looking into using the Windows Azure REST API to create Virtual Machines in the Windows Azure environment. Looking into the Windows Azure REST API reference I see that the URL to which the POST request should be made is:

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

My confusion here is about the need for <cloudservice-name> and <deployment-name>. In fact if I directly login to my Windows Azure subscription portal and go through the menu to create the Virtual Machine, I DON'T have to specify a cloudservice-name or deployment-name. All I do is choose an image (centos, ubuntu, windows etc.) for the VM, choose a flavor (xsmall, small, large etc.) for the VM and click on "Create" and the VM gets created in a few minutes.

Given I could create a VM this way, I am at a loss to understand why I have to pass a <cloudservice-name> and a <deployment-name> parameters in the REST API curl call and what values to pass to those parameters. In fact I don't have a deployment in my subscription, nor I intend to have one. All I want is simply create a virtual machine that I could use.

Is it possible for me to skip these parameters and still be able to create a Virtual machine in my Azure subscription? i.e. just only by passing the <subscription-id>?

Could someone who has used the Windows Azure REST API before or someone with expertise with Windows Azure throw some light on this and help clarify?

Update Wed, 07/31/2013: Thanks again for the feedback to my question. I would like to update that I was able to get to the point where I was able to finally create a Virtual Machine using a REST API call. But the strange thing is that creating the Virtual Machine successfully worked only once. Subsequently when I tried to create a VM with a different name, it gave an error like "Staging deployment is blocked". So just for the sake of sanity I went ahead and deleted the existing VM and and did some account cleanup. I tried the POST operation to create the VM again and now what is happening is that the POST response is coming back fine with a 202 Accepted message, but in spite of it I DON'T see a VM being created in my Azure account. I don't know where and how to even start troubleshooting this issue, given I am neither getting an error, nor the VM is getting created.

I am posting below the entire XML request body I am posting for creating the VM:

<Deployment xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Name>Staging</Name>
  <DeploymentSlot>Staging</DeploymentSlot>
  <Label>stk_curl_label_1</Label>
  <RoleList>
    <Role>
      <RoleName>stk_curl_role_1</RoleName>
      <RoleType>PersistentVMRole</RoleType>
      <ConfigurationSets>
        <ConfigurationSet>
          <ConfigurationSetType>WindowsProvisioningConfiguration</ConfigurationSetType>
          <ComputerName>stkVm1</ComputerName>
          <AdminPassword>Password123</AdminPassword>
          <EnableAutomaticUpdates>false</EnableAutomaticUpdates>
        </ConfigurationSet>
      </ConfigurationSets>
      <OSVirtualHardDisk>
        <HostCaching>ReadWrite</HostCaching>
        <DiskLabel>Visual studio ultimate</DiskLabel>
        <DiskName>stk_disk_1</DiskName>
        <MediaLink>http://stk11.blob.core.windows.net/communityimages/visual_studio_ultimate.vhd</MediaLink>
        <SourceImageName>03f55de797f546a1b29d1b8d66be687a__Visual-Studio-2013-Preview-Ultimate-12.0.20617.1</SourceImageName>
      </OSVirtualHardDisk>
      <RoleSize>ExtraSmall</RoleSize>
    </Role>
  </RoleList>
</Deployment>

And I am pasting below the tail of the response I am getting for the curl call:

> User-Agent: curl/7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5
> Host: management.core.windows.net
> Accept: */*
> x-ms-version: 2012-03-01
> Content-Type: application/xml
> Content-Length: 1236
> Expect: 100-continue
>
* SSLv3, TLS handshake, Hello request (0):
SSLv3, TLS handshake, Client hello (1):
SSLv3, TLS handshake, Server hello (2):
SSLv3, TLS handshake, CERT (11):
SSLv3, TLS handshake, Request CERT (13):
SSLv3, TLS handshake, Server finished (14):
SSLv3, TLS handshake, CERT (11):
SSLv3, TLS handshake, Client key exchange (16):
SSLv3, TLS handshake, CERT verify (15):
SSLv3, TLS change cipher, Client hello (1):
SSLv3, TLS handshake, Finished (20):
SSLv3, TLS change cipher, Client hello (1):
SSLv3, TLS handshake, Finished (20):
HTTP/1.1 100 Continue
HTTP/1.1 202 Accepted
< Cache-Control: no-cache
< Content-Length: 0
< Server: 33.0.6198.68 (rd_rdfe_stable.130710-0833) Microsoft-HTTPAPI/2.0
< x-ms-servedbyregion: ussouth
< x-ms-request-id: b2f3dd01319049a5a6728bbdbcde6c4a
< Date: Wed, 31 Jul 2013 17:26:54 GMT
* Connection #0 to host management.core.windows.net left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):

As you could clearly see, it is a "202 Accepted" response. But as I mentioned earlier, in spite of this, when I check at my Azure account, I don't see a VM being created.

Would appreciate any expert insights/ideas on how to go about figuring out the root cause of why it isn't working as intended?

Answer 1

What you are seeing is a little magic behind the scenes of the portal. When you deploy a Virtual Machine it does indeed end up in a Cloud Service container. This was recently changed to be more obvious in the portal as well, previously they were hiding this from you. When people would delete the VM or add other VMs to the same group (previously called something like "attach to") the cloud service would show up in the portal. People got confused on what this was and it just caused more questions than it was worth.

In the portal now you are prompted for a cloud service. If you do the quick create when it asks for the DNS name (and shows the .cloudapp.net next to it) that's the Cloud Service name you are providing. When you do the create via the Gallery it is even more obvious on step 3 where is asks to create a new Cloud Service or select one that already exists.

To do what you want via the REST API you'll need to create the cloud service ahead of time or as a call prior to the create for the VM. Also, the link you provided is for adding a Cloud Service role, not creating a Virtual Machine. For that REST API Call you'll want to use this: http://msdn.microsoft.com/en-us/library/windowsazure/jj157194.aspx It still requires the cloud service, but not the deployment name.

Answer 2

There are 2 different APIs, one for creating the deployment and a VM under a cloud service, the other for adding roles to the deployment you created earlier.

These are the 2 APIs

For VM deployment

http://msdn.microsoft.com/en-us/library/azure/jj157194.aspx

For Roles in a deployment

http://msdn.microsoft.com/en-us/library/azure/jj157186.aspx

What you are using is the second one, you first need to create a VM deployment using the first API, then use the second one to add more roles in the same cloud service.