Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

{Doc} Track 2 Migration Guidance, revision #16495

Merged
merged 6 commits into from
Apr 15, 2021
Merged

{Doc} Track 2 Migration Guidance, revision #16495

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5535789
{Doc} Track 2 Migration Guidance, revision
qwordy Jan 12, 2021
b8f399e
Update doc/track_2_migration_guidance.md
qwordy Apr 7, 2021
1d03185
Merge branch 'dev' of https://github.com/Azure/azure-cli into doc7
qwordy Apr 15, 2021
4522770
update
qwordy Apr 15, 2021
1db6adf
Merge branch 'doc7' of https://github.com/qwordy/azure-cli into doc7
qwordy Apr 15, 2021
f81e52c
update
qwordy Apr 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions doc/track_2_migration_guidance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,17 @@
# Track 2 Migration Guidance

Azure CLI is built upon Azure Python SDK. Recently Azure Python SDK announced next generation product. It is named Track 2 SDK. The old version of SDK is named Track 1. It claims that it has great advantages than Track 1 SDK. It is not compatible with Track 1 SDK. Azure CLI developers need to spend considerable time and do some work to migrate from Track 1 SDK to Track 2 SDK. Let's see an example of Track 2 SDK. [azure-mgmt-compute 17.0.0b1](https://pypi.org/project/azure-mgmt-compute/17.0.0b1/) introduces important breaking changes and important new features like unified authentication and asynchronous programming.
Azure CLI is built on Azure Python SDKs. Recently, Azure Python SDK team announced the next generation product, named Track 2 SDK. The old version of SDK is called Track 1 SDK. It claims that it has some advantages than Track 1 SDK. It is not compatible with Track 1 SDK. A considerable number of work days are required for Azure CLI developers to migrate their modules from Track 1 SDK to Track 2 SDK. Let's see an example of Track 2 SDK. [azure-mgmt-compute 17.0.0b1](https://pypi.org/project/azure-mgmt-compute/17.0.0b1/) introduces important breaking changes and important new features like unified authentication and asynchronous programming.

This document summarizes typical issues and solutions when adopting Track 2 SDK in Azure CLI.

Example PRs:
1. [Compute PR #15750](https://github.com/Azure/azure-cli/pull/15750)
2. [Network PR #16245](https://github.com/Azure/azure-cli/pull/16245)
3. [Network PR #16350](https://github.com/Azure/azure-cli/pull/16350)
4. [Storage PR #15845](https://github.com/Azure/azure-cli/pull/15845)
5. [KeyVault PR #14150](https://github.com/Azure/azure-cli/pull/14150)
6. [AppConfig PR #16376](https://github.com/Azure/azure-cli/pull/16376)
qwordy marked this conversation as resolved.
Show resolved Hide resolved
7. [AppService PR #17146](https://github.com/Azure/azure-cli/pull/17146)

Below is a list of typical issues.

Expand All @@ -26,11 +31,12 @@ Below is a list of typical issues.

Long running operations have changed their function names in Track 2 SDK. A `begin_` prefix is added. For example, `create_or_update` becomes `begin_create_or_update`. `delete` becomes `begin_delete`. It is a naming convention in Track 2 SDK to indicate that an operation is a long running operation. Test cases can reveal most instances, but if a command has no test, it may be missed. A reliable approach is going through all methods to see whether they are long running operations.


### Property name change

Some of property names change in Track 2 SDK.

Examples:
Here are some examples. `->` is not Python code. It represents the left one is updated to the right one.

```
hyperVgeneration -> hyperVGeneration
Expand All @@ -40,6 +46,7 @@ virtual_machine_extension_type -> type_properties_type
type1 -> type_properties_type
instance_ids -> vm_instance_i_ds
diskMbpsReadWrite -> diskMBpsReadWrite
ipv4 -> I_PV4
```

Some changes are unnecessary, even wrong in English. I opened [Azure/autorest.python#850](https://github.com/Azure/autorest.python/issues/850) to track this problem.
Expand All @@ -48,7 +55,7 @@ Some changes are unnecessary, even wrong in English. I opened [Azure/autorest.py

Some of class names change in Track 2 SDK.

Examples:
[Example](https://github.com/Azure/azure-cli/pull/15750/files#diff-fd5160263d5431e9cdbf0f83abad213589c44c4c2724ff66b1172218caeb8396R629):

```
VirtualMachineIdentityUserAssignedIdentitiesValue -> UserAssignedIdentitiesValue
Expand All @@ -61,7 +68,9 @@ Error type changes in Track2 SDK.
Examples:

```
CloudError -> azure.core.exceptions.ResourceNotFoundError
msrestazure.azure_exceptions.CloudError -> azure.core.exceptions.ResourceNotFoundError
msrest.exceptions.ClientException -> azure.core.exceptions.HttpResponseError
ErrorException -> HttpResponseError
```

### No enum type
Expand All @@ -70,13 +79,24 @@ Track 2 SDK removes enum type and adopts string type instead. It loses the valid

### Class hierarchy change

The class hierarchy may change in Track 2 SDK. Some properties are not flattened. They are wrapped in classes.
The class hierarchy may change in Track 2 SDK. Some properties are not flattened. They are wrapped in classes. In Track 1 SDK, if the number of parameters is less than 3, it will be flattened.

Examples:

In VMSS `begin_update_instances`, a new type `VirtualMachineScaleSetVMInstanceRequiredIDs` is added.
In [VMSS](https://github.com/Azure/azure-cli/pull/15750/files?file-filters%5B%5D=.py#diff-fd5160263d5431e9cdbf0f83abad213589c44c4c2724ff66b1172218caeb8396R2688) `begin_update_instances`, a new type `VirtualMachineScaleSetVMInstanceRequiredIDs` is added.

In [DiskAccess](https://github.com/Azure/azure-cli/pull/15750/files#diff-fd5160263d5431e9cdbf0f83abad213589c44c4c2724ff66b1172218caeb8396R3602) `begin_create_or_update`, location and tags are moved to a nested structure `DiskAccess`, `disk_access = DiskAccess(location=location, tags=tags)`

In [Storage](https://github.com/Azure/azure-cli/pull/15845/files#diff-4cfe9a680ae04774e116b45bc06a679db751bfad1de211c6d2b3bc471900d8bfR23),
```
client.check_name_availability(account_name) // account_name is string
```
turns into
```
account_name = StorageAccountCheckNameAvailabilityParameters(name=name) client.check_name_availability(account_name)
```

In DiskAccess `begin_create_or_update`, location and tags are moved to a nested structure `DiskAccess`, `disk_access = DiskAccess(location=location, tags=tags)`
In [AppConfig](https://github.com/Azure/azure-cli/pull/16376/files#diff-1796b5bb574aca9235e83b02a207cb8a42aafab920f3aae1c46af22bf0ce5aa4R191), `id` cannot be passed directly to `regenerate_key method`. It needs to be wrapped in the new model `RegenerateKeyParameters`.

### Obtaining subscription

Expand Down Expand Up @@ -104,6 +124,8 @@ The problem I met is property name change. It is hard to find the line of code t

It is only used in CI jobs. It patches some code to SDK. This file should be deprecated. It was written long time ago. But for now, just modify this file and add missing packages.

[Example](https://github.com/Azure/azure-cli/pull/15750/files#diff-e1256a3d1d91aea524b252fa7dc4a64b83d183b7f57fb5c326b270a1c4b224a7)

### Missing external tenant authentication support

External tenant authentication support is missing in Azure CLI Core and Azure Core package. In request header, we use x-ms-authorization-auxiliary to pass auxiliary authorization token. Compute module is the first customer to have this requirement in Track 2 SDK. In azure/core/pipeline/policies/_authentication.py, there is a class BearerTokenCredentialPolicy. It simplifies bearer token authorization header configuration. However, auxiliary bearer token authorization is not supported in Azure Core policies [1] yet. The current solution is getting tokens manually, setting headers in client constructor or in operation call time manually. They said they will support this policy in the future. Azure CLI Core also needs an upgrade to provide better interfaces for Track 2 SDK users.
Expand Down