From 55357892b8a89214b91532741d1727b6bd474256 Mon Sep 17 00:00:00 2001 From: Feiyue Yu Date: Tue, 12 Jan 2021 14:09:02 +0800 Subject: [PATCH 1/4] {Doc} Track 2 Migration Guidance, revision --- doc/track_2_migration_guidance.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/track_2_migration_guidance.md b/doc/track_2_migration_guidance.md index b481e09bdc3..238e735af4f 100644 --- a/doc/track_2_migration_guidance.md +++ b/doc/track_2_migration_guidance.md @@ -7,6 +7,10 @@ This document summarizes typical issues and solutions when adopting Track 2 SDK 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) Below is a list of typical issues. @@ -40,6 +44,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. @@ -61,7 +66,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 @@ -70,7 +77,7 @@ 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: @@ -78,6 +85,15 @@ In VMSS `begin_update_instances`, a new type `VirtualMachineScaleSetVMInstanceRe In DiskAccess `begin_create_or_update`, location and tags are moved to a nested structure `DiskAccess`, `disk_access = DiskAccess(location=location, tags=tags)` +In Storage, +``` +track1: client.check_name_availability(account_name) // account_name is string +track2: account_name = StorageAccountCheckNameAvailabilityParameters(name=name) client.check_name_availability(account_name) +``` + +In AppConfig, +`id` cannot be passed directly to `regenerate_key method`. It needs to be wrapped in the new model `RegenerateKeyParameters`. + ### Obtaining subscription There are various ways to obtain subscription ID. Obtaining it from `client.config` does not work in Track 2 SDK any longer. From b8f399e5c02e41337465e9fa402b07d1fc0ec671 Mon Sep 17 00:00:00 2001 From: Feiyue Yu Date: Wed, 7 Apr 2021 13:42:08 +0800 Subject: [PATCH 2/4] Update doc/track_2_migration_guidance.md --- doc/track_2_migration_guidance.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/track_2_migration_guidance.md b/doc/track_2_migration_guidance.md index 238e735af4f..56b43f9306f 100644 --- a/doc/track_2_migration_guidance.md +++ b/doc/track_2_migration_guidance.md @@ -11,6 +11,7 @@ Example PRs: 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) +7. [AppService PR #17146](https://github.com/Azure/azure-cli/pull/17146) Below is a list of typical issues. From 4522770ae83c6c915aaafc7c4894ef6be77b5274 Mon Sep 17 00:00:00 2001 From: Feiyue Yu Date: Thu, 15 Apr 2021 15:22:16 +0800 Subject: [PATCH 3/4] update --- doc/track_2_migration_guidance.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/track_2_migration_guidance.md b/doc/track_2_migration_guidance.md index e133aba68b3..00b86015fe5 100644 --- a/doc/track_2_migration_guidance.md +++ b/doc/track_2_migration_guidance.md @@ -1,6 +1,6 @@ # 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. @@ -11,6 +11,7 @@ Example PRs: 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) +7. [AppService PR #17146](https://github.com/Azure/azure-cli/pull/17146) Below is a list of typical issues. @@ -30,6 +31,7 @@ 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. @@ -120,6 +122,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. From f81e52c05f7dc9665bcfa0bcaab2409decbfce4f Mon Sep 17 00:00:00 2001 From: Feiyue Yu Date: Thu, 15 Apr 2021 16:42:44 +0800 Subject: [PATCH 4/4] update --- doc/track_2_migration_guidance.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/track_2_migration_guidance.md b/doc/track_2_migration_guidance.md index 00b86015fe5..4fb176a3f2b 100644 --- a/doc/track_2_migration_guidance.md +++ b/doc/track_2_migration_guidance.md @@ -36,7 +36,7 @@ Long running operations have changed their function names in Track 2 SDK. A `beg 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 @@ -55,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 @@ -83,18 +83,20 @@ The class hierarchy may change in Track 2 SDK. Some properties are not 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 `begin_create_or_update`, location and tags are moved to a nested structure `DiskAccess`, `disk_access = DiskAccess(location=location, tags=tags)` +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, +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 ``` -track1: client.check_name_availability(account_name) // account_name is string -track2: account_name = StorageAccountCheckNameAvailabilityParameters(name=name) client.check_name_availability(account_name) +account_name = StorageAccountCheckNameAvailabilityParameters(name=name) client.check_name_availability(account_name) ``` -In AppConfig, -`id` cannot be passed directly to `regenerate_key method`. It needs to be wrapped in the new model `RegenerateKeyParameters`. +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