1---
2external help file: -help.xml
3Module Name:
4online version:
5schema: 2.0.0
6---
7
8# New-TestResources.ps1
9
10## SYNOPSIS
11Deploys live test resources defined for a service directory to Azure.
12
13## SYNTAX
14
15### Default (Default)
16```
17New-TestResources.ps1 [-BaseName <String>] [-ResourceGroupName <String>] [-ServiceDirectory] <String>
18 [-TestApplicationId <String>] [-TestApplicationSecret <String>] [-TestApplicationOid <String>]
19 [-SubscriptionId <String>] [-DeleteAfterHours <Int32>] [-Location <String>] [-Environment <String>]
20 [-ArmTemplateParameters <Hashtable>] [-AdditionalParameters <Hashtable>] [-EnvironmentVariables <Hashtable>]
21 [-CI] [-Force] [-OutFile] [-SuppressVsoCommands] [-WhatIf] [-Confirm] [<CommonParameters>]
22```
23
24### Provisioner
25```
26New-TestResources.ps1 [-BaseName <String>] [-ResourceGroupName <String>] [-ServiceDirectory] <String>
27 [-TestApplicationId <String>] [-TestApplicationSecret <String>] [-TestApplicationOid <String>]
28 -TenantId <String> [-SubscriptionId <String>] -ProvisionerApplicationId <String>
29 -ProvisionerApplicationSecret <String> [-DeleteAfterHours <Int32>] [-Location <String>]
30 [-Environment <String>] [-ArmTemplateParameters <Hashtable>] [-AdditionalParameters <Hashtable>]
31 [-EnvironmentVariables <Hashtable>] [-CI] [-Force] [-OutFile] [-SuppressVsoCommands] [-WhatIf] [-Confirm]
32 [<CommonParameters>]
33```
34
35## DESCRIPTION
36Deploys live test resouces specified in test-resources.json or test-resources.bicep
37files to a new resource group.
38
39This script searches the directory specified in $ServiceDirectory recursively
40for files named test-resources.json or test-resources.bicep.
41All found test-resources.json
42and test-resources.bicep files will be deployed to the test resource group.
43
44If no test-resources.json or test-resources.bicep files are located the script
45exits without making changes to the Azure environment.
46
47A service principal may optionally be passed to $TestApplicationId and $TestApplicationSecret.
48Test resources will grant this service principal access to the created resources.
49If no service principal is specified, a new one will be created and assigned the
50'Owner' role for the resource group associated with the test resources.
51
52This script runs in the context of credentials already specified in Connect-AzAccount
53or those specified in $ProvisionerApplicationId and $ProvisionerApplicationSecret.
54
55## EXAMPLES
56
57### EXAMPLE 1
58```
59Connect-AzAccount -Subscription 'REPLACE_WITH_SUBSCRIPTION_ID'
60New-TestResources.ps1 keyvault
61```
62
63Run this in a desktop environment to create a new AAD application and Service Principal
64for running live tests against the test resources created.
65The principal will have ownership
66rights to the resource group and the resources that it contains, but no other resources in
67the subscription.
68
69Requires PowerShell 7 to use ConvertFrom-SecureString -AsPlainText or convert
70the SecureString to plaintext by another means.
71
72### EXAMPLE 2
73```
74Connect-AzAccount -Subscription 'REPLACE_WITH_SUBSCRIPTION_ID'
75New-TestResources.ps1 `
76 -BaseName 'azsdk' `
77 -ServiceDirectory 'keyvault' `
78 -SubscriptionId 'REPLACE_WITH_SUBSCRIPTION_ID' `
79 -ResourceGroupName 'REPLACE_WITH_NAME_FOR_RESOURCE_GROUP' `
80 -Location 'eastus'
81```
82
83Run this in a desktop environment to specify the name and location of the resource
84group that test resources are being deployed to.
85This will also create a new AAD
86application and Service Principal for running live tests against the rest resources
87created.
88The principal will have ownership rights to the resource group and the
89resources that it contains, but no other resources in the subscription.
90
91Requires PowerShell 7 to use ConvertFrom-SecureString -AsPlainText or convert
92the SecureString to plaintext by another means.
93
94### EXAMPLE 3
95```
96Connect-AzAccount -Subscription 'REPLACE_WITH_SUBSCRIPTION_ID'
97New-TestResources.ps1 `
98 -BaseName 'azsdk' `
99 -ServiceDirectory 'keyvault' `
100 -SubscriptionId 'REPLACE_WITH_SUBSCRIPTION_ID' `
101 -ResourceGroupName 'REPLACE_WITH_NAME_FOR_RESOURCE_GROUP' `
102 -Location 'eastus' `
103 -TestApplicationId 'REPLACE_WITH_TEST_APPLICATION_ID' `
104 -TestApplicationSecret 'REPLACE_WITH_TEST_APPLICATION_SECRET'
105```
106
107Run this in a desktop environment to specify the name and location of the resource
108group that test resources are being deployed to.
109This will grant ownership rights
110to the 'TestApplicationId' for the resource group and the resources that it contains,
111without altering its existing permissions.
112
113### EXAMPLE 4
114```
115New-TestResources.ps1 `
116 -BaseName 'azsdk' `
117 -ServiceDirectory 'keyvault' `
118 -SubscriptionId 'REPLACE_WITH_SUBSCRIPTION_ID' `
119 -ResourceGroupName 'REPLACE_WITH_NAME_FOR_RESOURCE_GROUP' `
120 -Location 'eastus' `
121 -ProvisionerApplicationId 'REPLACE_WITH_PROVISIONER_APPLICATION_ID' `
122 -ProvisionerApplicationSecret 'REPLACE_WITH_PROVISIONER_APPLICATION_ID' `
123 -TestApplicationId 'REPLACE_WITH_TEST_APPLICATION_ID' `
124 -TestApplicationOid 'REPLACE_WITH_TEST_APPLICATION_OBJECT_ID' `
125 -TestApplicationSecret 'REPLACE_WITH_TEST_APPLICATION_SECRET'
126```
127
128Run this in a desktop environment to specify the name and location of the resource
129group that test resources are being deployed to.
130The script will be executed in the
131context of the 'ProvisionerApplicationId' rather than the caller.
132
133Depending on the permissions of the Provisioner Application principal, the script may
134grant ownership rights 'TestApplicationId' for the resource group and the resources
135that it contains, or may emit a message indicating that it was unable to perform the grant.
136
137For the Provisioner Application principal to perform the grant, it will need the
138permission 'Application.ReadWrite.OwnedBy' for the Microsoft Graph API.
139
140Requires PowerShell 7 to use ConvertFrom-SecureString -AsPlainText or convert
141the SecureString to plaintext by another means.
142
143### EXAMPLE 5
144```
145New-TestResources.ps1 `
146 -ServiceDirectory '$(ServiceDirectory)' `
147 -TenantId '$(TenantId)' `
148 -ProvisionerApplicationId '$(ProvisionerId)' `
149 -ProvisionerApplicationSecret '$(ProvisionerSecret)' `
150 -TestApplicationId '$(TestAppId)' `
151 -TestApplicationSecret '$(TestAppSecret)' `
152 -DeleteAfterHours 24 `
153 -CI `
154 -Force `
155 -Verbose
156```
157
158Run this in an Azure DevOps CI (with approrpiate variables configured) before
159executing live tests.
160The script will output variables as secrets (to enable
161log redaction).
162
163## PARAMETERS
164
165### -BaseName
166A name to use in the resource group and passed to the ARM template as 'baseName'.
167Limit $BaseName to enough characters to be under limit plus prefixes specified in
168the ARM template.
169See also https://docs.microsoft.com/azure/architecture/best-practices/resource-naming
170
171Note: The value specified for this parameter will be overriden and generated
172by New-TestResources.ps1 if $CI is specified.
173
174```yaml
175Type: String
176Parameter Sets: (All)
177Aliases:
178
179Required: False
180Position: Named
181Default value: None
182Accept pipeline input: False
183Accept wildcard characters: False
184```
185
186### -ResourceGroupName
187Set this value to deploy directly to a Resource Group that has already been
188created or to create a new resource group with this name.
189
190If not specified, the $BaseName will be used to generate name for the resource
191group that will be created.
192
193```yaml
194Type: String
195Parameter Sets: (All)
196Aliases:
197
198Required: False
199Position: Named
200Default value: None
201Accept pipeline input: False
202Accept wildcard characters: False
203```
204
205### -ServiceDirectory
206A directory under 'sdk' in the repository root - optionally with subdirectories
207specified - in which to discover ARM templates named 'test-resources.json' and
208Bicep templates named 'test-resources.bicep'.
209This can also be an absolute path
210or specify parent directories.
211
212```yaml
213Type: String
214Parameter Sets: (All)
215Aliases:
216
217Required: True
218Position: 1
219Default value: None
220Accept pipeline input: False
221Accept wildcard characters: False
222```
223
224### -TestApplicationId
225Optional Azure Active Directory Application ID to authenticate the test runner
226against deployed resources.
227Passed to the ARM template as 'testApplicationId'.
228
229If not specified, a new AAD Application will be created and assigned the 'Owner'
230role for the resource group associated with the test resources.
231No permissions
232will be granted to the subscription or other resources.
233
234For those specifying a Provisioner Application principal as 'ProvisionerApplicationId',
235it will need the permission 'Application.ReadWrite.OwnedBy' for the Microsoft Graph API
236in order to create the Test Application principal.
237
238This application is used by the test runner to execute tests against the
239live test resources.
240
241```yaml
242Type: String
243Parameter Sets: (All)
244Aliases:
245
246Required: False
247Position: Named
248Default value: None
249Accept pipeline input: False
250Accept wildcard characters: False
251```
252
253### -TestApplicationSecret
254Optional service principal secret (password) to authenticate the test runner
255against deployed resources.
256Passed to the ARM template as
257'testApplicationSecret'.
258
259This application is used by the test runner to execute tests against the
260live test resources.
261
262```yaml
263Type: String
264Parameter Sets: (All)
265Aliases:
266
267Required: False
268Position: Named
269Default value: None
270Accept pipeline input: False
271Accept wildcard characters: False
272```
273
274### -TestApplicationOid
275Service Principal Object ID of the AAD Test Application.
276This is used to assign
277permissions to the AAD application so it can access tested features on the live
278test resources (e.g.
279Role Assignments on resources).
280It is passed as to the ARM
281template as 'testApplicationOid'
282
283If not specified, an attempt will be made to query it from the Azure Active Directory
284tenant.
285For those specifying a service principal as 'ProvisionerApplicationId',
286it will need the permission 'Application.Read.All' for the Microsoft Graph API
287in order to query AAD.
288
289For more information on the relationship between AAD Applications and Service
290Principals see: https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals
291
292```yaml
293Type: String
294Parameter Sets: (All)
295Aliases:
296
297Required: False
298Position: Named
299Default value: None
300Accept pipeline input: False
301Accept wildcard characters: False
302```
303
304### -TenantId
305The tenant ID of a service principal when a provisioner is specified.
306The same
307Tenant ID is used for Test Application and Provisioner Application.
308
309This value is passed to the ARM template as 'tenantId'.
310
311```yaml
312Type: String
313Parameter Sets: Provisioner
314Aliases:
315
316Required: True
317Position: Named
318Default value: None
319Accept pipeline input: False
320Accept wildcard characters: False
321```
322
323### -SubscriptionId
324Optional subscription ID to use for new resources when logging in as a
325provisioner.
326You can also use Set-AzContext if not provisioning.
327
328If you do not specify a SubscriptionId and are not logged in, one will be
329automatically selected for you by the Connect-AzAccount cmdlet.
330
331Once you are logged in (or were previously), the selected SubscriptionId
332will be used for subsequent operations that are specific to a subscription.
333
334```yaml
335Type: String
336Parameter Sets: (All)
337Aliases:
338
339Required: False
340Position: Named
341Default value: None
342Accept pipeline input: False
343Accept wildcard characters: False
344```
345
346### -ProvisionerApplicationId
347Optional Application ID of the Azure Active Directory service principal to use for
348provisioning the test resources.
349If not, specified New-TestResources.ps1 uses the
350context of the caller to provision.
351
352If specified, the Provisioner Application principal would benefit from the following
353permissions to the Microsoft Graph API:
354
355 - 'Application.Read.All' in order to query AAD to obtain the 'TestApplicaitonOid'
356
357 - 'Application.ReadWrite.OwnedBy' in order to create the Test Application principal
358 or grant an existing principal ownership of the resource group associated with
359 the test resources.
360
361If the provisioner does not have these permissions, it can still be used with
362New-TestResources.ps1 by specifying an existing Test Application principal, including
363its Object ID, and managing permissions to the resource group manually.
364
365This value is not passed to the ARM template.
366
367```yaml
368Type: String
369Parameter Sets: Provisioner
370Aliases:
371
372Required: True
373Position: Named
374Default value: None
375Accept pipeline input: False
376Accept wildcard characters: False
377```
378
379### -ProvisionerApplicationSecret
380A service principal secret (password) used to provision test resources when a
381provisioner is specified.
382
383This value is not passed to the ARM template.
384
385```yaml
386Type: String
387Parameter Sets: Provisioner
388Aliases:
389
390Required: True
391Position: Named
392Default value: None
393Accept pipeline input: False
394Accept wildcard characters: False
395```
396
397### -DeleteAfterHours
398Positive integer number of hours from the current time to set the
399'DeleteAfter' tag on the created resource group.
400The computed value is a
401timestamp of the form "2020-03-04T09:07:04.3083910Z".
402
403An optional cleanup process can delete resource groups whose "DeleteAfter"
404timestamp is less than the current time.
405
406This is used for CI automation.
407
408```yaml
409Type: Int32
410Parameter Sets: (All)
411Aliases:
412
413Required: False
414Position: Named
415Default value: 120
416Accept pipeline input: False
417Accept wildcard characters: False
418```
419
420### -Location
421Optional location where resources should be created.
422If left empty, the default
423is based on the cloud to which the template is being deployed:
424
425* AzureCloud -\> 'westus2'
426* AzureUSGovernment -\> 'usgovvirginia'
427* AzureChinaCloud -\> 'chinaeast2'
428* Dogfood -\> 'westus'
429
430```yaml
431Type: String
432Parameter Sets: (All)
433Aliases:
434
435Required: False
436Position: Named
437Default value: None
438Accept pipeline input: False
439Accept wildcard characters: False
440```
441
442### -Environment
443Optional name of the cloud environment.
444The default is the Azure Public Cloud
445('AzureCloud')
446
447```yaml
448Type: String
449Parameter Sets: (All)
450Aliases:
451
452Required: False
453Position: Named
454Default value: AzureCloud
455Accept pipeline input: False
456Accept wildcard characters: False
457```
458
459### -ArmTemplateParameters
460Optional key-value pairs of parameters to pass to the ARM template(s).
461
462```yaml
463Type: Hashtable
464Parameter Sets: (All)
465Aliases:
466
467Required: False
468Position: Named
469Default value: None
470Accept pipeline input: False
471Accept wildcard characters: False
472```
473
474### -AdditionalParameters
475Optional key-value pairs of parameters to pass to the ARM template(s) and pre-post scripts.
476
477```yaml
478Type: Hashtable
479Parameter Sets: (All)
480Aliases:
481
482Required: False
483Position: Named
484Default value: None
485Accept pipeline input: False
486Accept wildcard characters: False
487```
488
489### -EnvironmentVariables
490Optional key-value pairs of parameters to set as environment variables to the shell.
491
492```yaml
493Type: Hashtable
494Parameter Sets: (All)
495Aliases:
496
497Required: False
498Position: Named
499Default value: @{}
500Accept pipeline input: False
501Accept wildcard characters: False
502```
503
504### -CI
505Indicates the script is run as part of a Continuous Integration / Continuous
506Deployment (CI/CD) build (only Azure Pipelines is currently supported).
507
508```yaml
509Type: SwitchParameter
510Parameter Sets: (All)
511Aliases:
512
513Required: False
514Position: Named
515Default value: ($null -ne $env:SYSTEM_TEAMPROJECTID)
516Accept pipeline input: False
517Accept wildcard characters: False
518```
519
520### -Force
521Force creation of resources instead of being prompted.
522
523```yaml
524Type: SwitchParameter
525Parameter Sets: (All)
526Aliases:
527
528Required: False
529Position: Named
530Default value: False
531Accept pipeline input: False
532Accept wildcard characters: False
533```
534
535### -OutFile
536Save test environment settings into a .env file next to test resources template.
537The contents of the file are protected via the .NET Data Protection API (DPAPI).
538This is supported only on Windows.
539The environment file is scoped to the current
540service directory.
541
542The environment file will be named for the test resources template that it was
543generated for.
544For ARM templates, it will be test-resources.json.env.
545For
546Bicep templates, test-resources.bicep.env.
547
548```yaml
549Type: SwitchParameter
550Parameter Sets: (All)
551Aliases:
552
553Required: False
554Position: Named
555Default value: False
556Accept pipeline input: False
557Accept wildcard characters: False
558```
559
560### -SuppressVsoCommands
561By default, the -CI parameter will print out secrets to logs with Azure Pipelines log
562commands that cause them to be redacted.
563For CI environments that don't support this (like
564stress test clusters), this flag can be set to $false to avoid printing out these secrets to the logs.
565
566```yaml
567Type: SwitchParameter
568Parameter Sets: (All)
569Aliases:
570
571Required: False
572Position: Named
573Default value: ($null -eq $env:SYSTEM_TEAMPROJECTID)
574Accept pipeline input: False
575Accept wildcard characters: False
576```
577
578### -WhatIf
579Shows what would happen if the cmdlet runs.
580The cmdlet is not run.
581
582```yaml
583Type: SwitchParameter
584Parameter Sets: (All)
585Aliases: wi
586
587Required: False
588Position: Named
589Default value: None
590Accept pipeline input: False
591Accept wildcard characters: False
592```
593
594### -Confirm
595Prompts you for confirmation before running the cmdlet.
596
597```yaml
598Type: SwitchParameter
599Parameter Sets: (All)
600Aliases: cf
601
602Required: False
603Position: Named
604Default value: None
605Accept pipeline input: False
606Accept wildcard characters: False
607```
608
609### CommonParameters
610This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
611
612## INPUTS
613
614## OUTPUTS
615
616## NOTES
617
618## RELATED LINKS
View as plain text