...

Text file src/github.com/Azure/azure-sdk-for-go/eng/common/TestResources/README.md

Documentation: github.com/Azure/azure-sdk-for-go/eng/common/TestResources

     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