Free trial *Internet Service Required

How to use Service Management from Python

This guide will show you how to programmatically perform common service management tasks from Python. The ServiceManagementService class in the Windows Azure SDK for Python supports programmatic access to much of the service management-related functionality that is available in the management portal (such as creating, updating, and deleting cloud services, deployments, data management services, virtual machines and affinity groups). This functionality can be useful in building applications that need programmatic access to service management.

Table of Contents

What is Service Management

The Service Management API provides programmatic access to much of the service management functionality available through the management portal. The Windows Azure SDK for Python allows you to manage your cloud services, storage accounts, and affinity groups.

To use the Service Management API, you will need to create a Windows Azure account.

Concepts

The Windows Azure SDK for Python wraps the Windows Azure Service Management API, which is a REST API. All API operations are performed over SSL and mutually authenticated using X.509 v3 certificates. The management service may be accessed from within a service running in Windows Azure, or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response.

How to: Connect to service management

To connect to the Service Management endpoint, you need your Windows Azure subscription ID and the path to a valid management certificate. You can obtain your subscription ID through the management portal, and you can create management certificates in a number of ways. In this guide OpenSSL is used, which you can download for Windows and run in a console.

You actually need to create two certificates, one for the server (a .cer file) and one for the client (a .pem file). To create the .pem file, 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 more information about Windows Azure certificates, see Managing Certificates in Windows Azure. For a complete description of OpenSSL parameters, see the documentation at http://www.openssl.org/docs/apps/openssl.html.

After you have created these files, you will need to upload the .cer file to Windows Azure via the management portal, and you will need to make note of where you saved the .pem file.

After you have obtained your subscription ID, created a certificate, and uploaded the .cer file to Windows Azure, you can connect to the Windows Azure managent endpoint by passing the subscription id and the path to the .pem file to ServiceManagementService:

from azure import *
from azure.servicemanagement import *

subscription_id = '<your_subscription_id>'
certificate_path = '<path_to_.pem_certificate>'

sms = ServiceManagementService(subscription_id, certificate_path)

In the example above, sms is a ServiceManagementService object. The ServiceManagementService class is the primary class used to manage Windows Azure services.

How to: List available locations

To list the locations that are available for hosting services, use the list_locations method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

result = sms.list_locations()
for location in result:
    print(location.name)

When you create a cloud service, storage service, or affinity group, you will need to provide a valid location. The list_locations method will always return an up-to-date list of the currently available locations. As of this writing, the available locations are:

  • West Europe
  • Southeast Asia
  • East Asia
  • North Central US
  • North Europe
  • South Central US
  • West US
  • East US

How to: Create a cloud service

When you create an application and run it in Windows Azure, the code and configuration together are called a Windows Azure cloud service (known as a hosted service in earlier Windows Azure releases). The create_hosted_service method allows you to create a new hosted service by providing a hosted service name (which must be unique in Windows Azure), a label (automatically encoded to base64), a description and a location. You can specify an affinity group instead of a location for your service.

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myhostedservice'
label = 'myhostedservice'
desc = 'my hosted service'
location = 'West US'

# You can either set the location or an affinity_group
sms.create_hosted_service(name, label, desc, location)

You can list all the hosted services for your subscription with the list_hosted_services method:

result = sms.list_hosted_services()

for hosted_service in result:
    print('Service name: ' + hosted_service.service_name)
    print('Management URL: ' + hosted_service.url)
    print('Affinity group: ' + hosted_service.hosted_service_properties.affinity_group)
    print('Location: ' + hosted_service.hosted_service_properties.location)
    print('')

If you want to get information about a particular hosted service, you can do so by passing the hosted service name to the get_hosted_service_properties method:

hosted_service = sms.get_hosted_service_properties('myhostedservice')

print('Service name: ' + hosted_service.service_name)
print('Management URL: ' + hosted_service.url)
print('Affinity group: ' + hosted_service.hosted_service_properties.affinity_group)
print('Location: ' + hosted_service.hosted_service_properties.location)

After you have created a cloud service, you can deploy your code to the service with the create_deployment method.

How to: Delete a cloud service

You can delete a cloud service by passing the service name to the delete_hosted_service method:

sms.delete_hosted_service('myhostedservice')

Note that before you can delete a service, all deployments for the the service must first be deleted. (See How to: Delete a deployment for details.)

How to: Create a deployment

The create_deployment method uploads a new service package and creates a new deployment in the staging or production environment. The parameters for this method are as follows:

  • name: The name of the hosted service.
  • deployment_name: The name of the deployment.
  • slot: A string indicating the staging or production slot.
  • package_url: The URL for the deployment package (a .cspgk file). The package file must be stored in a Windows Azure Blob Storage account under the same subscription as the hosted service to which the package is being uploaded. You can create a deployment package with the Windows Azure PowerShell cmdlets, or with the cspack commandline tool.
  • configuration: The service configuration file (.cscfg file) encoded to base64.
  • label: The label for the hosted service name (automatically encoded to base64).

The following example creates a new deployment v1 for a hosted service called myhostedservice:

from azure import *
from azure.servicemanagement import *
import base64

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myhostedservice'
deployment_name = 'v1'
slot = 'production'
package_url = 'URL_for_.cspkg_file'
configuration = base64.b64encode(open('path_to_cscfg', 'rb'))
label = 'myhostedservice'

result = sms.create_deployment(name, slot, deployment_name, package_url, label, configuration)

operation_result = sms.get_operation_status(result.request_id)
print('Operation status: ' + operation_result.status)

Note in the example above that the status of the create_deployment operation can be retrieved by passing the result returned by create_deployment to the get_operation_status method.

You can access deployment properties with the get_deployment_by_slot or get_deployment_by_name methods. The following example retrieves a deployment by specifying the deployment slot. The example also iterates through all the instances for the deployment:

result = sms.get_deployment_by_slot('myhostedservice', 'production')

print('Name: ' + result.name)
print('Slot: ' + result.deployment_slot)
print('Private ID: ' + result.private_id)
print('Status: ' + result.status)
print('Instances:')
for instance in result.role_instance_list:
    print('Instance name: ' + instance.instance_name)
    print('Instance status: ' + instance.instance_status)
    print('Instance size: ' + instance.instance_size)

How to: Update a deployment

A deployment can be updated by using the change_deployment_configuration method or the update_deployment_status method.

The change_deployment_configuration method allows you to upload a new service configuration (.cscfg) file, which will change any of several service settings (including the number of instances in a deployment). For more information, see Windows Azure Service Configuration Schema (.cscfg). The following example demonstrates how to upload a new service configuration file:

from azure import *
from azure.servicemanagement import *
import base64

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myhostedservice'
deployment_name = 'myhostedservice'
configuration = base64.b64encode(open('path_to_cscfg', 'rb'))

result = sms.change_deployment_configuration(name, deployment_name, configuration)

operation_result = sms.get_operation_status(result.request_id)
print('Operation status: ' + operation_result.status)

Note in the example above that the status of the change_deployment_configuration operation can be retrieved by passing the result returned by change_deployment_configuration to the get_operation_status method.

The update_deployment_status method allows you to set a deployment status to RUNNING or SUSPENDED. The following example demonstrates how to set the status to RUNNING for a deployment named v1 of a hosted service called myhostedservice:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myhostedservice'
deployment_name = 'v1'

result = update_deployment_status(name, deployment_name, 'Running')

How to: Move deployments between staging and production

Windows Azure provides two deployment environments: staging and production. Typically a service is deployed to the staging environment to test it before deploying the service to the production environment. When it is time to promote the service in staging to the production environment, you can do so without redeploying the service. This can be done by swapping the deployments. (For more information on swapping deployments, see Deploying a Windows Azure Service.)

The following example shows how to use the swap_deployment method to swap two deployments (with deployment names v1 and v2). In the example, prior to calling swap_deployment, deployment v1 is in the production slot and deployment v2 is in the staging slot. After calling swap_deployment, v2 is in production and v1 is in staging.

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

result = sms.swap_deployment('myhostedservice', 'v1', 'v2')

How to: Delete a deployment

To delete a deployment, use the delete_deployment method. The following example shows how to delete a deployment named v1.

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

sms.delete_deployment('myhostedservice', 'v1')

How to: Create a storage service

A storage service gives you access to Windows Azure Blobs, Tables, and Queues. To create a storage service, you need a name for the service (between 3 and 24 lowercase characters and unique within Windows Azure), a description, a label (up to 100 characters, automatically encoded to base64), and either a location or an affinity group. The following example shows how to create a storage service by specifying a location. If you want to use an affinity group, you have to create an affinity group first (see How to: Create an affinity group) and set it with the affinity_group parameter.

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'mystorageaccount'
label = 'mystorageaccount'
location = 'West US'
desc = 'My storage account description.'

result = sms.create_storage_account(name, desc, label, location=location)

operation_result = sms.get_operation_status(result.request_id)
print('Operation status: ' + operation_result.status)

Note in the example above that the status of the create_storage_account operation can be retrieved by passing the result returned by create_storage_account to the get_operation_status method.

You can list your storage accounts and their properties with the list_storage_accounts method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

result = sms.list_storage_accounts()
for account in result:
    print('Service name: ' + account.service_name)
    print('Affinity group: ' + account.storage_service_properties.affinity_group)
    print('Location: ' + account.storage_service_properties.location)
    print('')

How to: Delete a storage service

You can delete a storage service by passing the storage service name to the delete_storage_account method. Deleting a storage service will delete all data stored in the service (blobs, tables and queues).

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

sms.delete_storage_account('mystorageaccount')

How to: Create an affinity group

An affinity group is a logical grouping of Azure services that tells Windows Azure to locate the services for optimized performance. For example, you might create an affinity group in the “West US” location, then create a cloud service in that affinity group. If you then create a storage service in the same affinity group, Windows Azure knows to put it in the “West US” location and optimize within the data center for the best performance with the cloud services in the same affinity group.

To create an affinity group, you need a name, label (automatically encoded to base64), and location. You can optionally provide a description:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myAffinityGroup'
label = 'myAffinityGroup'
location = 'West US'
desc = 'my affinity group'

sms.create_affinity_group(name, label, location, desc)

After you have created an affinity group, you can specify the group (instead of a location) when creating a storage service.

You can list affinity groups and inspect their properties by calling the list_affinity_groups method:

result = sms.list_affinity_groups()

for group in result:
    print('Name: ' + group.name)
    print('Description: ' + group.description)
    print('Location: ' + group.location)
    print('')

How to: Delete an affinity group

You can delete an affinity group by passing the group name to the delete_affinity_group method. Note that before you can delete an affinity group, the affinity group must be disassociated from any services (or services that use the affinity group must be deleted).

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

sms.delete_affinity_group('myAffinityGroup')

How to: List available operating systems

To list the operating systems that are available for hosting services, use the list_operating_systems method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

result = sms.list_operating_systems()

for os in result:
    print('OS: ' + os.label)
    print('Family: ' + os.family_label)
    print('Active: ' + str(os.is_active))

Alternatively, you can use the list_operating_system_families method, which groups the operating systems by family:

result = sms.list_operating_system_families()

for family in result:
    print('Family: ' + family.label)
    for os in family.operating_systems:
        if os.is_active:
            print('OS: ' + os.label)
            print('Version: ' + os.version)
    print('')

How to: Create an operating system image

To add an operating system image to the image repository, use the add_os_image method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'mycentos'
label = 'mycentos'
os = 'Linux' # Linux or Windows
media_link = 'url_to_storage_blob_for_source_image_vhd'

result = sms.add_os_image(label, media_link, name, os)

operation_result = sms.get_operation_status(result.request_id)
print('Operation status: ' + operation_result.status)

To list the operating system images that are available, use the list_os_images method. This includes all platform images and user images:

result = sms.list_os_images()

for image in result:
    print('Name: ' + image.name)
    print('Label: ' + image.label)
    print('OS: ' + image.os)
    print('Category: ' + image.category)
    print('Description: ' + image.description)
    print('Location: ' + image.location)
    print('Affinity group: ' + image.affinity_group)
    print('Media link: ' + image.media_link)
    print('')

How to: Delete an operating system image

To delete a user image, use the delete_os_image method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

result = sms.delete_os_image('mycentos')

operation_result = sms.get_operation_status(result.request_id)
print('Operation status: ' + operation_result.status)

How to: Create a virtual machine

To create a virtual machine, you first need to create a cloud service. Then create the virtual machine deployment using the create_virtual_machine_deployment method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

name = 'myvm'
location = 'West US'

# You can either set the location or an affinity_group
sms.create_hosted_service(service_name=name,
    label=name,
    location=location)

# Name of an os image as returned by list_os_images
image_name = 'OpenLogic__OpenLogic-CentOS-62-20120531-en-us-30GB.vhd'

# Destination storage account container/blob where the VM disk
# will be created
media_link = 'url_to_target_storage_blob_for_vm_hd'

# Linux VM configuration, you can use WindowsConfigurationSet
# for a Windows VM instead
linux_config = LinuxConfigurationSet('myhostname', 'myuser', 'mypassword', True)

os_hd = OSVirtualHardDisk(image_name, media_link)

sms.create_virtual_machine_deployment(service_name=name,
    deployment_name=name,
    deployment_slot='production',
    label=name,
    role_name=name,
    system_config=linux_config,
    os_virtual_hard_disk=os_hd,
    role_size='Small')

How to: Delete a virtual machine

To delete a virtual machine, you first delete the deployment using the delete_deployment method:

from azure import *
from azure.servicemanagement import *

sms = ServiceManagementService(subscription_id, certificate_path)

sms.delete_deployment(service_name='myvm',
    deployment_name='myvm')

The cloud service can then be deleted using the delete_hosted_service method:

sms.delete_hosted_service(service_name='myvm')

Next Steps

Now that you've learned the basics of service management, follow these links to do more complex tasks.

Rss Newsletter