# Managing Azure Automation Runtime Environments via PowerShell

You may have heard about a new (currently in preview) feature called [Runtime Environment](https://learn.microsoft.com/en-us/azure/automation/runtime-environment-overview).

The main features are:

* You can have multiple custom runtime 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 including modules management through my PowerShell module** [**AzureResourceStuff**](https://www.powershellgallery.com/packages/AzureResourceStuff)**.**

By the way, there is [official documentation](https://learn.microsoft.com/en-us/azure/automation/manage-runtime-environment?tabs=create-runtime-rest%2Clist-runtime-portal%2Cdelete-runtime-portal%2Cupdate-runtime-rest%2Ccreate-runbook-portal%2Cupdate-runbook-portal%2Ctest-update-api%2Ccreate-cloud-job-portal) 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 in most cases 😎

---

# 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](https://learn.microsoft.com/en-us/azure/automation/runtime-environment-overview#switch-between-new-and-old-experience) before you continue!

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1718176572854/b6fd9480-ce9f-4e5d-b123-19792d274fc7.png align="center")

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1718176443948/0585b6c3-9645-4a68-a46b-04a8c7721870.png align="center")

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

## Install AzureResourceStuff module

To be able to use my PowerShell commands, you must first install [AzureResourceStuff](https://www.powershellgallery.com/packages/AzureResourceStuff) module from the PowerShell Gallery.

```powershell
Install-Module AzureResourceStuff
```

<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text">TIP: to get all commands related to Runtime Environment run the following command in your PowerShell console: <code>Get-Command -Name *automationRuntime* -module AzureResourceStuff</code></div>
</div>

---

# Runtime environment functions

Now I show you a few basic actions you want to make with your Runtimes. Be sure to check functions help (via `Get-Help`) to get more details and examples though!

<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text">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</div>
</div>

```powershell
Import-Module Az.Accounts

Connect-AzAccount

Set-AzContext -Subscription "<nameOfYourSubscription>"
```

### Get all Runtime Environments

```powershell
Get-AzureAutomationRuntime
```

### Create a new Runtime Environment

```powershell
$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 a ZIP file.

```powershell
# import newest version of the 'CommonStuff' module (including all required dependencies) from the PowerShell Gallery
New-AzureAutomationRuntimeModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

# import module archived in the selected zip file
New-AzureAutomationRuntimeZIPModule -moduleZIPPath "C:\DATA\helperFunctions.zip" -runtimeName 'CustomPSH_7.2'
```

### Update a custom PSH module

```powershell
# 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'

# replace existing module with the one saved in selected zip file
New-AzureAutomationRuntimeZIPModule -moduleZIPPath "C:\DATA\helperFunctionsv2.zip" -runtimeName 'CustomPSH_7.2'
```

### Remove a custom PSH module

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

### Get available default modules

Default modules are pre-built into every runtime. You select whether you want to use it (and which version) or don’t want to use it at all.

```powershell
Get-AzureAutomationRuntimeAvailableDefaultModule
```

### Set default module version

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

```powershell
$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'
```

### Get Runtime selected default modules

```powershell
Get-AzureAutomationRuntimeSelectedDefaultModule
```

### Make Runtime Environment copy

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

### Remove Runtime Environment

```powershell
Remove-AzureAutomationRuntime -runtimeName 'CustomPSH_7.2'
```

---

# Runbook functions

Here are some of the functions related to Runbooks

### Get Runbook script content

```powershell
Get-AzureAutomationRunbookContent -runbookName someRunbook -ResourceGroupName Automations -AutomationAccountName someAutomationAccount
```

### Set Runbook script content

```powershell
$content = @'
   Get-process notepad
   restart-service spooler
'@

Set-AzureAutomationRunbookContent -runbookName someRunbook -ResourceGroupName Automations -AutomationAccountName someAutomationAccount -content $content
```

### Get Runtime used in selected Runbook

```powershell
Get-AzureAutomationRunbookRuntime
```

### Set Runbook Runtime

```powershell
Set-AzureAutomationRunbookRuntime
```

### Set Runbook description

```powershell
Set-AzureAutomationRuntimeDescription
```

### Start 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.

```powershell
Start-AzureAutomationRunbookTestJob -runtimeName "CustomPSH_7.2_v2" -runbookName "ExchangeSetAuditSettings"
```

### Stop Runbook test run

```powershell
Stop-AzureAutomationRunbookTestJob
```

### Get Runbook test run output

```powershell
# 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

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