Overview of Command Line Deployment and Management with the Windows Azure SDK for PHP
June 7, 2012 update: The Microsoft Windows Azure team has released a new Windows Azure SDK for PHP. This release is part of an effort to keep PHP client libraries up to date with new Windows Azure features and to make PHP a first-class citizen in Windows Azure. The latest client libraries are on GitHub: https://github.com/WindowsAzure/azure-sdk-for-php. While the SDK hosted on CodePlex will continue to work for the foreseeable future, it is strongly recommended that new PHP/Windows Azure application use the SDK hosted on GitHub.
The work done by Maarten Balliauw and other contributors in building the SDK hosted on CodePlex was critical in unifying the PHP developer experience for Windows Azure. The Windows Azure team is grateful to these contributors for their pioneering work and looks forward to their continued support (and yours!) in adding to the new SDK on GitHub.
Thanks,
The Windows Azure Team
I’ve been exploring the Windows Azure SDK for PHP command line tools that allow you to create, deploy, and manage new hosted services and web roles. In this post, I’ll walk you through a the basics of using the tools, but first I want to point out a couple of the benefits that come to mind when using these tools:
- The tools are platform-independent (with the exception of the package tool). The service, certificate, and deployment tools essentially wrap the REST-based Windows Azure management API. (If you look at the files in the SDK, you’ll notice that there are .bat and .sh files for these tools.) So, you can manage your Windows Azure services and deployments from the platform of your choice. (Note that because the management API is REST-based, you can use it via the language of your choice, not just PHP. In fact, tools based on languages other than PHP already exist - See this Ruby example on github.)
- The tools allow you to programmatically manage your Windows Azure services and deployments.This series of articles, Building Scalable Applications for Windows Azure, demonstrates how to programmatically scale an application using the PHP classes in the SDK. The same type of management is possible with the command line tools.
In the rest of this post, I’ll assume that you have set up the Windows Azure SDK for PHP and that you have a ready to deploy application (see Packaging Applications).
Overview of service, certificate, and deployment tools
The operations exposed by the service, certificate and deployment tools should give you a good idea of what you can do with them. The following tables list the operations that are available. For more information (such as short operation names and parameter information), type the tool name at the command line.
service
Operation |
Description |
| list | Lists the hosted services for a specified subscription ID. |
| getproperties | Gets properties (ServiceName, Label, AffinityGroup, Location) for specified hosted service. |
| getproperty | Get a single hosted service property (ServiceName, Label, AffinityGroup, Location) |
| create | Creates a hosted service. |
| update | Updates a hosted service. |
| delete | Deletes a hosted service. |
Note: The list operation returns two properties: ServiceName and Url. The value of the Url property is the management API endpoint, not the service URL. If you want the service URL, you can create it from the ServiceName property: https://ServiceName.cloudapp.net.
certificate
Operation |
Description |
| listcertificates | Lists properties (Thumbprint, CertificateUrl, ThumbprintAlgorithm) for each certificate associated with the specifed hosted service. |
| addcertificate | Adds a certificate to the specified hosted service. |
| getcertificate | Gets properties (Thumbprint, CertificateUrl, ThumbprintAlgorithm) for a specified certificate. |
| getcertificateproperty | Gets a single certificate property (Thumbprint, CertificateUrl, ThumbprintAlgorithm). |
| deletecertificate | Deletes a certificate. |
deployment
Operation |
Description |
| createfromstorage | Creates a deployment from a remote package file (.cspkg) and service configuration file (.cscfg). |
| createfromlocal | Creates a deployment from a local package file (.cspkg) and service configuration file (.cscfg). |
| getproperties | Gets properties (Name, DeploymentSlot, Label, Url, Status) for a specified deployment. |
| getproperty | Gets a single property (Name, DeploymentSlot, Label, Url, Status) for a specified deployment. |
| swap | Swaps deployment slots (production to staging and staging to production) |
| delete | Deletes a deployment. |
| updateconfiguration | Updates the configuration for a specified deployment. |
| updatestatus | Updates the status (Running or Suspended) of a deployment. |
| editinstancenumber | Updates the number of instances of a deployment. |
| rebootinstance | Reboots a role instance. |
| reimageinstance | Reimages a role instance. |
| upgradefromstorage | Upgrades a deployment from a remote package file (.cspkg) and service configuration file (.cscfg). |
| upgradefromlocal | Upgrades a deployment from a local package file (.cspkg) and service configuration file (.cscfg). |
| walkupgradedomains | Walks upgrade domains for a specified deployment. |
Note: The getproperties operation returns 5 properties: Name, DeploymentSlot, Label, Url, and Status. The value of the Name property is the deployment ID.
Using the service, certificate, and deployment tools
Creating and uploading a service management API certificate
Before you can use the command line management tools, you need to create certificates for both the server (a .cer file)and the client (a .pem file). Both files can be created using OpenSSL, which you can download for Windows and run in a console.
To create the .pem certificate, execute this:
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
To create the .cer certificate, execute this:
openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer
(For a complete description of OpenSSL parameters, see the documentation at https://www.openssl.org/docs/apps/openssl.html.)
Next, you’ll need to upload the .cer certificate to your Windows Azure account. To do this, go to the Windows Azure portal, select Hosted Services, Storage Accounts & CDN, choose Management Certificates, and click Add Certificate.
Now you are ready to use the service, certificate, and deployment tools.
Create a configuration file
The command line tools in the the Windows Azure SDK for PHP support using a configuration file for commonly used parameters. Here’s what I put into my config.ini file:
-sid="my_subscription_id" -cert="path\to\my\certificate.pem"
This makes it possible to use the –F option on any operation to include my SID and certificate.
List hosted services
The following command will list all hosted services:
service list -F="C:\config.ini"
This operation will return two properties ServiceName and Url. As mentioned above, the Url property is the management URL, not the service URL. You can create the service URL from the value of the ServiceName property: https://ServiceName.cloudapp.net.
Create a new hosted service
The following command will create a new hosted service:
service create -F="C:\config.ini" --Name="unique_dns_prefix" --Location="North Central US" --Label="your_service_label"
Note that the value of the Name parameter must be your unique DNS prefix. This is the value that will prefix cloudapp.net to create your service URL (e.g. https://your_dns_prefix.cloudapp.net). When this operation completes successfully, it will return your unique DNS prefix.
Add a certificate
The command below will add a certificate to a hosted service. Note that this isn’t a management certificate, but one that might be used to enable RDP, for example.
certificate addcertificate -F="C:\config.ini" --ServiceName="dns_prefix" --CertificateLocation="path\to\your\certificate.cer" --CertificatePassword=your_certificate_password
Note that the ServiceName parameter takes the DNS prefix of your service. When this operation completes successfully, it returns the DNS prefix of the targeted service.
Create a staging deployment from a local package
Next, to create a new deployment from a local package (.cspkg file) and service configuration file (.cscfg)…
deployment createfromlocal -F="C:\config.ini" --Name="dns_prefix" --DeploymentName="deployment_name" --Label="deployment_label" --Staging --PackageLocation="path\to\your.cspkg" --ServiceConfigLocation="path\to\ServiceConfiguration.cscfg" --StorageAccount="your_storage_account_name"
Again, the Name parameter is the DNS prefix of your hosted service. When this operation completes successfully, it returns the request ID of the request. (Look for future posts on using this request ID with the getasynchronousoperation tool in the SDK.)
Get deployment properties
Once a deployment has been created, you can get its properties:
deployment getproperties -F="C:\config.ini" --Name="dns_prefix" --BySlot=Staging
Note that you get get deployment properties BySlot (staging or production) or ByName (the name of the deployment).
Move staging deployment to production
To move a deployment from staging to production…
deployment swap -F="C:\config.ini" --Name="dns_endpoint"
When this operation completes successfully, it returns the request ID of the request.
Add an instance
And lastly, to change the number of instances for a deployment…
deployment editinstancenumber -F="C:\config.ini" --Name="dns_prefix" --BySlot=production --RoleName="role_name" --NewInstanceNumber=2
Wrap Up
Hopefully, those examples are enough to give you the idea. In future posts, I’ll take a look at how to create scripts using these commands to make deployment and management quick and easy. In the meantime, we would love to hear your thoughts on these command line tools. How usable are they for you? What’s missing? Etc.
Thanks.
-Brian