Quickstart for Track 2 preview management libraries and update root readme for track 2 #11384

nickzhums · 2020-05-12T09:42:13Z

This is the quickstart for Track 2 Python Management library thats going to be in public preview, creating this PR as part of release preparation.
This document will be later translated to a document on docs.microsoft.com

kaerm · 2020-05-13T17:38:05Z

doc/sphinx/mgmt_preview_quickstart.rst

+1. Login into your azure account
+2. Select azure active directory in the left sidebar
+3. Click "App Registrations"
+4. Select the application which you have created


Or create a new one

Removed these steps and added a link to the official doc for more detailed content

kaerm · 2020-05-13T17:38:57Z

doc/sphinx/mgmt_preview_quickstart.rst

+Get Client Secret
+^^^^^^^^^^^^^^^^^
+
+1. Login into your azure account


I guess according to the branding guidelines all instances of Azure should be capitalized. As well as Azure Active Directory etc

kaerm · 2020-05-13T17:39:54Z

doc/sphinx/mgmt_preview_quickstart.rst

+7. Copy and store the key value. You won’t be able to retrieve it after
+   you leave this page.
+
+Get Tenant ID


I'd move it before secret as this is the same set of instructions as Client ID so people don't need to navigate between tabs back and forth

kaerm · 2020-05-13T17:41:01Z

doc/sphinx/mgmt_preview_quickstart.rst

+
+To set the following environment variables on your development system:
+
+::


the instructions are different depending on OS, right?

Yes, good point, instructions added for Windows

doc/sphinx/mgmt_preview_quickstart.rst

kaerm · 2020-05-13T17:42:13Z

doc/sphinx/mgmt_preview_quickstart.rst

+Now that the environment is setup, all you need to do is to create an
+authenticated client. Our default option is to use
+**DefaultAzureCredentials** and in this guide we have picked
+**Resource** as our target service. To authenticate to Azure and create


I'd add a sentence saying that " but you can set it up similarly for any other service that you are using"

doc/sphinx/mgmt_preview_quickstart.rst

kaerm · 2020-05-13T17:44:42Z

doc/sphinx/mgmt_preview_quickstart.rst

+::
+
+    delete_async_op = resource_client.resource_groups.begin_delete(group_name)
+    delete_async_op.wait()


Is this document going to appear as a README for mgmt plane? If yes might be worth adding links to:

more samples

troubleshooting

contributing section

yes, we are working on the samples part, when it's setup i'll add link to the samples here.
For troubleshooting and contributing sections, are there existing places we can point to?

For both of these sections check what we have in the main readme. Troubleshooting could encourage posting an issue, link to ref docs, stack overflow. Contributing is just a copy paste:

Contributing

For details on contributing to this repository, see the contributing guide.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

I think we could add appropriate links to reference for resource group, that would teach people how to find appropriate section in python reference.
However for now we could add links to latest versions and later remember to change it to bx version.

thanks Zim, I will add links once track 2 api references are updated

zikalino · 2020-05-14T05:56:14Z

doc/sphinx/mgmt_preview_quickstart.rst

+3. Click "App Registrations"
+4. Select the application which you have created
+5. Copy "Application (client) ID"
+


How about "Subscription -> Access Control -> Add Role Assignment"?

doc/sphinx/mgmt_preview_quickstart.rst

kaerm · 2020-05-14T19:12:45Z

README.md

@@ -33,6 +33,17 @@ You can find the [most up to date list of all of the new packages on our page](h

 Last stable versions of packages that have been provided for usage with Azure and are production-ready. These libraries provide you with similar functionalities to the Preview ones as they allow you to use and consume existing resources and interact with them, for example: upload a blob. They might not implement the [guidelines](https://azure.github.io/azure-sdk/python_introduction.html) or have the same feature set as the Novemeber releases. They do however offer wider coverage of services.

+### Management: New Releases


You'll also have to update the links in the Packages Available to point to these sections instead (L20-22)

hmm, strange, I thought I updated these, thanks for spotting :)

kaerm · 2020-05-14T19:13:10Z

README.md

+For a complete list of management libraries which enable you to provision and manage Azure resources, please check [here](https://azure.github.io/azure-sdk/releases/latest/all/python.html). They might not have the same feature set as the new releases but they do offer wider coverage of services.
+Management libraries can be identified by namespaces that start with `azure-mgmt-`, e.g. `azure-mgmt-compute`
+
+
 ### Management


This section should be deleted and content merged with the sections above

lmazuel · 2020-05-16T00:02:39Z

doc/sphinx/mgmt_preview_quickstart.rst

+    import azure.mgmt.resource
+    import azure.mgmt.network
+    import azure.mgmt.compute
+    from azure.identity import DefaultAzureCredential;


lmazuel · 2020-05-16T00:03:22Z

doc/sphinx/mgmt_preview_quickstart.rst

+    from azure.identity import DefaultAzureCredential;
+    ...
+    subscription_id = os.environ.get("AZURE_SUBSCRIPTION_ID")
+    credentials = DefaultAzureCredential()


shoudl use the singular form for clarity

lmazuel · 2020-05-16T00:04:00Z

doc/sphinx/mgmt_preview_quickstart.rst

+    resource_client = azure.mgmt.resource.ResourceManagementClient(credential=credentials, subscription_id=subscription_id)
+
+More information and different authentication approaches using Azure Identity can be found in
+`this document <https://docs.microsoft.com/en-us/python/api/overview/azure/identity-readme?view=azure-python>`__


Recommendation is to always remove the "en-us" part of the URL, so the url can be localized depending of customer country automatically

lmazuel · 2020-05-16T00:04:28Z

doc/sphinx/mgmt_preview_quickstart.rst

+::
+
+    delete_async_op = resource_client.resource_groups.begin_delete(group_name)
+    delete_async_op.wd 


wd? guess wait() ?

yes, should be copy paste error

lmazuel · 2020-05-16T00:04:43Z

doc/sphinx/mgmt_preview_quickstart.rst

+
+::
+
+    # 


Why an empty # ?

Remove extra section Add pointer to new sections

Add troubleshooting and contributing sections

Update troubleshooting sections

zikalino · 2020-06-03T03:38:12Z

README.md

+
+### Management: Previous Versions
+For a complete list of management libraries which enable you to provision and manage Azure resources, please check [here](https://azure.github.io/azure-sdk/releases/latest/all/python.html). They might not have the same feature set as the new releases but they do offer wider coverage of services.
+Management libraries can be identified by namespaces that start with `azure-mgmt-`, e.g. `azure-mgmt-compute`


Shall we also have something about "Preview Versions" (I mean our bx versions)? And perhaps in general "preview versions"

This is covered in "Management: New Releases" section on this page

zikalino · 2020-06-03T03:40:46Z

doc/sphinx/mgmt_preview_quickstart.rst

+- **Client ID** 
+- **Client Secret** 
+- **Tenant ID** 
+


I was also thinking that we could add alternative of using Azure CLI as well. Maybe simpler for some users. Just "az login" and the same examples should work considering we use default credentials?

zikalino · 2020-06-03T03:42:39Z

doc/sphinx/mgmt_preview_quickstart.rst

+
+Windows (Note: Administrator access is required)
+
+1. Open the Control Panel


this can be also done in command line:
set AZURE_CLIENT_ID=

however maybe via control panel is better as it will be persistent.

zikalino · 2020-06-03T03:44:19Z

doc/sphinx/mgmt_preview_quickstart.rst

+::
+
+    import azure.mgmt.resource
+    import azure.mgmt.network


for simplicity of example, we probably don't need network and compute here

zikalino · 2020-06-03T03:47:04Z

doc/sphinx/mgmt_preview_quickstart.rst

+
+::
+
+    location = "mylocation"


i would change "mylocation" to some real location for instance "westus2"
if somebody is novice, they might try to put for instance "Warsaw" ;-)

yep, good point

* [doc] add description about asynchronous client. * update description.

…into regenerate_certs * 'master' of https://github.com/Azure/azure-sdk-for-python: [text analytics] remove duplicate platform info in user agent (Azure#12123) [form recognizer] remove duplicate platform info in user agent (Azure#12124) fix broken links (Azure#12100) Document "<unchanged>" for DataSourceCredentials.connectionString if it is empty (Azure#12129) Let the transport handles bad urls (Azure#12106) Remove Unneeded Reference to repository resource (Azure#11929) enable logging for tests (Azure#12110) fix network in batch testcase (Azure#12114) update test recording for appservice (Azure#12116) Add test for connection monitor and fix test api version. (Azure#12113) Minor root readme and mgmt quickstart update for Track 2 mgmt sdk (Azure#12112) Quickstart for Track 2 preview management libraries and update root readme for track 2 (Azure#11384) Seg fault fix (Azure#11933)

…into regenerate_keys * 'master' of https://github.com/Azure/azure-sdk-for-python: [text analytics] remove duplicate platform info in user agent (Azure#12123) [form recognizer] remove duplicate platform info in user agent (Azure#12124) fix broken links (Azure#12100) Document "<unchanged>" for DataSourceCredentials.connectionString if it is empty (Azure#12129) Let the transport handles bad urls (Azure#12106) Remove Unneeded Reference to repository resource (Azure#11929) enable logging for tests (Azure#12110) fix network in batch testcase (Azure#12114) update test recording for appservice (Azure#12116) Add test for connection monitor and fix test api version. (Azure#12113) Minor root readme and mgmt quickstart update for Track 2 mgmt sdk (Azure#12112) Quickstart for Track 2 preview management libraries and update root readme for track 2 (Azure#11384) Seg fault fix (Azure#11933)

…into regenerate_secrets * 'master' of https://github.com/Azure/azure-sdk-for-python: (39 commits) [text analytics] remove duplicate platform info in user agent (Azure#12123) [form recognizer] remove duplicate platform info in user agent (Azure#12124) fix broken links (Azure#12100) Document "<unchanged>" for DataSourceCredentials.connectionString if it is empty (Azure#12129) Let the transport handles bad urls (Azure#12106) Remove Unneeded Reference to repository resource (Azure#11929) enable logging for tests (Azure#12110) fix network in batch testcase (Azure#12114) update test recording for appservice (Azure#12116) Add test for connection monitor and fix test api version. (Azure#12113) Minor root readme and mgmt quickstart update for Track 2 mgmt sdk (Azure#12112) Quickstart for Track 2 preview management libraries and update root readme for track 2 (Azure#11384) Seg fault fix (Azure#11933) [formrecognizer] update formrecognizer links to new aka.ms naming (Azure#12079) changes in samples tests (Azure#12090) readme & sample updates (Azure#12095) Update Key Vault minimum azure-core to 1.4.0 (Azure#12074) [formrecognizer] test parity with other languages (Azure#12059) syncing missing changelog items (Azure#12089) updating doc references (Azure#12086) ...

Quickstart for Track 2 preview management libraries

15da20b

nickzhums requested review from maggiepint, zikalino, lmazuel and kaerm May 12, 2020 09:42

kaerm reviewed May 13, 2020

View reviewed changes

zikalino reviewed May 14, 2020

View reviewed changes

doc/sphinx/mgmt_preview_quickstart.rst Show resolved Hide resolved

nickzhums added 3 commits May 14, 2020 16:59

Update quickstart document based on comments

51650b8

Update index.rst

fb204a8

Update index.rst and add Track 2 quickstart to menu

4012010

nickzhums added the Do Not Merge label May 14, 2020

nickzhums changed the title ~~Quickstart for Track 2 preview management libraries~~ Quickstart for Track 2 preview management libraries and update root readme for track 2 May 14, 2020

Update root readme to reflect track 2 mgmt libraries

7299074

nickzhums requested review from zikalino and kaerm May 14, 2020 09:23

kaerm reviewed May 14, 2020

View reviewed changes

lmazuel reviewed May 16, 2020

View reviewed changes

nickzhums added 5 commits May 16, 2020 14:02

Update root readme for track 2 mgmt plane libraries

11a0b25

Remove extra section Add pointer to new sections

Update mgmt preview quickstart based on review comments

e45d6c2

Update mgmt quickstart based on authentication

18363a2

Update quickstart docs based on review comments

1c3fcab

Add troubleshooting and contributing sections

Update quickstart based on review comments

f4c4efd

Update troubleshooting sections

nickzhums requested review from lmazuel and kaerm May 16, 2020 07:27

zikalino reviewed Jun 3, 2020

View reviewed changes

Update quickstart

e85994e

nickzhums requested a review from zikalino June 3, 2020 06:36

nickzhums and others added 2 commits June 5, 2020 16:23

Update quickstart with network sample

b73ea95

Add async description in quickstart (#11943)

8f960b0

* [doc] add description about asynchronous client. * update description.

nickzhums requested a review from changlong-liu June 18, 2020 02:49

changlong-liu approved these changes Jun 18, 2020

View reviewed changes

nickzhums merged commit d662b54 into master Jun 18, 2020

nickzhums deleted the nickzhums-quickstart-track2 branch June 18, 2020 05:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quickstart for Track 2 preview management libraries and update root readme for track 2 #11384

Quickstart for Track 2 preview management libraries and update root readme for track 2 #11384

nickzhums commented May 12, 2020

kaerm May 13, 2020

nickzhums May 14, 2020

kaerm May 13, 2020

kaerm May 13, 2020

kaerm May 13, 2020

nickzhums May 14, 2020

kaerm May 13, 2020

kaerm May 13, 2020

nickzhums May 14, 2020

kaerm May 14, 2020

zikalino Jun 3, 2020

nickzhums Jun 3, 2020

zikalino May 14, 2020

kaerm May 14, 2020

nickzhums May 16, 2020

kaerm May 14, 2020

nickzhums May 16, 2020

lmazuel May 16, 2020

lmazuel May 16, 2020

lmazuel May 16, 2020

nickzhums May 16, 2020

lmazuel May 16, 2020

nickzhums May 16, 2020

lmazuel May 16, 2020

nickzhums May 16, 2020

zikalino Jun 3, 2020 •

edited

nickzhums Jun 3, 2020

zikalino Jun 3, 2020

zikalino Jun 3, 2020 •

edited

zikalino Jun 3, 2020

nickzhums Jun 3, 2020

zikalino Jun 3, 2020

nickzhums Jun 3, 2020


		To set the following environment variables on your development system:

		::

		@@ -33,6 +33,17 @@ You can find the [most up to date list of all of the new packages on our page](h

		Last stable versions of packages that have been provided for usage with Azure and are production-ready. These libraries provide you with similar functionalities to the Preview ones as they allow you to use and consume existing resources and interact with them, for example: upload a blob. They might not implement the [guidelines](https://azure.github.io/azure-sdk/python_introduction.html) or have the same feature set as the Novemeber releases. They do however offer wider coverage of services.

		### Management: New Releases


		Windows (Note: Administrator access is required)

		1. Open the Control Panel

Quickstart for Track 2 preview management libraries and update root readme for track 2 #11384

Quickstart for Track 2 preview management libraries and update root readme for track 2 #11384

Conversation

nickzhums commented May 12, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Contributing

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zikalino Jun 3, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zikalino Jun 3, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zikalino Jun 3, 2020 •

edited

zikalino Jun 3, 2020 •

edited