diff --git a/eng/common/TestResources/New-TestResources.ps1 b/eng/common/TestResources/New-TestResources.ps1 index c361fcb0b..133137ea7 100644 --- a/eng/common/TestResources/New-TestResources.ps1 +++ b/eng/common/TestResources/New-TestResources.ps1 @@ -446,7 +446,7 @@ Force creation of resources instead of being prompted. Connect-AzAccount -Subscription "REPLACE_WITH_SUBSCRIPTION_ID" $testAadApp = New-AzADServicePrincipal -Role Owner -DisplayName 'azure-sdk-live-test-app' New-TestResources.ps1 ` - -BaseName 'myalias' ` + -BaseName 'uuid123' ` -ServiceDirectory 'keyvault' ` -TestApplicationId $testAadApp.ApplicationId.ToString() ` -TestApplicationSecret (ConvertFrom-SecureString $testAadApp.Secret -AsPlainText) @@ -475,14 +475,6 @@ Run this in an Azure DevOps CI (with approrpiate variables configured) before executing live tests. The script will output variables as secrets (to enable log redaction). -.OUTPUTS -Entries from the ARM templates' "output" section in environment variable syntax -(e.g. $env:RESOURCE_NAME='<< resource name >>') that can be used for running -live tests. - -If run in -CI mode the environment variables will be output in syntax that Azure -DevOps can consume. - .LINK Remove-TestResources.ps1 #> diff --git a/eng/common/TestResources/New-TestResources.ps1.md b/eng/common/TestResources/New-TestResources.ps1.md index ac0d33260..39efc1446 100644 --- a/eng/common/TestResources/New-TestResources.ps1.md +++ b/eng/common/TestResources/New-TestResources.ps1.md @@ -53,11 +53,10 @@ specified in $ProvisionerApplicationId and $ProvisionerApplicationSecret. ### EXAMPLE 1 ``` -$subscriptionId = "REPLACE_WITH_SUBSCRIPTION_ID" -Connect-AzAccount -Subscription $subscriptionId +Connect-AzAccount -Subscription "REPLACE_WITH_SUBSCRIPTION_ID" $testAadApp = New-AzADServicePrincipal -Role Owner -DisplayName 'azure-sdk-live-test-app' -.\eng\common\LiveTestResources\New-TestResources.ps1 ` - -BaseName 'myalias' ` +New-TestResources.ps1 ` + -BaseName 'uuid123' ` -ServiceDirectory 'keyvault' ` -TestApplicationId $testAadApp.ApplicationId.ToString() ` -TestApplicationSecret (ConvertFrom-SecureString $testAadApp.Secret -AsPlainText) @@ -71,7 +70,7 @@ the SecureString to plaintext by another means. ### EXAMPLE 2 ``` -eng/New-TestResources.ps1 ` +New-TestResources.ps1 ` -BaseName 'Generated' ` -ServiceDirectory '$(ServiceDirectory)' ` -TenantId '$(TenantId)' ` @@ -215,7 +214,7 @@ Accept wildcard characters: False ``` ### -SubscriptionId -Optional subscription ID to use for new resources when logging in as a +Optional subscription ID to use for new resources when logging in as a provisioner. You can also use Set-AzContext if not provisioning. @@ -416,16 +415,12 @@ Accept wildcard characters: False ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +## INPUTS + ## OUTPUTS -### Entries from the ARM templates' "output" section in environment variable syntax -### (e.g. $env:RESOURCE_NAME='<< resource name >>') that can be used for running -### live tests. -### If run in -CI mode the environment variables will be output in syntax that Azure -### DevOps can consume. ## NOTES ## RELATED LINKS -[Remove-TestResources.ps1](./New-TestResources.ps1.md) - +[Remove-TestResources.ps1](./Remove-TestResources.ps1.md) diff --git a/eng/common/TestResources/README.md b/eng/common/TestResources/README.md index 8eb911419..522bbc6b0 100644 --- a/eng/common/TestResources/README.md +++ b/eng/common/TestResources/README.md @@ -1,29 +1,112 @@ # Live Test Resource Management -Live test runs require pre-existing resources in Azure. This set of PowerShell -commands automates creation and teardown of live test resources for Desktop and -CI scenarios. +Running and recording live tests often requires first creating some resources +in Azure. Service directories that include a test-resources.yml file require +running [New-TestResources.ps1][] to create these resources and output +environment variables you must set. -* [New-TestResources.ps1](./New-TestResources.ps1.md) - Create new test resources -for the given service. -* [Remove-TestResources.ps1](./New-TestResources.ps1.md) - Deletes resources +The following scripts can be used both in on your desktop for developer +scenarios as well as on hosted agents for continuous integration testing. + +* [New-TestResources.ps1][] - Creates new test resources for a given service. +* [Remove-TestResources.ps1][] - Deletes previously created resources. ## On the Desktop -Run `New-TestResources.ps1` on your desktop to create live test resources for a -given service (e.g. Storage, Key Vault, etc.). The command will output -environment variables that need to be set when running the live tests. +To set up your Azure account to run live tests, you'll need to log into Azure, +create a service principal, and set up your resources defined in +test-resources.json as shown in the following example using Azure Search. -See examples for how to create the needed Service Principals and execute live -tests. +Note that `-Subscription` is an optional parameter but recommended if your account +is a member of multiple subscriptions. + +```powershell +Connect-AzAccount -Subscription 'YOUR SUBSCRIPTION ID' +$sp = New-AzADServicePrincipal -Role Owner +eng\common\TestResources\New-TestResources.ps1 ` + -BaseName 'myusername' ` + -ServiceDirectory 'search' ` + -TestApplicationId $sp.ApplicationId ` + -TestApplicationSecret (ConvertFrom-SecureString $sp.Secret -AsPlainText) +``` + +Along with some log messages, this will output environment variables based on +your current shell like in the following example: + +```powershell +$env:AZURE_TENANT_ID = '<>' +$env:AZURE_CLIENT_ID = '<>' +$env:AZURE_CLIENT_SECRET = '<>' +$env:AZURE_SUBSCRIPTION_ID = 'YOUR SUBSCRIPTION ID' +$env:AZURE_RESOURCE_GROUP = 'rg-myusername' +$env:AZURE_LOCATION = 'westus2' +$env:AZURE_SEARCH_STORAGE_NAME = 'myusernamestg' +$env:AZURE_SEARCH_STORAGE_KEY = '<>' +``` + +For security reasons we do not set these environment variables automatically +for either the current process or persistently for future sessions. You must +do that yourself based on your current platform and shell. + +If your current shell was detected properly, you should be able to copy and +paste the output directly in your terminal and add to your profile script. +For example, in PowerShell on Windows you can copy the output above and paste +it back into the terminal to set those environment variables for the current +process. To persist these variables for future terminal sessions or for +applications started outside the terminal, you could copy and paste the +following commands: + +```powershell +setx AZURE_TENANT_ID $env:AZURE_TENANT_ID +setx AZURE_CLIENT_ID $env:AZURE_CLIENT_ID +setx AZURE_CLIENT_SECRET $env:AZURE_CLIENT_SECRET +setx AZURE_SUBSCRIPTION_ID $env:AZURE_SUBSCRIPTION_ID +setx AZURE_RESOURCE_GROUP $env:AZURE_RESOURCE_GROUP +setx AZURE_LOCATION $env:AZURE_LOCATION +setx AZURE_SEARCH_STORAGE_NAME $env:AZURE_SEARCH_STORAGE_NAME +setx AZURE_SEARCH_STORAGE_KEY $env:AZURE_SEARCH_STORAGE_KEY +``` + +After running or recording live tests, if you do not plan on further testing +you can remove the test resources you created above by running +[Remove-TestResources.ps1][]: + +```powershell +Remove-TestResources.ps1 -BaseName 'myusername' -Force +``` + +If you persisted environment variables, you should also remove those as well. ## In CI -The `New-TestResources.ps1` script is invoked on each test job to create an -isolated environment for live tests. Test resource isolation makes it easier to -parallelize test runs. +Test pipelines should include deploy-test-resources.yml and +remove-test-resources.yml like in the following examples: -## Other +```yml +- template: /eng/common/TestResources/deploy-test-resources.yml + parameters: + ServiceDirectory: '${{ parameters.ServiceDirectory }}' -PowerShell markdown documentation created with -[PlatyPS](https://github.com/PowerShell/platyPS) \ No newline at end of file +# Run tests + +- template: /eng/common/TestResources/remove-test-resources.yml +``` + +Be sure to link the **Secrets for Resource Provisioner** variable group +into the test pipeline for these scripts to work. + +## Documentation + +To regenerate documentation for scripts within this directory, you can install +[platyPS][] and run it like in the following example: + +```powershell +Install-Module platyPS -Scope CurrentUser -Force +New-MarkdownHelp -Command .\New-TestResources.ps1 -OutputFolder . -Force +``` + +PowerShell markdown documentation created with [platyPS][]. + + [New-TestResources.ps1]: ./New-TestResources.ps1.md + [Remove-TestResources.ps1]: ./Remove-TestResources.ps1.md + [platyPS]: https://github.com/PowerShell/platyPS diff --git a/eng/common/TestResources/Remove-TestResources.ps1 b/eng/common/TestResources/Remove-TestResources.ps1 index 881e48afe..961452fe8 100644 --- a/eng/common/TestResources/Remove-TestResources.ps1 +++ b/eng/common/TestResources/Remove-TestResources.ps1 @@ -165,7 +165,7 @@ Name of the cloud environment. The default is the Azure Public Cloud Force removal of resource group without asking for user confirmation .EXAMPLE -./Remove-TestResources.ps1 -BaseName uuid123 -Force +Remove-TestResources.ps1 -BaseName 'uuid123' -Force Use the currently logged-in account to delete the resource group by the name of 'rg-uuid123' diff --git a/eng/common/TestResources/Remove-TestResources.ps1.md b/eng/common/TestResources/Remove-TestResources.ps1.md index 44d4a8a11..edf3990ce 100644 --- a/eng/common/TestResources/Remove-TestResources.ps1.md +++ b/eng/common/TestResources/Remove-TestResources.ps1.md @@ -53,7 +53,7 @@ create resources. ### EXAMPLE 1 ``` -./Remove-TestResources.ps1 -BaseName uuid123 -Force +Remove-TestResources.ps1 -BaseName 'uuid123' -Force ``` Use the currently logged-in account to delete the resource group by the name of @@ -61,7 +61,7 @@ Use the currently logged-in account to delete the resource group by the name of ### EXAMPLE 2 ``` -eng/Remove-TestResources.ps1 ` +Remove-TestResources.ps1 ` -ResourceGroupName "${env:AZURE_RESOURCEGROUP_NAME}" ` -TenantId '$(TenantId)' ` -ProvisionerApplicationId '$(AppId)' ` @@ -123,7 +123,7 @@ Accept wildcard characters: False ``` ### -SubscriptionId -Optional subscription ID to use for new resources when logging in as a +Optional subscription ID to use for new resources when logging in as a provisioner. You can also use Set-AzContext if not provisioning. @@ -235,7 +235,12 @@ Accept wildcard characters: False ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +## INPUTS + +## OUTPUTS + +## NOTES + ## RELATED LINKS [New-TestResources.ps1](./New-TestResources.ps1.md) -