Scaling Out/In with the Azure Management API

10. August 2012 16:17 / 0 / Comments (2)

The Windows Azure Service Management REST API docs are very well written and informative, but they do lack in examples. In this post I will write a guide on how to use the Rest API to programmatically Scale Out/In (increase/decrease the number of instances).

In order to increase the number of instances of a deployment you must call the Change Deployment Configuration operation and post an updated configuration file to Azure. Therefore, the first thing to do is get the current configuration by calling the Get Deployment operation. After we retrieve the deployment we need to change the configuration file so we can scale out or in. The service returns the configuration file encoded as a base 64 so we abstract the decoding, modification, and re encoding using the UpdateInstanceCount method. After the change we call the ChangeDeploymentConfiguration which uploads the new configuration file to Azure.

        1: public void Scale(string serviceName, string deploymentName, string roleName, int count)

       2: {

       3:     X509Certificate2 cert = GetCertificate(); //from somewhere

       4:     Guid subscriptionId = new Guid("use your subscription guid");

       5:  

       6:     Deployment dep = GetDeployment(subscriptionId, serviceName, deploymentName, cert);

       7:  

       8:     if (dep == null)

       9:     {

      10:         //deployment doesn't exist anymore!

      11:         //TODO: do something

      12:         return;

      13:     }

      14:     string encodedConf = UpdateInstanceCount(dep.Configuration, roleName, count);

      15:     if (encodedConf == null)

      16:     {

      17:         //role doesn't exist anymore!

      18:         //TODO: do something

      19:         return;

      20:     }

      21:  

      22:     ChangeDeploymentConfiguration(subscriptionId, serviceName, deploymentName, encodedConf, false, cert);

      23:  

      24:     return View();

      25: }

Below is the GetDeployment function, which retrieves the Deployment information, including the encoded configuration file.

       1: const string getDeploymentUrl = "https://management.core.windows.net/{0}/services/hostedservices/{1}/deployments/{2}";

       2: const string getDeploymentVersion = "2012-03-01";

       3:  

       4: public static Deployment GetDeployment(Guid subscriptionId, string serviceName, string deploymentName, X509Certificate2 cert)

       5: {

       6:     Uri uri = new Uri(String.Format(getDeploymentUrl, subscriptionId, serviceName, deploymentName));

       7:  

       8:     HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);

       9:     request.Method = "GET";

    request.Headers.Add("x-ms-version", getDeploymentVersion);

    request.ClientCertificates.Add(cert);

    request.ContentType = "application/xml";

 

    XDocument responseBody = null;

    HttpStatusCode statusCode;

    HttpWebResponse response;

    try

    {

        response = (HttpWebResponse)request.GetResponse();

    }

    catch (WebException ex)

    {

        // GetResponse throws a WebException for 400 and 500 status codes

        response = (HttpWebResponse)ex.Response;

    }

    statusCode = response.StatusCode;

    if (response.ContentLength > 0)

    {

        using (XmlReader reader = XmlReader.Create(response.GetResponseStream()))

        {

            responseBody = XDocument.Load(reader);

        }

    }

    response.Close();

    if (statusCode.Equals(HttpStatusCode.OK))

    {

        XNamespace wa = "http://schemas.microsoft.com/windowsazure";

        XElement dep = responseBody.Element(wa + "Deployment");

        Deployment deployment = new Deployment

        {

            Name = dep.Element(wa + "Name").Value,

            Slot = (DeploymentSlot)Enum.Parse(typeof(DeploymentSlot), dep.Element(wa + "DeploymentSlot").Value),

            PrivateID = dep.Element(wa + "PrivateID").Value,

            Status = (DeploymentStatus)Enum.Parse(typeof(DeploymentStatus), dep.Element(wa + "Status").Value),

            Label = dep.Element(wa + "Label").Value,

            Url = new Uri(dep.Element(wa + "Url").Value),

            Configuration = dep.Element(wa + "Configuration").Value,

            Roles = (from r in dep.Element(wa + "RoleInstanceList").Elements(wa + "RoleInstance")

                     select new RoleInstance

                     {

                         RoleName = r.Element(wa + "RoleName").Value,

                         InstanceName = r.Element(wa + "InstanceName").Value,

                         Size = (InstanceSize)Enum.Parse(typeof(InstanceSize), r.Element(wa + "InstanceSize").Value),

                         Status = (InstanceStatus)Enum.Parse(typeof(InstanceStatus), r.Element(wa + "InstanceStatus").Value)

 

                     }).ToList()

        };

 

        return deployment;

    }

    else

    {

        //TODO: return some error

    }

    return null;

}

From the code above you can see we first create the Uri that we will be calling using subscriptionId, serviceName, and deploymentName for a very specific deployment. All those values can be retrieved from previous calls to the Azure Management API and/or the Azure Management Portal. We then go ahead and create a web request using GET, attaching the certificate, and specifying the type as application/xml. If the response is OK then we populate the model object Deployment using LINQ to XML.

Below is the UpdateInstanceCount, which decodes, modifies, and encodes the configuration file.

       1: private static string UpdateInstanceCount(string base64Conf, string roleName, int count)

       2: {

       3:     string conf = GetStringFromBase64String(base64Conf);

       4:  

       5:     XDocument c = XDocument.Parse(conf);

       6:  

       7:     XNamespace wa = "http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration";

       8:     XElement serviceConf = c.Element(wa + "ServiceConfiguration");

       9:  

    var role = serviceConf.Elements(wa + "Role").Where(r => r.Attribute("name").Value == roleName).SingleOrDefault();

 

    if (role == null)

        return null;

 

    role.Element(wa + "Instances").SetAttributeValue("count", count);

 

    string encoded = GetBase64StringFromString(serviceConf.ToString());

 

    return encoded;

}

 

private static string GetStringFromBase64String(string base64Str)

{

    byte[] bs = System.Convert.FromBase64String(base64Str);

    string s = System.Text.Encoding.UTF8.GetString(bs);

    return s;

}

 

private static string GetBase64StringFromString(string str)

{

    byte[] toEncodeAsBytes = System.Text.UTF8Encoding.UTF8.GetBytes(str);

    string returnValue = System.Convert.ToBase64String(toEncodeAsBytes);

    return returnValue;

}

We first get a readable string of the base 64 encoded configuration and then create an XDocument so we can query it and change it. After changing the ServiceConfiguration\Role\Instances[count] attribute we base 64 encode the configuration again and return it to the calling method. Below is a sample configuration file:

       1: <ServiceConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" serviceName="" osFamily="1" osVersion="*" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">

       2:   <Role name="mTender">

       3:     <ConfigurationSettings>

       4:       <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />

       5:       <Setting name="StorageAccount" value="something" />

       6:     </ConfigurationSettings>

       7:     <Instances count="1" />

       8:     <Certificates />

       9:   </Role>

      10: </ServiceConfiguration>

The last step is calling the ChangeDeploymentConfiguration which looks like this:

       1: const string changeDeploymentConfigurationUrl = "https://management.core.windows.net/{0}/services/hostedservices/{1}/deployments/{2}/?comp=config";

       2: const string changeDeploymentConfigurationVersion = "2012-03-01";

       3:  

       4: public static void ChangeDeploymentConfiguration(Guid subscriptionId, string serviceName, string deploymentName, string base64Configuration, bool treatWarningsAsError, X509Certificate2 cert)

       5: {

       6:     Uri uri = new Uri(String.Format(changeDeploymentConfigurationUrl, subscriptionId, serviceName, deploymentName));

       7:  

       8:     HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);

       9:     request.Method = "POST";

    request.Headers.Add("x-ms-version", changeDeploymentConfigurationVersion);

    request.ClientCertificates.Add(cert);

    request.ContentType = "application/xml";

  

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

                                <ChangeConfiguration xmlns=""http://schemas.microsoft.com/windowsazure"">

                                   <Configuration>{0}</Configuration>

                                   <TreatWarningsAsError>{1}</TreatWarningsAsError>

                                   <Mode>Auto</Mode>

                                   <ExtendedProperties />

                                </ChangeConfiguration>";

  

    string xmlRequest = String.Format(xmlRequestFormat, base64Configuration, treatWarningsAsError.ToString().ToLower());

  

    byte[] bs = System.Text.Encoding.UTF8.GetBytes(xmlRequest);

    request.ContentLength = bs.Length;

  

    Stream dataStream = request.GetRequestStream();

    dataStream.Write(bs, 0, bs.Length);

    dataStream.Close();

  

    XDocument responseBody = null;

    HttpStatusCode statusCode;

    HttpWebResponse response;

    try

    {

        response = (HttpWebResponse)request.GetResponse();

    }

    catch (WebException ex)

    {

        // GetResponse throws a WebException for 400 and 500 status codes

        response = (HttpWebResponse)ex.Response;

    }

    statusCode = response.StatusCode;

    if (response.ContentLength > 0)

    {

        using (XmlReader reader = XmlReader.Create(response.GetResponseStream()))

        {

            responseBody = XDocument.Load(reader);

        }

    }

    response.Close();

    if (statusCode.Equals(HttpStatusCode.Accepted))

    {

        XNamespace wa = "http://schemas.microsoft.com/windowsazure";

        //XElement hs = responseBody.Element(wa + "HostedService");

  

  

        return;

    }

    else

    {

        //TODO: error! what do we return?

    }

    return;

}

This code is very similar to the GetDeployment function, but with some major differences. Instead of a GET we have to perform a POST and post what we want to change. The API documentation specifies we need to post an XML that looks like the one from line 14-20. The Configuration node should hold the encoded configuration file we changed earlier. Something very important to note is line 22 where we change the treatWarningAsError boolean into a lower case string. XML is case sensitive and the service is expecting false or true, not False or True. If you fail to lower case it then you will receive an error from the service. We then post the information and check for the Status Code Accepted. Something else to note is that if you upload a configuration file without any modifications you will get a WebException with a Status Code of 400 (Bad Request) with a response body that looks like this:

       1: <Error xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

       2:   <Code>BadRequest</Code>

       3:   <Message>No change in settings specified</Message>

       4: </Error>

Please note that this is only sample code and is missing a lot of checks like the one below. It’s only purpose is to demo what steps are needed to scale out or in programmatically in Azure. Feel free to use this code and modified as needed.

Happy programming (and scaling)!

d5654249-d40f-408b-9f94-f28a9803e711|0|.0|27604f05-86ad-47ef-9e05-950bb762570c

Tags : Azure . .NET

Jonas Stawski

Scaling Out/In with the Azure Management API

Comments (2) -

Add comment