Managing Azure Automation Runtime Environments via PowerShell

Managing Azure Automation Runtime Environments via PowerShell


4 min read

You may have heard about a new (currently in preview) feature called Runtime Environment.

The main features are:

  • You can have multiple custom environments that can be used across numerous Runbooks (a.k.a. one runtime in multiple runbooks)

  • Testing of new module versions is super easy, you create a new runtime, import modules you want to test, switch to this runtime in your runbook, and see how it goes

  • Testing of the new Runtime language version is super easy

  • All of this can be automated via direct API calls

Today I will show you how to manage the whole Runtime Environment lifecycle through my PowerShell functions (module AzureResourceStuff).

Btw there is official documentation about managing Runtime Environments via API, but it lacks a lot of information, therefore I had to use web browser Developer Tools (F12) to get what I needed ๐Ÿ˜Ž

Before we begin

Enable Runtime Environments (Preview)

Open your testing Automation Account in the Azure web portal interface.

Manually switch to the new Runtime experience before you continue!

By the way, you can switch back using Switch to Old Experience button any time.

Now when switching to the new experience, you should see a new menu Runtime Environments (Preview) in your Automation Account left pane.

Now we can create new runtimes, import modules, etc manually, or using PowerShell commands as shown below.

Install AzureResourceStuff module

To be able to use my PowerShell commands, you must first install AzureResourceStuff module from the PowerShell Gallery.

Install-Module AzureResourceStuff
TIP: to get all commands related to Runtime Environment run the following command in your PowerShell console: Get-Command -Name automationRuntime -module AzureResourceStuff

Control your Runtimes via PowerShell

Now I show you a few basic actions you want to make with your Runtimes. Be sure to check functions help to get more details and examples though!

Authenticate and select the correct subscription

Before you begin, make sure you are authenticated to your Azure and that the correct subscription where your testing Automation Account is placed is selected

Import-Module Az.Accounts


Set-AzContext -Subscription "<nameOfYourSubscription>"

Get all Runtime Environments


Create a new Runtime Environment

$defaultPackage = @{
    az = '8.0.0'
New-AzureAutomationRuntime -runtimeName 'CustomPSH_7.2' -runtimeLanguage 'PowerShell' -runtimeVersion '7.2' -defaultPackage $defaultPackage

Add a custom PSH module

Custom modules are imported from PSH Gallery or as a ZIP file.

# add newest version of the 'CommonStuff' module (including all required dependencies)
New-AzureAutomationRuntimeModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

Update a custom PSH module

Custom modules are imported from PSH Gallery or as a ZIP file.

# update 'CommonStuff' module to the newest version
Update-AzureAutomationRunbookModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

# update/downgrade 'CommonStuff' module to the specified version
Update-AzureAutomationRunbookModule -moduleName 'CommonStuff' -moduleVersion '1.0.15' -runtimeName 'CustomPSH_7.2'

# update all custom modules to their newest version
Update-AzureAutomationRunbookModule -allCustomModule -runtimeName 'CustomPSH_7.2'

Remove a custom PSH module

Custom modules are imported from PSH Gallery or as a ZIP file.

Remove-AzureAutomationRuntimeModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

Set default module version

The default (built-in) modules are az, azure cli a.k.a. the ones selected from the dropdown menu.

$defaultPackage = @{
    'azure cli' = '2.56.0'

# replace existing default modules with new setting (remove 'az' completely)
Set-AzureAutomationRuntimeDefaultModule -defaultPackage $defaultPackage -runtimeName 'CustomPSH_7.2' -replace

$defaultPackage = @{
    'az'        = '8.3.0'
    'azure cli' = '2.56.0'

# replace existing default modules with new setting
Set-AzureAutomationRuntimeDefaultModule -defaultPackage $defaultPackage -runtimeName 'CustomPSH_7.2'

# remove all default modules
Set-AzureAutomationRuntimeDefaultModule -defaultPackage @{} -runtimeName 'CustomPSH_7.2'

Make Runtime Environment copy

Copy-AzureAutomationRuntime -runtimeName "CustomPSH_7.2" -newRuntimeName "CustomPSH_7.2_v2"

Invoke Runbook test run using selected Runtime

Useful if you want to automate testing of the new Runtimes a.k.a. that your Runbook will successfully end with this new Runtime (modules) version, before the final assignment.

Invoke-AzureAutomationRunbookTestJob -runtimeName "CustomPSH_7.2_v2" -runbookName "ExchangeSetAuditSettings"

Get Runbook test run output

# get the output as array of string
Get-AzureAutomationRunbookTestJobOutput -runbookName "ExchangeSetAuditSettings" -justText 'Output', 'Warning', 'Error', 'Exception'

# get the output as array of objects
Get-AzureAutomationRunbookTestJobOutput -runbookName "ExchangeSetAuditSettings"

Get Runbook test run status

# get test run status 
Get-AzureAutomationRunbookTestJobStatus -runbookName "ExchangeSetAuditSettings"

Remove Runtime Environment

Remove-AzureAutomationRuntime -runtimeName 'CustomPSH_7.2'

Did you find this article valuable?

Support Ondrej Sebela by becoming a sponsor. Any amount is appreciated!