Blog

Azure PowerShell Setup

February 11th, 2013

Before We Start

You can sign up and see the limitations of an Azure Free Trial at http://www.windowsazure.com/en-us/.  Most of our experience has been using the Pay As You Go subscription.  For the purpose of following along with this article, the free trial should be fine. Internally, we setup a test Azure on the Pay As You Go Subscription that gets fairly low usage (see usage stats below) and is mainly used to explore Azure features.  Here is a screen shot of our monthly billing for mid January to February 2013. 

image

The total cost is $21 dollars.  You can checkout more of the pricing information at http://www.windowsazure.com/en-us/pricing/calculator/.  The $21.12 covered deploying and testing a multi tenanted web application, with 2 tenants and  few thousand rows of test users per tenant.  

PowerShell

Ideally, the tools that I use for development have an associated command line tool, preferably with a PoweShell API.  Initially, command line tools may have more overhead in terms of learning, however for repetitive actions knowing the command line can speed up long term usage and automation.   From my personal experience, I’ve found that the concepts of the underlying platform become more clear after using a command line tool versus the GUI interface.  The ability to relate what is happening in the UI to the action taken on the command line can also be a powerful learning tool.

From an automation standpoint, already knowing the command line makes integrating into an existing build process or script simple.  As an example, when we start a new web based app for a client, we reuse a starter kit template inside a VSIX file, setup a GIT repository and then setup automated production and development build in Team City.   Knowing the Azure command line to spin up a new service and role would allow us to automate more steps in the initial project setup.  Creating a standard approach and enforcing that approach through automation can be a big time saver and helps reduce the risk that manual setups may introduce. 

Like many Microsoft products, Azure has a fairly extensive set of documentation, including setting up and using PowerShell commands.  The official documentation on setting up PowerShell access can be found in the resources section at the bottom of the page.  

PowerShell Access to Azure

External tools, or Agents, access Azure through the Service Management API.  In order to connect to that API, we need to generate a X509 v3 certificate with a 2048 bit key.  This certificate will be stored locally in our ‘Personal’ store.  We then export a second.cer file without the private key from our newly created certificate and upload that to a subscription in Azure.  Finally, we use PowerShell to export the current publish settings file and import that to our local machines AppData\Roaming\WindowsAzurePowerShell folder through a PowerShell command. 

After being uploaded to Azure, the cer file is used to authenticate and agent (in this case the PowerShell console) against the ServiceManagement API.   If someone gained access to your local cer file’s private key, they would be able to impersonate you and access the Azure account subscription.

Management certificates are stored in a ‘Management Certificate Store’ and are associated to an specific Azure subscription.  Each certificate store within the subscription can hold up to 25 certificates.  In our example, we create a certificate on our machine with the name of protolithazure.cer (Protolith is just a set of code we use for our SaaS starter kit).  The protolithazure.cer needs to be imported to the current user Personal store and then exported without the private key.  After exporting, the cer file can be uploaded to Azure management certificates under the Pay As You Go subscription and the new publish settings file will be available for download.    The publish settings file contains an xml description of the service management endpoint, subscription id and certificate for the Azure cmdlet to use when making authenticated calls to Azure. 

Here is the basic workflow, lets go through each step.

image

Connecting to the Service Management API

  1. Generate a Certificate

    Open the Visual Studio 2012 developer command prompt (this should also work in 2010).   Navigate to a location where you want to temporarily create the certificate.  For example:  C:\Temp.  After we are done installing the certificate in the Personal folder, we can delete the one generated in C:\Temp.   Enter the following command with a different cert name.  This step generated a certificate in C:\Temp called ‘protolithazure.cer’

    image

  2. Import the certificate to the current user Personal store.

    Start – Run – certmgr.msc.  This will launch the MSC console to manage certificates.  Right click the ‘Personal’ folder – All Tasks – Import.  The import dialog will ask you to select a certificate (C:\Temp\protolithazure.cer in our case).  The next step will ask you where to import the certificate. Personal should already be selected.  Finish the wizard and the certificate should appear under the Personal certificate folder in MSC.  Go ahead and delete the certificate from the C:\Temp folder.

    image

  3. Export the cer file without private key

    Back in certmgr, right click the imported key – All Tasks – Export.  Choose DER encoded X.509 and the file name to export to .  We used the same name (protolithazure.cer) under C:\Temp after deleting the previous key.,  Notice that the ‘Export Keys’ property is set to ‘No’.

    image

  4. Upload exported .cer file to Azure Management Certificate Store

    Login to the Azure management portal.   The Settings area of the portal contains the management certificates.  Select Settings – Management Certificates – Upload Certificate.  (If you have an existing certificate, the upload button is located on the bottom menu). 

    image

  5. Install the Azure PowerShell Cmdet

    The Azure PowerShell installer is available through the Web Platform Installer.  Go to the Web Platform Installer (can be found under IIS) and search for Azure PowerShell and then install.  This will add the cmdlet to your local machine.   If you don’t ever use PowerShell, you will need to first setup the correct remote execution policy.  For PowerShell users, this has most likely already been set.  Launch PowerShell as an Administrator and type the following command. 

    This will set the correct policy needed to execute Azure PowerShell commands.  The second line will import the module for use on 64 bit systems.  If you are running 32 bit, use ‘Program Files’ folder rather than ‘Program Files x86’ to locate the PowerShell module.

  6. Export Publish Settings from Azure and import locally

    For Azure PowerShell commands to access a specific subscription in Azure, it needs to have access to the publish settings file.  This file describes the endpoints and correlates the certificate with a specific subscript.   Launch a PowerShell console and run the following command.  This will launch a browser window where you will login to your Azure account and download the .publishsettings file. 

    The next step is to import the .publishsettings file into PowerShell.  This will create an XML file with the subscription info under AppData\Roaming\Windows Azure PowerShell.   It is important to note that this creates two files, publishsettings.xml and DefaultSubscriptionData.xml. 

    As the name implies, the default subscription file tells Azure commands to use the settings you imported by default.  Check out the Azure PowerShell Subscriptions link from resources  for more information on changing default subscriptions.

    image 

To test access to the Management API through PowerShell, you need to import the module for usage.  Run the following commands.  Get-AzureSubscription should list the details for any subscriptions in your Azure account.

 

 

References

Azure Management Certificates http://msdn.microsoft.com/en-us/library/windowsazure/gg551722.aspx
Azure PowerShell Documentation http://msdn.microsoft.com/en-us/library/windowsazure/jj156055.aspx
Recovering Private Keys http://www.entrust.net/knowledge-base/technote.cfm?tn=7905
Azure PowerShell Installer http://www.entrust.net/knowledge-base/technote.cfm?tn=7905
Azure PowerShell Subscriptions http://msdn.microsoft.com/en-us/library/windowsazure/jj554332.aspx
Azure Sign Up http://www.windowsazure.com/en-us/