1# Live Test Resource Management
2
3Running and recording live tests often requires first creating some resources
4in Azure. Service directories that include a `test-resources.json` or `test-resources.bicep`
5file require running [New-TestResources.ps1][] to create these resources and output
6environment variables you must set.
7
8The following scripts can be used both in on your desktop for developer
9scenarios as well as on hosted agents for continuous integration testing.
10
11* [New-TestResources.ps1][] - Creates new test resources for a given service.
12* [Remove-TestResources.ps1][] - Deletes previously created resources.
13
14## Prerequisites
15
161. Install [PowerShell][] version 7.0 or newer.
172. Install the [Azure PowerShell][PowerShellAz].
18
19## On the Desktop
20
21To set up your Azure account to run live tests, you'll need to log into Azure,
22and create the resources defined in your `test-resources.json` or `test-resources.bicep`
23template as shown in the following example using Azure Key Vault. The script will create
24a service principal automatically, or you may create a service principal that can be reused
25subsequently.
26
27Note that `-Subscription` is an optional parameter but recommended if your account
28is a member of multiple subscriptions. If you didn't specify it when logging in,
29you should select your desired subscription using `Select-AzSubscription`. The
30default can be saved using `Set-AzDefault` for future sessions.
31
32```powershell
33Connect-AzAccount -Subscription 'YOUR SUBSCRIPTION ID'
34eng\common\TestResources\New-TestResources.ps1 keyvault
35```
36
37The `OutFile` switch will be set by default if you are running this for a .NET project on Windows.
38This will save test environment settings into a `test-resources.json.env` file next to `test-resources.json`
39or a `test-resources.bicep.env` file next to `test-resources.bicep`. The file is protected via DPAPI.
40The environment file would be scoped to the current repository directory and avoids the need to
41set environment variables or restart your IDE to recognize them.
42
43Along with some log messages, this will output environment variables based on
44your current shell like in the following example:
45
46```powershell
47${env:KEYVAULT_TENANT_ID} = '<<secret>>'
48${env:KEYVAULT_CLIENT_ID} = '<<secret>>'
49${env:KEYVAULT_CLIENT_SECRET} = '<<secret>>'
50${env:KEYVAULT_SUBSCRIPTION_ID} = 'YOUR SUBSCRIPTION ID'
51${env:KEYVAULT_RESOURCE_GROUP} = 'rg-myusername'
52${env:KEYVAULT_LOCATION} = 'westus2'
53${env:KEYVAULT_SKU} = 'premium'
54${env:AZURE_KEYVAULT_URL} = '<<url>>'
55```
56
57For security reasons we do not set these environment variables automatically
58for either the current process or persistently for future sessions. You must
59do that yourself based on your current platform and shell.
60
61If your current shell was detected properly, you should be able to copy and
62paste the output directly in your terminal and add to your profile script.
63For example, in PowerShell on Windows you can copy the output above and paste
64it back into the terminal to set those environment variables for the current
65process. To persist these variables for future terminal sessions or for
66applications started outside the terminal, you could copy and paste the
67following commands:
68
69```powershell
70setx KEYVAULT_TENANT_ID ${env:KEYVAULT_TENANT_ID}
71setx KEYVAULT_CLIENT_ID ${env:KEYVAULT_CLIENT_ID}
72setx KEYVAULT_CLIENT_SECRET ${env:KEYVAULT_CLIENT_SECRET}
73setx KEYVAULT_SUBSCRIPTION_ID ${env:KEYVAULT_SUBSCRIPTION_ID}
74setx KEYVAULT_RESOURCE_GROUP ${env:KEYVAULT_RESOURCE_GROUP}
75setx KEYVAULT_LOCATION ${env:KEYVAULT_LOCATION}
76setx KEYVAULT_SKU ${env:KEYVAULT_SKU}
77setx AZURE_KEYVAULT_URL ${env:AZURE_KEYVAULT_URL}
78```
79
80### Pre- and Post- Scripts
81
82Sometimes creating test resources requires either some work to be done prior to or after the main test-resources.json script is executed.
83For these scenarios a `test-resources-pre.ps1` or `test-resources-post.ps1`, respectively, can be created in the same folder as the `test-resources.json` file.
84
85For example, it may be necessary to create artifacts prior to provisioning the actual resource, such as a certificate.
86Typically the created artifact will need to be passed to `test-resources.json` to be used in the ARM template or as output (or both).
87
88Below is an example of how `$templateFileParameters` can be used to pass data from the `pre-` script to `test-resources.json`.
89
90**Snippet from `test-resources-pre.ps1`**
91```powershell
92$cert = New-X509Certificate2 -SubjectName 'E=opensource@microsoft.com, CN=Azure SDK, OU=Azure SDK, O=Microsoft, L=Frisco, S=TX, C=US' -ValidDays 3652
93# Create new entries in $templateFileParameters
94$templateFileParameters['ConfidentialLedgerPrincipalPEM'] = Format-X509Certificate2 -Certificate $cert
95$templateFileParameters['ConfidentialLedgerPrincipalPEMPK'] = Format-X509Certificate2 -Type Pkcs8 -Certificate $cert
96```
97
98**Snippet from the corresponding `test-resources.json`.**
99
100Note that the values present in `$templateFileParameters` will map to parameters of the same name.
101```json
102{
103 "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
104 "contentVersion": "1.0.0.0",
105 "parameters": {
106 "_comment": "Other required parameters would go here... (this is not part of the actual test-resources.json)",
107 "ConfidentialLedgerPrincipalPEM": {
108 "type": "string",
109 "metadata": {
110 "description": "The certificate to configure as a certBasedSecurityPrincipal."
111 }
112 },
113 "ConfidentialLedgerPrincipalPEMPK": {
114 "type": "string",
115 "metadata": {
116 "description": "The certificate to configure as a certBasedSecurityPrincipal."
117 }
118 }
119 },
120}
121```
122
123### Cleaning up Resources
124
125By default, resource groups are tagged with a `DeleteAfter` value and date according to the default or specified
126value for the `-DeleteAfterHours` switch. You can use this tag in scheduled jobs to remove older resources based
127on that date.
128
129If you are not ready for the resources to be deleted, you can update the resource group by running [Update-TestResources.ps1][]:
130
131```powershell
132Update-TestResources.ps1 keyvault
133```
134
135This will extend the expiration time by the default value (e.g. 48 hours) from now.
136
137Alternatively, after running or recording live tests, if you do not plan on further testing
138you can immediately remove the test resources you created above by running [Remove-TestResources.ps1][]:
139
140```powershell
141Remove-TestResources.ps1 keyvault -Force
142```
143
144If you persisted environment variables, you should also remove those as well.
145
146### Passing Additional Arguments
147
148Some test-resources.json templates utilize the `AdditionalParameters` parameter to control additional resource configuration options. For example:
149
150```powershell
151New-TestResources.ps1 keyvault -AdditionalParameters @{enableHsm = $true}
152```
153
154## In CI
155
156Test pipelines should include deploy-test-resources.yml and
157remove-test-resources.yml like in the following examples:
158
159```yml
160- template: /eng/common/TestResources/deploy-test-resources.yml
161 parameters:
162 ServiceDirectory: '${{ parameters.ServiceDirectory }}'
163
164# Run tests
165
166- template: /eng/common/TestResources/remove-test-resources.yml
167```
168
169Be sure to link the **Secrets for Resource Provisioner** variable group
170into the test pipeline for these scripts to work.
171
172## Documentation
173
174To regenerate documentation for scripts within this directory, you can install
175[platyPS][] and run it like in the following example:
176
177```powershell
178Install-Module platyPS -Scope CurrentUser -Force
179New-MarkdownHelp -Command .\New-TestResources.ps1 -OutputFolder . -Force
180```
181
182After the markdown files are generated, please make sure all "http" URIs use "https".
183
184PowerShell markdown documentation created with [platyPS][].
185
186 [New-TestResources.ps1]: https://aka.ms/azsdk/tools/New-TestResources
187 [Update-TestResources.ps1]: https://aka.ms/azsdk/tools/Update-TestResources
188 [Remove-TestResources.ps1]: https://aka.ms/azsdk/tools/Remove-TestResources
189 [PowerShell]: https://github.com/PowerShell/PowerShell
190 [PowerShellAz]: https://docs.microsoft.com/powershell/azure/install-az-ps
191 [platyPS]: https://github.com/PowerShell/platyPS
View as plain text