Custom Resource Providers in Windows Azure Pack – Deploying the Hello World Sample

Hello readers, Victor Arzate here. I'm a Program Manager in the Windows Server and System Center CAT team and in this post I will walk you through the different steps required to deploy the Hello World custom Resource Provider sample that is included in the Windows Azure Pack Developers Kit. The purpose of this blog is to explain one of the methods used to extend Windows Azure Pack (WAP) by way of example. In this post I'll show how to deploy the Windows Azure Pack example resource provider 'Hello World'. One could develop their own resource provider and in this blog post I'll show all the basic steps to get the 'Hello World' example by way of the process and steps I used. In future blog posts, we will blog about how to extend the Hello World sample, and even how you can create your own Resource Provider taking the Hello World sample as a starting point.

Warning dear readers! – This blog post includes the following terms: Visual Studio and Compile

 

Disclaimer – There's a known issue when you deploy the Hello World Custom Resource Provider that is included in the WAP Service Management API Samples for December 2013, where you won't be able to see the PowerShell code for the SMA Runbooks using the WAP Admin Portal. Please note that the SMA Runbooks are there, and you'll be able to start/stop them, but the code won't be visible. This issue is specific to the Hello World sample, and does not apply to other WAP custom extensions you may create. If you uninstall the Hello World Custom Resource Provider, you will be able to see the PowerShell code for the SMA Runbooks again. Hence I recommend to use this blog post to test/evaluate the Hello World sample and custom resource providers in a testing environment. If you're working quite heavily with SMA you may not want to import this custom resource provider until a fix is released.

 

You may ask, what are Resource Providers in Windows Azure Pack (WAP)? In a nutshell, the cloud services that Windows Azure Pack provides are represented by Resource Providers. For example, by now you may have already deployed Windows Azure Pack and you noticed that it includes the Web Site Clouds, VM Clouds, Service Bus, SQL Servers and MySQL Servers Resource Providers. Obviously you can choose which services to offer to your tenants (for example, VM Clouds only), but what if the services you'd like to offer to your tenant are not available in the Resource Providers included in WAP? For example, what if you'd like to offer your tenants the option that they can back up their own Virtual Machines?

As described in the Custom Resource Provider Overview documentation in MSDN, a Resource Provider can provide services on its own, or it can act as a proxy to an existing external system. This means that you could include the functionality required in the custom Resource Provider, or you could use the custom Resource Provider to proxy the user and administrators requests to an external system (for example, System Center Orchestrator).

The Hello World custom Resource Provider sample is a great starting point when you want to offer additional functionality in WAP that is not currently provided in the out-of-the-box Resource Providers (such as VM Clouds and SQL Servers) and you want to use the default portals provided by WAP. For example, the Hello World Custom Resource Provider simulates the capabilities to allow tenants to create new file shares in the file servers defined by the administrator (this capability is not provided in the out-of-the-box Resource Providers).

You can learn more about the Hello World sample here and also, you can learn more about custom resource providers here.

Note that you can find generic guidance in MSDN and in the read me files included within the Hello World sample on how deploy it. In this blog post I'll give you the detailed steps with examples J

Prerequisites

  • Visual Studio 2012 installed (in my case I had Update 4 applied as well). Note that Visual Studio 2012 does not need to be installed in the same machine where you have Windows Azure Pack (WAP) installed.
  • Windows Installer XML (WiX) toolset version 3.6.3303.0 or newer installed (in my environment I installed WiX Toolset v3.8)
  • A Windows Azure Pack environment up & running.

 

Step 1 – Build the Hello World MSI installer file.

  1. Download the Windows Azure Pack: Service Management API Samples - Dec 2013 by clicking in the download button below:

  2. Copy the Microsoft.WindowsAzurePack.Samples.zip file to the machine where you've installed Visual Studio 2012 and extract the following folders (for example, to c:\projects):

    1. .\ Microsoft.WindowsAzurePack.Samples\HelloWorld
    2. .\ Microsoft.WindowsAzurePack.Samples\ApiClients
  3. Once those folders are extracted, make sure to remove the read only property for folders, all subfolders and files. Make sure you remove the read-only property for both, Microsoft.WAP.Samples.HelloWorld and the ApiClients folders.

  4. Copy the following assemblies from your WAP deployment to the .\HelloWorld\References folder (these assemblies are required to build the solution):

    1. Microsoft.Azure.Portal.Configuration.dll
    2. Microsoft.WindowsAzure.Management.Common.HttpClient.dll

    You will find these assemblies in the server where WAP is installed (for example, you can find them in the following folder: C:\inetpub\MgmtSvc-AdminSite\bin).

    Note – Before executing the next step, confirm that Visual Studio 2012 and that the Windows Installer XML (WiX) toolset 3.6.3303.0 are installed in the same machine.

  5. Launch Visual Studio 2012, and open the Hello World Solution that is located on the folder you extracted (in my example, C:\Projects\HelloWorld\Microsoft.WindowsAzurePack.Samples.HelloWorld.sln). You may receive a warning indicating that one or more projects were not loaded correctly. Click on OK and in the output Window you will see a line similar to this:

    C:\Projects\HelloWorld\Setup\Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup.wixproj : error : The project file could not be loaded. Could not find file 'C:\Projects\HelloWorld\Setup\Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup.wixproj'. C:\Projects\HelloWorld\Setup\Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup.wixproj

    In Solution Explorer locate the Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup project and you will notice that it has a blue exclamation mark.

  6. In the Properties Window, click on the three dots at the end of the File Path for the Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup project. In the Locate Project File window select the Microsoft.WAP.Samples.HelloWorld.Setup.wixproj file (that is located under .\HelloWorld\Setup folder) and click Open.

  7. Right click the Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup project and click on Reload Project. If you receive a security warning asking you if you would like to open the project click on ok.

    Once the project is reloaded, it will should correctly in the Solution Explorer

  8. You may find that the Newtonsoft.Json assembly is not properly resolved for the Microsoft.WindowsAzurePack.Samples, Microsoft.WindowsAzurePack.Samples.HelloWorld.Api and the Microsoft.WindowsAzurePack.Samples.HelloWorld.ApiClient projects.

     

     

    NewtonSoft.json is a NuGet package which normally is installed and resolved using the following NuGet command: Install-Package NewtonSoft.json. We have to execute this command for each of the projects where the NewtonSoft.json reference is not properly resolved. For this, go to the Tools Menu – Library Package ManagerPackage Manager Console:

    This will open the Package Manager Console:

    In the Package Manager Console, in Default project select the project where the NewtonSoft.Json reference is not properly resolved (for example, Microsoft.WindowsAzurePack.Samples), and type the following command in the Package Manager Console: Install-Package NewtonSoft.json

    You will receive an output similar to this to indicate that the Newtonsoft.Json reference was installed and added successfully:

    Installing 'Newtonsoft.Json 5.0.8'.

    Successfully installed 'Newtonsoft.Json 5.0.8'.

    Adding 'Newtonsoft.Json 5.0.8' to Microsoft.WindowsAzurePack.Samples.

    Successfully added 'Newtonsoft.Json 5.0.8' to Microsoft.WindowsAzurePack.Samples.

    And also you will notice that the reference in the project is now properly resolved.

    Repeat this procedure for the Microsoft.WindowsAzurePack.Samples.HelloWorld.Api and the Microsoft.WindowsAzurePack.Samples.HelloWorld.ApiClient projects making sure that the Newtonsoft.Json reference is properly resolved:

  9. Locate the Web.Config file in the Solution Explorer and double click on it.

  10. In the details Window, locate the <appSettings>
    section and note the values for Username and Password. Here you have to specify the credentials to be used by the Resource Provider and we will use them when we have to register it in WAP later in this blog post (note that this is an account specific to the sample Resource Provider and does not need to exist somewhere else, for example in AD). Set the values to your standards. For example, I changed them to:

    <appSettings>

    <!-- Following credentials are used for basic auth for hello world resource provider. Its shown like this for this sample only.

    Its always recommended not to store credentials in plain text in web.config.

    Encrypt the credentials or config file -->

    <add
    key="Username"
    value="admin" />

    <add
    key="Password"
    value="Pass@word1" />

    </appSettings>

  11. Save the Project, and then in the Build Menu, click on Build Solution

  12. Depending on your Visual Studio layout, you should see a message similar to this in the Output Window indicating that the project was built successfully:

    ========== Build: 7 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  13. You will notice that the build process succeeded without errors, and also, you'll see the location of the MSI file that was generated as part of the build process (in my example, it was generated on: C:\Projects\HelloWorld\Setup\bin\x64\Debug\ Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup.msi)

 

Step 2 – Install and register the Hello World Custom Resource Provider

In this section we will install the Hello World custom Resource Provider in the WAP server, and then we will register it with the Service Management API using the PowerShell script provided in the kit.

  1. Copy the Microsoft.WindowsAzurePack.Samples.HelloWorld.Setup.msi to the server where WAP is installed in the case of the Express Install or the server where the Admin and Tenant sites are installed, and execute it.

    1. In the Welcome to the Windows Azure Pack: Hello World Sample Setup screen click on Next.

    2. In the End-User License Agreement read the EULA and click on I accept the terms in the License Agreement if you do so, and click on Next.

    3. In the Custom Setup screen, make sure that all options are selected and click on Next.

    4. On the Ready to install Windows Azure Pack: Hello World Sample click on Install (accept any UAC prompts that may be displayed).

    5. On the Completed the Windows Azure Pack: Hello World Sample Setup Wizard click on Finish.

  2. Now we have to register the Hello World Resource Provider with the Service Management API. For this, the sample kit has provided a PowerShell script. Copy the Register-ResourceProvider.ps1 script located in the

    .\ Microsoft.WAP.Samples.HelloWorld\Setup\PowerShell folder to your WAP server and open it with the PowerShell ISE.

  3. In the script, locate the section where the $username and $password variables are initialized and provide the same values that you specified in the Web.Config file in Visual Studio. In my case, I set the following values:

     

    $hostName
    =
    "$env:ComputerName"
    +
    ":30030"

    $userName
    =
    "admin"

    $password
    =
    "Pass@word1"

     

    Save the script and close the Windows PowerShell ISE.

    Note: Make sure that the credentials specified in the Web.config file (step 1.9 from this blog post) are the same as the ones specified in the Register-ResourceProvider.ps1 script.

  4. Open a PowerShell window with Administrative rights and execute the Register-ResourceProvider.ps1. Make sure that there are no errors in the output window. Note that you've to run this PowerShell script in the server where WAP is installed (for the Express install) or the server with the WAP PowerShell modules installed (MgmtSvcConfig).

 

Step 3 – Explore the Hello World Custom Resource Provider

That's it – the Hello World sample is now deployed in your WAP environment. Now let's take a few steps so that you explore this sample resource provider, and also, make it available to your tenants.

  1. Open the Windows Azure Pack Admin Portal and you will notice the Hello World custom Resource Provider.

    You will notice that the Register your Hello World REST endpoint option is grayed out, this indicates that the Resource Provider extension has been successfully registered. Navigate through the different options (File Servers, Products, Settings and Controls) to get an overview of this sample resource provider.

    Now we want to give our tenants access to this resource provider. Let's assume that you already have a plan and you just need to add this custom resource provider to that plan.

  2. In the WAP Admin Portal, select one of your plans, and in the actions menu click on Add Service.

  3. In the Select Services to Add screen, select Hello World and click on the check mark to add the service to the plan.

  4. In the Plan, under Plan Services you'll see the recently added service (Hello World):

  5. Now it's time to sign in to the Tenant Portal as a tenant and explore the recently added service.

  6. Sign in into the WAP Tenant Portal with the credentials of a user that has been subscribed to the plan we edited in the previous steps.

  7. You will notice that the Hello World Resource Provider is now available to the tenant.

 

Note that the Microsoft.WAP.Samples.HelloWorld.Setup.msi installer we generated when building the Hello World solution in Visual Studio, installs, updates, or removes the Hello World Custom Provider including the client-side and server-side management portal for administrators and the management portal for tenants. Hence you can use the installer when you've a new version of your solution, or when you want to uninstall a previously deployed extension:

    

Also note that you can use the Register-ResourceProvider.ps1 script in case you need to re-register the Resource Provider, as the script first checks if there is already an existing Resource Provider with the name provided using the Get-MgmtSvcResourceProviderConfiguration cmdlet. In case it exists, it will remove it using the Remove-MgmtSvcResourceProviderConfiguration cmdlet and then it will create and add the new Resource Provider using the New-MgmtSvcResourceProviderConfiguration and Add-MgmtSvcResourceProviderConfiguration cmdlets.

 

This is just the tip of the iceberg, but this will give you a quick start into another extensibility option available in the Windows Azure Pack.

Please let us know if you've any specific scenarios/functionality that is not covered by the out-of-the-box Resource Providers in WAP and that could be provided via a custom Resource Provider (either creating a new one or extending the Hello World sample).

Until next time!