Skip to content

Latest commit

 

History

History
170 lines (121 loc) · 5.98 KB

python_mgmt_migration_guide.rst

File metadata and controls

170 lines (121 loc) · 5.98 KB
Raw

Migration Guide - Resource Management

Guide for migrating to the next generation of Azure Python SDK for Management Libraries

This document is intended for users that are familiar with an older version of the Python SDK for managment libraries and wish to migrate their application to the next version of Azure resource management libraries

For users new to the Python SDK for resource management libraries, please see the quickstart guide

Table of contents

Prerequisites

  • Active Azure subscription
  • Python 2.7 or 3.5+

Updated Python Packages

You can refer to the this site to see all the new Python packages.

For packages that are already generally available (GA), you can directly install the package using pip. Take Azure Compute service for example, simply do: pip install azure-mgmt-compute

The release history for azure-mgmt-compute can be found at https://pypi.org/project/azure-mgmt-compute/#history

You will notice that there was a beta release in release history, and the changelog for this version mentioned that "this version uses a next-generation code generator that introduces important breaking changes". This indicates the package is based on the new generator.

In addition, some next-generation Python SDK management client libraries might still in Public Preview. The preview version SDK will be contain a b in its version to number to indicate that it's a beta release (e.g.``10.0.0b1``).

For those beta releases, please install the package based on the beta version number, for example, to install the latest preview package for BetaServiceExample, please use: pip install azure-mgmt-beta-service-example==10.0.0b1

General Changes

The latest Azure Python SDK for management libraries is a result of our efforts to create a resource management client library that is user-friendly and idiomatic to the Python ecosystem.

While conforming to the new Azure SDK Design Guidelines for Python, we have tried our best to minimize the breaking changes. Most of the API signatures have stayed the same to offer user an easier migration experience.

The important breaking changes are listed in the following sections:

Authentication

In old version, ServicePrincipalCredentials in azure.common is used for authenticating to Azure and creating a service client

In new version, in order to provide an unified authentication based on Azure Identity for all Azure SDKs, the authentication mechanism has been re-designed and replaced by azure-identity library

To use the new azure-identity authentication mechanism, please use pip install azure-identity to install the package

To the show the code snippets for the change:

In old version

import azure.mgmt.compute
from azure.common.credentials import ServicePrincipalCredentials

credentials = ServicePrincipalCredentials(
    client_id=client_id,
    secret=client_secret,
    tenant=tenant_id
)
compute_client = azure.mgmt.compute.ComputeManagementClient(credentials=credentials, subscription_id=self.subscription_id)

Equivalent in new version

import azure.mgmt.compute
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret
)
compute_client = azure.mgmt.compute.ComputeManagementClient(credential=credential, subscription_id=self.subscription_id)

For detailed information on the benefits of using the new authentication classes as well as all available authentication options, please refer to this page

Client API Changes

Most of the API has stayed the same to provide an easier migration experience. There is a minor change regarding the async operations

Async Operations Change

To differentiate between asynchronous and synchronous API operations in the new version, an explicit begin_ prefix is added for all the async APIs operations (this includes operations where the user gets a 202 response code or needs to call .result() explicitly to get the response)

To show an example (creating virtual machine):

In old version

result = self.compute_client.virtual_machines.create_or_update(
    group_name,
    vm_name,
    parameters
)
result = result.result()

Equivalent in new version

result = self.compute_client.virtual_machines.begin_create_or_update(
    group_name,
    vm_name,
    parameters
)
vm = result.result()

Additional Samples

More samples can be found at :

Need help?

If you have encountered an issue during migration, please file an issue via Github Issues and make sure you add the "Preview" label to the issue