[Identity] Update manual testing docs (#27182)

* This updates Azure Arc manual testing instructions and
also adds a document for testing on Azure Container Instances.
Dockerfiles and requirements.txt were both updated accordingly.
* Update VM and Cloud Shell instructions
* Pod identity doc updates
* Add missing await keyword in async test

Signed-off-by: Paul Van Eck <[email protected]>

sdk/identity/azure-identity/tests/managed-identity-live/Dockerfile

@@ -6,7 +6,7 @@
 # internal users should provide MCR registry to build via 'docker build . --build-arg REGISTRY="mcr.microsoft.com/mirror/docker/library/"'
 # public OSS users should simply leave this argument blank or ignore its presence entirely
 ARG REGISTRY=""
-ARG PYTHON_VERSION=3.9
+ARG PYTHON_VERSION=3.10
 
 # docker can't tell when the repo has changed and will therefore cache this layer
 FROM ${REGISTRY}alpine:3.14 as repo
@@ -15,10 +15,13 @@ RUN git clone https://github.com/Azure/azure-sdk-for-python --single-branch --de
 
 FROM ${REGISTRY}python:${PYTHON_VERSION}-slim
 
+COPY --from=repo /azure-sdk-for-python/tools /tools
 COPY --from=repo /azure-sdk-for-python/sdk/identity /sdk/identity
 COPY --from=repo /azure-sdk-for-python/sdk/core/azure-core /sdk/core/azure-core
 COPY --from=repo /azure-sdk-for-python/sdk/keyvault/azure-keyvault-secrets /sdk/keyvault/azure-keyvault-secrets
 
+ENV AZURE_TEST_RUN_LIVE=true
+ENV AZURE_SKIP_LIVE_RECORDING=true
 WORKDIR /sdk/identity/azure-identity/tests/managed-identity-live
 RUN pip install --no-cache-dir -r requirements.txt
 

sdk/identity/azure-identity/tests/managed-identity-live/azure_arc.md

@@ -1,11 +1,11 @@
-# Testing azure-identity in Azure Arc
+# Test Azure Identity in Azure Arc
 
 ## Prerequisite tools
 
 1. A non-Azure Windows or Linux VM.
 2. Administrator privileges on the VM.
 3. An Azure Key Vault.
-4. Python 3.6+
+4. Python 3.7+
 
 ### Install Azure Arc on the VM
 
@@ -25,37 +25,43 @@ sudo setfacl -m "g:himds:r-x" /var/opt/azcmagent/tokens/
 sudo setfacl -m "g::r-x" /var/opt/azcmagent/tokens/
 ```
 7. Arc setup should now be complete. Restart your VM to finalize your environment setup.
-8. After restarting, check your environment by searching for environment variables named `IDENTITY_ENDPOINT` and 
-`IMDS_ENDPOINT`. If they are not present, or don't resemble `http://localhost:40342/metadata/identity/oauth2/token` and 
+8. After restarting, check your environment by searching for environment variables named `IDENTITY_ENDPOINT` and
+`IMDS_ENDPOINT`. If they are not present, or don't resemble `http://localhost:40342/metadata/identity/oauth2/token` and
 `http://localhost:40342` respectively, you may need to wait a short while or try restarting the VM again.
 
 ## Give the Azure Arc VM access to the key vault
 
 For the tests to pass, the VM will need secret management permissions in your key vault.
 
 1. Go to your key vault resource in the [Azure Portal](https://portal.azure.com).
-2. Go to the vault's "Access policies" page, and click "Add Access Policy".
-3. Using the secret management template, select your Arc VM resource as the principal.
-4. Click "Add".
-5. Don't forget to click "Save" at the top of the access policies page after the policy is added.
+2. Go to the vault's "Access policies" page, and click "Create".
+3. Using the "Secret Management" template, select your Arc VM resource as the principal.
+4. Click "Create".
 
 ## Run the azure-identity Tests on the Azure Arc VM
 
 > **Note:** The following steps are specific to Python.
 
 In a terminal window, run:
-```
-git clone https://github.com/Azure/azure-sdk-for-python --single-branch --branch master --depth 1
+```sh
+git clone https://github.com/Azure/azure-sdk-for-python --single-branch --branch main --depth 1
 cd azure-sdk-for-python/sdk/identity/azure-identity/tests/managed-identity-live
 ```
-Set the environment variable `AZURE_IDENTITY_TEST_VAULT_URL` to the vault URI of your key vault.
 
 Install `requirements.txt`:
-```
+```sh
 pip install -r requirements.txt
 ```
-Run the managed identity tests, using the below command with Python 3.6+:
+
+Set the following environment variables, being sure to update the URL value:
 ```
-pytest -k managed_identity_live
+AZURE_IDENTITY_TEST_VAULT_URL=<URL of your key vault>
+AZURE_TEST_RUN_LIVE=true
+AZURE_SKIP_LIVE_RECORDING=true
 ```
+Run the managed identity tests, using the below command with Python 3.7+:
+```sh
+pytest -sv -k managed_identity_live
+```
+
 Expected output for each: `passed` for all tests run.

sdk/identity/azure-identity/tests/managed-identity-live/cloudshell.md

@@ -1,11 +1,11 @@
-# Testing azure-identity in Azure Cloud Shell
+# Test Azure Identity in Azure Cloud Shell
 
 # Open Azure Cloud Shell
 https://shell.azure.com/
 
 # Create an Azure Key Vault
 
-## set environment variables to simplify copy-pasting
+## Set environment variables to simplify copy-pasting
 - RESOURCE_GROUP
   - name of an Azure resource group
   - must be unique in the Azure subscription
@@ -15,12 +15,12 @@ https://shell.azure.com/
   - must begin with a letter
   - must be globally unique
 
-## create a resource group
+## Create a resource group
 ```sh
 az group create -n $RESOURCE_GROUP --location westus2
 ```
 
-## create the Key Vault
+## Create the key vault
 ```sh
 az keyvault create -g $RESOURCE_GROUP -n $KEY_VAULT_NAME --sku standard
 ```
@@ -35,48 +35,50 @@ export AZURE_IDENTITY_TEST_VAULT_URL=$(az keyvault show -g $RESOURCE_GROUP -n $K
 ## Acquire the latest code
 This may take several minutes:
 ```sh
-git clone https://github.com/azure/azure-sdk-for-python --single-branch --branch master --depth 1
+git clone https://github.com/azure/azure-sdk-for-python --single-branch --branch main --depth 1
 ```
 
 ## Change working directory
 ```sh
 cd azure-sdk-for-python/sdk/identity/azure-identity
 ```
 
-## Create virtual environments
-The Azure SDK supports Python 3.6+. Python 3 should be installed in your Cloud Shell.
-
-### Python 3
-If your shell has at least Python 3.6 available, create a virtual environment
-for it:
+## Create virtual environment
+The Azure SDK supports Python 3.7+. Python 3 should be installed in your Cloud Shell.
 ```sh
-virtualenv -p python3 ~/venv3
+python -m venv ~/venv
 ```
 
-## For each virtual environment:
-
-### Activate
+## Activate virtual environment
 For example:
 ```sh
-source ~/venv2/bin/activate
+source ~/venv/bin/activate
 ```
 
-### Install packages
+## Install packages
 ```sh
 pip install -r dev_requirements.txt .
 ```
 
-### Run tests
+## Set required environment variables
+```sh
+export AZURE_TEST_RUN_LIVE=true
+export AZURE_SKIP_LIVE_RECORDING=true
+```
+
+## Run tests
 ```sh
 pytest ./tests -vrs -m cloudshell
 ```
 
-### Deactivate
+# Clean up
+
+## Deactivate virtual environment
 ```sh
 deactivate
 ```
 
-# Delete Azure resources
+## Delete Azure resources
 After running tests, delete the resources provisioned earlier:
 ```sh
 az group delete -n $RESOURCE_GROUP -y --no-wait

sdk/identity/azure-identity/tests/managed-identity-live/container_instances.md

@@ -0,0 +1,160 @@
+# Test Azure Identity in Azure Container Instances
+
+# Prerequisite tools
+- Azure CLI
+  - https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest
+- Docker CLI
+  - https://hub.docker.com/search?q=&type=edition&offering=community
+
+
+# Azure resources
+This test requires instances of these Azure resources:
+- Azure Key Vault
+- Azure Managed Identity
+  - with secrets/set and secrets/delete permission for the Key Vault
+- Azure Container Registry
+
+The rest of this section is a walkthrough of deploying these resources.
+
+## Set environment variables to simplify copy-pasting
+- RESOURCE_GROUP
+  - name of an Azure resource group
+  - must be unique in the Azure subscription
+  - e.g. 'pod-identity-test'
+- ACR_NAME
+  - name of an Azure Container Registry
+  - 5-50 alphanumeric characters
+  - must be globally unique
+- MANAGED_IDENTITY_NAME
+  - 3-128 alphanumeric characters
+  - must be unique in the resource group
+- KEY_VAULT_NAME
+  - 3-24 alphanumeric characters
+  - must begin with a letter
+  - must be globally unique
+
+## Create resource group
+```sh
+az group create -n $RESOURCE_GROUP --location westus2
+```
+
+## Create a managed identity
+### Create the managed identity
+```sh
+az identity create -g $RESOURCE_GROUP -n $MANAGED_IDENTITY_NAME
+```
+
+### Save its ARM URI for later
+```sh
+export MANAGED_IDENTITY_ID=$(az identity show -g $RESOURCE_GROUP -n $MANAGED_IDENTITY_NAME --query id -o tsv)
+```
+
+## Key Vault
+### Create the Vault
+```sh
+az keyvault create -g $RESOURCE_GROUP -n $KEY_VAULT_NAME --sku standard
+```
+
+### Add an access policy for the managed identity
+```sh
+az keyvault set-policy -n $KEY_VAULT_NAME \
+  --object-id $(az identity show -g $RESOURCE_GROUP -n $MANAGED_IDENTITY_NAME --query principalId -o tsv) \
+  --secret-permissions set delete list
+```
+
+## Create Container Registry
+```sh
+az acr create -g $RESOURCE_GROUP -n $ACR_NAME --admin-enabled --sku basic
+```
+
+# Build container images
+The test application must be packaged as a Docker image.
+
+## Authenticate to ACR
+```sh
+az acr login -n $ACR_NAME
+```
+
+## Acquire the test code
+```sh
+git clone https://github.com/Azure/azure-sdk-for-python/ --branch main --single-branch --depth 1
+```
+
+The rest of this section assumes this working directory:
+```sh
+cd azure-sdk-for-python/sdk/identity/azure-identity/tests
+```
+
+## Build and push images to container registry
+### Set environment variables
+```sh
+export REPOSITORY=$(az acr show -g $RESOURCE_GROUP -n $ACR_NAME --query loginServer -o tsv) \
+  IMAGE_NAME=test-pod-identity \
+  PYTHON_VERSION=3.10
+```
+
+### Build image
+```sh
+docker build --no-cache --build-arg PYTHON_VERSION=$PYTHON_VERSION -t $REPOSITORY/$IMAGE_NAME:$PYTHON_VERSION ./managed-identity-live
+```
+
+### Push image
+```sh
+docker push $REPOSITORY/$IMAGE_NAME:$PYTHON_VERSION
+```
+
+Then set `PYTHON_VERSION` to the latest 3.x and run the above `docker build`
+and `docker push` commands again. (It's safe--and faster--to omit
+`--no-cache` from `docker build` the second time.)
+
+# Run tests
+
+Run these commands to run the tests in a container instance.
+
+## Set a name for the container group
+```sh
+export CONTAINER_NAME=managed-id-container-test-python${PYTHON_VERSION::1}
+```
+
+## Run the test
+```sh
+az container create -g $RESOURCE_GROUP -n $CONTAINER_NAME \
+ --assign-identity $MANAGED_IDENTITY_ID \
+ --restart-policy OnFailure \
+ --registry-username $(az acr credential show -n $ACR_NAME --query username -o tsv) \
+ --registry-password $(az acr credential show -n $ACR_NAME --query passwords[0].value -o tsv) \
+ --image $REPOSITORY/$IMAGE_NAME:$PYTHON_VERSION \
+ -e AZURE_IDENTITY_TEST_VAULT_URL=$(az keyvault show -g $RESOURCE_GROUP -n $KEY_VAULT_NAME --query properties.vaultUri -o tsv)
+```
+
+## Inspect output
+```sh
+az container logs -g $RESOURCE_GROUP -n $CONTAINER_NAME
+```
+
+Success looks like this:
+```
+============================= test session starts ==============================
+platform linux -- Python 3.10.8, pytest-7.2.0, pluggy-1.0.0 -- /usr/local/bin/python
+cachedir: .pytest_cache
+rootdir: /sdk/identity/azure-identity
+plugins: asyncio-0.20.1, cov-4.0.0
+asyncio: mode=strict
+collecting ... collected 4 items
+
+test_cloud_shell.py::test_cloud_shell_live SKIPPED (Cloud Shell MSI ...)  [ 25%]
+test_cloud_shell_async.py::test_cloud_shell_live SKIPPED (Cloud Shell...) [ 50%]
+test_managed_identity_live.py::test_managed_identity_live PASSED          [ 75%]
+test_managed_identity_live_async.py::test_managed_identity_live PASSED    [100%]
+
+=========================== short test summary info ============================
+SKIPPED [2] conftest.py:46: Cloud Shell MSI unavailable
+========================= 2 passed, 2 skipped in 1.30s =========================
+```
+`test_managed_identity_live` must pass. Other test cases may be skipped. No test case may fail.
+
+# Delete Azure resources
+Finally, delete the resources created above:
+```sh
+az group delete -n $RESOURCE_GROUP -y --no-wait
+```

sdk/identity/azure-identity/tests/managed-identity-live/requirements.txt

@@ -1,6 +1,8 @@
 ../../../../core/azure-core
 ../..
 ../../../../keyvault/azure-keyvault-secrets
+../../../../../tools/azure-devtools
+../../../../../tools/azure-sdk-tools
 pytest
 pytest-asyncio
 aiohttp>=3.0

sdk/identity/azure-identity/tests/managed-identity-live/service-fabric/service_fabric.md

@@ -19,7 +19,7 @@ The `arm-templates` directory contains Azure resource templates for creating the
 
 From a command prompt window, run
 ```
-git clone https://github.com/Azure/azure-sdk-for-python --single-branch --branch master --depth 1
+git clone https://github.com/Azure/azure-sdk-for-python --single-branch --branch main --depth 1
 cd azure-sdk-for-python/sdk/identity/azure-identity/tests/managed-identity-live/service-fabric
 ```
 
@@ -148,7 +148,7 @@ Your Service Fabric cluster will target each application by referencing a `.sfpk
 
 ### Upload the application packages to a storage account
 
-If using an existing cluster, ensure your resource group has a storage account connected to your cluster. If you deployed a cluster using the template provided, two storage accounts were created but only one needs to store the `.sfpkg` files for the applications (the one with the name corresponding to `applicationDiagnosticsStorageAccountName` in the template). 
+If using an existing cluster, ensure your resource group has a storage account connected to your cluster. If you deployed a cluster using the template provided, two storage accounts were created but only one needs to store the `.sfpkg` files for the applications (the one with the name corresponding to `applicationDiagnosticsStorageAccountName` in the template).
 
 Go to your resource group in the [Azure Portal](https://portal.azure.com) and click on the storage account. Go to the "Containers" page and create a new container named "apps" -- be sure the set the public access level to Blob.
 

sdk/identity/azure-identity/tests/managed-identity-live/test_cloud_shell_async.py

@@ -13,7 +13,7 @@
 @pytest.mark.asyncio
 async def test_cloud_shell_live(cloud_shell):
     credential = ManagedIdentityCredential()
-    token = credential.get_token("https://vault.azure.net")
+    token = await credential.get_token("https://vault.azure.net")
 
     # Validate the token by sending a request to the Key Vault. The request is manual because azure-keyvault-secrets
     # can't authenticate in Cloud Shell; the MSI endpoint there doesn't support AADv2 scopes.