Manage variables in Azure Automation
Variable assets are values that are available to all runbooks and DSC configurations in your Automation account. You can manage them from the Azure portal, from PowerShell, within a runbook, or in a DSC configuration.
Automation variables are useful for the following scenarios:
Sharing a value among multiple runbooks or DSC configurations.
Sharing a value among multiple jobs from the same runbook or DSC configuration.
Managing a value used by runbooks or DSC configurations from the portal or from the PowerShell command line. An example is a set of common configuration items, such as a specific list of VM names, a specific resource group, an AD domain name, and more.
Azure Automation persists variables and makes them available even if a runbook or DSC configuration fails. This behavior allows one runbook or DSC configuration to set a value that is then used by another runbook, or by the same runbook or DSC configuration the next time it runs.
Azure Automation stores each encrypted variable securely. When you create a variable, you can specify its encryption and storage by Azure Automation as a secure asset. After you create the variable, you can't change its encryption status without re-creating the variable. If you have Automation account variables storing sensitive data that are not already encrypted, then you need to delete them and recreate them as encrypted variables. A Microsoft Defender for Cloud recommendation is to encrypt all Azure Automation variables as described in Automation account variables should be encrypted. If you have unencrypted variables that you want excluded from this security recommendation, see Exempt a resource from recommendations and secure score to create an exemption rule.
Note
Secure assets in Azure Automation include credentials, certificates, connections, and encrypted variables. These assets are encrypted and stored in Azure Automation using a unique key that is generated for each Automation account. Azure Automation stores the key in the system-managed Key Vault. Before storing a secure asset, Automation loads the key from Key Vault and then uses it to encrypt the asset.
Variable types
When you create a variable with the Azure portal, you must specify a data type from the dropdown list so that the portal can display the appropriate control for entering the variable value. The following are variable types available in Azure Automation:
- String
- Integer
- DateTime
- Boolean
- Null
The variable isn't restricted to the specified data type. You must set the variable using Windows PowerShell if you want to specify a value of a different type. If you indicate Not defined, the value of the variable is set to Null. You must set the value with the Set-AzAutomationVariable cmdlet or the internal Set-AutomationVariable cmdlet. You use the Set-AutomationVariable in your runbooks that are intended to run in the Azure sandbox environment, or on a Windows Hybrid Runbook Worker.
You can't use the Azure portal to create or change the value for a complex variable type. However, you can provide a value of any type using Windows PowerShell. Complex types are retrieved as a Newtonsoft.Json.Linq.JProperty for a Complex object type instead of a PSObject type PSCustomObject.
You can store multiple values to a single variable by creating an array or hashtable and saving it to the variable.
Note
VM name variables can be a maximum of 80 characters. Resource group variables can be a maximum of 90 characters. See Naming rules and restrictions for Azure resources.
PowerShell cmdlets to access variables
The cmdlets in the following table create and manage Automation variables with PowerShell. They ship as part of the Az modules.
| Cmdlet | Description |
|---|---|
| Get-AzAutomationVariable | Retrieves the value of an existing variable. If the value is a simple type, that same type is retrieved. If it's a complex type, a PSCustomObject type is retrieved. 1 |
| New-AzAutomationVariable | Creates a new variable and sets its value. |
| Remove-AzAutomationVariable | Removes an existing variable. |
| Set-AzAutomationVariable | Sets the value for an existing variable. |
1
You can't use this cmdlet to retrieve the value of an encrypted variable. The only way to do this is by using the internal Get-AutomationVariable cmdlet in a runbook or DSC configuration. For example, to see the value of an encrypted variable, you might create a runbook to get the variable and then write it to the output stream:
$encryptvar = Get-AutomationVariable -Name TestVariable
Write-output "The encrypted value of the variable is: $encryptvar"
Internal cmdlets to access variables
The internal cmdlets in the following table are used to access variables in your runbooks and DSC configurations. These cmdlets come with the global module Orchestrator.AssetManagement.Cmdlets. For more information, see Internal cmdlets.
| Internal Cmdlet | Description |
|---|---|
Get-AutomationVariable |
Retrieves the value of an existing variable. |
Set-AutomationVariable |
Sets the value for an existing variable. |
Note
Avoid using variables in the Name parameter of Get-AutomationVariable cmdlet in a runbook or DSC configuration. Use of a variable can complicate the discovery of dependencies between runbooks and Automation variables at design time.
Python functions to access variables
The functions in the following table are used to access variables in a Python 2 and 3 runbook. Python 3 runbooks are currently in preview.
| Python Functions | Description |
|---|---|
automationassets.get_automation_variable |
Retrieves the value of an existing variable. |
automationassets.set_automation_variable |
Sets the value for an existing variable. |
Note
You must import the automationassets module at the top of your Python runbook to access the asset functions.
Create and get a variable
Note
If you want to remove the encryption for a variable, you must delete the variable and recreate it as unencrypted.
Create and get a variable using the Azure portal
- From your Automation account, on the left-hand pane select Variables under Shared Resources.
- On the Variables page, select Add a variable.
- Complete the options on the New Variable page and then select Create to save the new variable.
Note
Once you have saved an encrypted variable, it can't be viewed in the portal. It can only be updated.
Create and get a variable in Windows PowerShell
Your runbook or DSC configuration uses the New-AzAutomationVariable cmdlet to create a new variable and set its initial value. If the variable is encrypted, the call should use the Encrypted parameter. Your script can retrieve the value of the variable using Get-AzAutomationVariable.
Note
A PowerShell script can't retrieve an encrypted value. The only way to do this is to use the internal Get-AutomationVariable cmdlet.
The following example shows how to create a string variable and then return its value.
$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"
$variableValue = "My String"
New-AzAutomationVariable -ResourceGroupName "ResourceGroup01"
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable' `
-Encrypted $false -Value 'My String'
$string = (Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable').Value
The following example shows how to create a variable with a complex type and then retrieve its properties. In this case, a virtual machine object from Get-AzVM is used specifying a subset of its properties.
$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"
$vm = Get-AzVM -ResourceGroupName "ResourceGroup01" -Name "VM01" | Select Name, Location, Extensions
New-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable" -Encrypted $false -Value $vm
$vmValue = Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable"
$vmName = $vmValue.Value.Name
$vmTags = $vmValue.Value.Tags
Textual runbook examples
The following example shows how to set and retrieve a variable in a textual runbook. This example assumes the creation of integer variables named numberOfIterations and numberOfRunnings and a string variable named sampleMessage.
$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"
$numberOfIterations = Get-AutomationVariable -Name "numberOfIterations"
$numberOfRunnings = Get-AutomationVariable -Name "numberOfRunnings"
$sampleMessage = Get-AutomationVariable -Name "sampleMessage"
Write-Output "Runbook has been run $numberOfRunnings times."
for ($i = 1; $i -le $numberOfIterations; $i++) {
Write-Output "$i`: $sampleMessage"
}
Set-AutomationVariable -Name numberOfRunnings -Value ($numberOfRunnings += 1)
Graphical runbook examples
In a graphical runbook, you can add activities for the internal cmdlets Get-AutomationVariable or Set-AutomationVariable. Just right-click each variable in the Library pane of the graphical editor and select the activity that you want.
The following image shows example activities to update a variable with a simple value in a graphical runbook. In this example, the activity for Get-AzVM retrieves a single Azure virtual machine and saves the computer name to an existing Automation string variable. It doesn't matter whether the link is a pipeline or sequence since the code only expects a single object in the output.
Next steps
To learn more about the cmdlets used to access variables, see Manage modules in Azure Automation.
For general information about runbooks, see Runbook execution in Azure Automation.
For details of DSC configurations, see Azure Automation State Configuration overview.