Document Details

{ "type": "Microsoft.Resources/deploymentScripts", "apiVersion": "2020-10-01", "name": "runPowerShellInline", "location": "[resourceGroup().location]", "tags": { "tagName1": "tagValue1", "tagName2": "tagValue2" }, "kind": "AzurePowerShell", // or "AzureCLI" "identity": { "type": "userAssigned", "userAssignedIdentities": { "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {} } }, "properties": { "forceUpdateTag": "1", "containerSettings": { "containerGroupName": "mycustomaci" }, "storageAccountSettings": { "storageAccountName": "myStorageAccount", "storageAccountKey": "myKey" }, "azPowerShellVersion": "9.7", // or "azCliVersion": "2.47.0", "arguments": "-name \\\"John Dole\\\"", "environmentVariables": [ { "name": "UserName", "value": "jdole" }, { "name": "Password", "secureValue": "jDolePassword" } ], "scriptContent": " param([string] $name) $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password} Write-Output $output $DeploymentScriptOutputs = @{} $DeploymentScriptOutputs['text'] = $output ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1", "supportingScriptUris":[], "timeout": "PT30M", "cleanupPreference": "OnSuccess", "retentionInterval": "P1D" } }

The output looks like: :::image type="content" source="./media/deployment-script-template/resource-manager-template-deployment-script-helloworld-output.png" alt-text="Screenshot of Resource Manager template deployment script hello world output."::: ## Use external scripts In addition to inline scripts, you can also use external script files. Only primary PowerShell scripts with the _ps1_ file extension are supported. For CLI scripts, the primary scripts can have any extensions (or without an extension), as long as the scripts are valid bash scripts. To use external script files, replace `scriptContent` with `primaryScriptUri`. For example:

See [Sample templates](#sample-templates) for a complete `Microsoft.Resources/deploymentScripts` definition sample. When an existing storage account is used, the script service creates a file share with a unique name. See [Clean up deployment script resources](#clean-up-deployment-script-resources) for how the script service cleans up the file share. ## Develop deployment scripts ### Handle nonterminating errors You can control how PowerShell responds to nonterminating errors by using the `$ErrorActionPreference` variable in your deployment script. If the variable isn't set in your deployment script, the script service uses the default value **Continue**. The script service sets the resource provisioning state to **Failed** when the script encounters an error despite the setting of `$ErrorActionPreference`. ### Use environment variables Deployment script uses these environment variables: |Environment variable|Default value|System reserved| |--------------------|-------------|---------------| |AZ_SCRIPTS_AZURE_ENVIRONMENT|AzureCloud|N| |AZ_SCRIPTS_CLEANUP_PREFERENCE|OnExpiration|N| |AZ_SCRIPTS_OUTPUT_PATH|<AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY>/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME>|Y| |AZ_SCRIPTS_PATH_INPUT_DIRECTORY|/mnt/azscripts/azscriptinput|Y| |AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY|/mnt/azscripts/azscriptoutput|Y| |AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME|Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh|Y| |AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME|primaryscripturi.config|Y| |AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME|supportingscripturi.config|Y| |AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME|scriptoutputs.json|Y| |AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME|executionresult.json|Y| |AZ_SCRIPTS_USER_ASSIGNED_IDENTITY|/subscriptions/|N| For more information about using `AZ_SCRIPTS_OUTPUT_PATH`, see [Work with outputs from CLI script](#work-with-outputs-from-cli-scripts). ### Pass secured strings to deployment script Setting environment variables (EnvironmentVariable) in your container instances allows you to provide dynamic configuration of the application or script run by the container. Deployment script handles nonsecured and secured environment variables in the same way as Azure Container Instance. For more information, see [Set environment variables in container instances](/azure/container-instances/container-instances-environment-variables#secure-values). For an example, see [Sample templates](#sample-templates). The max allowed size for environment variables is 64 KB. ## Monitor and troubleshoot deployment scripts The script service creates a [storage account](../../storage/common/storage-account-overview.md) (unless you specify an existing storage account) and a [container instance](/azure/container-instances/container-instances-overview) for script execution. If these resources are automatically created by the script service, both resources have the `azscripts` suffix in the resource names. :::image type="content" source="./media/deployment-script-template/resource-manager-template-deployment-script-resources.png" alt-text="Screenshot of Resource Manager template deployment script resource names."::: The user script, the execution results, and the stdout file are stored in the files shares of the storage account. There's a folder called `azscripts`. In the folder, there are two more folders for the input and the output files: `azscriptinput` and `azscriptoutput`. The output folder contains a _executionresult.json_ and the script output file. You can see the script execution error message in _executionresult.json_. The output file is created only when the script is executed successfully. The input folder contains a system PowerShell script file and the user deployment script files. You can replace the user deployment script file with a revised one, and rerun the deployment script from the Azure container instance. ### Use the Azure portal After you deploy a deployment script resource, the resource is listed under the resource group in the Azure portal. The following screenshot shows the **Overview** page of a deployment script resource: :::image type="content" source="./media/deployment-script-template/resource-manager-deployment-script-portal.png" alt-text="Screenshot of Resource Manager template deployment script portal overview."::: The overview page displays some important information of the resource, such as **Provisioning state**, **Storage account**, **Container instance**, and **Logs**. From the left menu, you can view the deployment script content, the arguments passed to the script, and the output. You can also export a template for the deployment script including the deployment script. ### Use PowerShell Using Azure PowerShell, you can manage deployment scripts at subscription or resource group scope: - [Get-AzDeploymentScript](/powershell/module/az.resources/get-azdeploymentscript): Gets or lists deployment scripts. - [Get-AzDeploymentScriptLog](/powershell/module/az.resources/get-azdeploymentscriptlog): Gets the log of a deployment script execution. - [Remove-AzDeploymentScript](/powershell/module/az.resources/remove-azdeploymentscript): Removes a deployment script and its associated resources. - [Save-AzDeploymentScriptLog](/powershell/module/az.resources/save-azdeploymentscriptlog): Saves the log of a deployment script execution to disk. The `Get-AzDeploymentScript` output is similar to:

replace(string(parameters('tables')), '\"', '\\\"')

Supporting script files can be called from both inline scripts and primary script files. Supporting script files have no restrictions on the file extension. The supporting files are copied to `azscripts/azscriptinput` at the runtime. Use relative path to reference the supporting files from inline scripts and primary script files. ## Work with outputs from PowerShell scripts The following template shows how to pass values between two `deploymentScripts` resources: :::code language="json" source="~/resourcemanager-templates/deployment-script/deploymentscript-basic.json" range="1-68" highlight="30-31,50"::: In the first resource, you define a variable called `$DeploymentScriptOutputs`, and use it to store the output values. To access the output value from another resource within the template, use: