How to Automate with Microsoft Azure Runbooks

Published:16 August 2022 - 12 min. read

Nicholas Xuan Nguyen Image

Nicholas Xuan Nguyen

Read more tutorials by Nicholas Xuan Nguyen!

Meet Active Directory and Windows Server auditing, security and compliance needs with ManageEngine ADAudit Plus. Download Free Trial!

Automation is crucial in the modern world of IT. Automation tools like Microsoft Azure Runbooks can help do tasks faster and more efficiently. Although the learning curve may be steep for some, especially for those new to Azure, the payoff is beneficial in the long run.

This tutorial will show you how to create and run a Microsoft Azure Runbook. You’ll also learn a typical real-world use case example of using an Azure runbook in your Azure environment.

So keep reading and learn something new today!

Prerequisites

This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have

  • An Azure account with an active subscription. If you don’t have an Azure subscription, create a free account before you begin.
  • The latest Az PowerShell module must be installed on your computer. This tutorial will use the Azure PowerShell module version 8.1.0.

Creating an Azure Runbook Using the Portal

Whether you’re a new or seasoned user, the Azure Portal is the quickest way to create Azure Runbooks. This section will teach you how to create, edit, test, publish, and execute an Azure Runbook in the Azure Portal.

Creating an Automation Account

The primary requirement of a runbook is the automation account. An automation account is a container for your automation resources, like the modules, credentials, variables, and the runbook itself.

Follow the below steps to create a new Automation account in the Azure Portal.

1. Sign in to the Azure Portal using your preferred web browser.

2. Click the Create Resource → IT & Management Tools → Automation (create).

Creating a new automation account
Creating a new automation account

3. On the Create an Automation Account page, fill out the form under the Basics tab.

Select the Subscription in which you wish to create the automation account.

Click the Create new link under the Resource group box. Type the name for the new resource group and click OK. This example automation account’s name is aa-rg-portal.

Note: Creating a new resource group is optional. Alternatively, you can select an existing resource group from the drop-down.

Selecting the subscription and creating a new resource group.
Selecting the subscription and creating a new resource group.

4. Next, enter the Automation account name and select the Region. Typically, you would choose a region that’s geographically optimal to your location. In this example, the automation account name is ata-automation-account, and the location is East US.

Click the Review+Create button once you’ve completed the details.

Configuring the automation account details
Configuring the automation account details

5. The page validates your automation account details. If you see the message Validation passed, click the Create button to initiate the automation account creation.

Reviewing and Creating the automation account
Reviewing and Creating the automation account

After the automation account deployment, you’ll see a confirmation message similar to the screenshot below.

Automation account deployment confirmation
Automation account deployment confirmation

Creating a PowerShell Runbook

You now have an automation account and can start creating an Azure Runbook in it. Follow the below steps to create a new runbook in the Azure Portal.

1. Navigate back to the Automation accounts blade and click on the name of your Automation account.

Opening the automation account page
Opening the automation account page

2. Under the Process Automation section, click Runbooks and the Create a runbook button near the top of the page.

Clicking the Create a runbook button
Clicking the Create a runbook button

3. On the Create a runbook page, fill out the runbook Name and choose the Azure Runbook type and Runtime version. This example will create a new Graphical PowerShell runbook called azure-runbook-01 based on Windows PowerShell 5.1 runtime.

The Graphical PowerShell runbook type means you are creating a PowerShell Runbook that you can only edit using the Automation graphical editor.

Refer to the Azure Automation runbook types documentation to know more about the different runbook types.

After filling out the runbook information, click Create.

Configuring and creating a new Azure runbook
Configuring and creating a new Azure runbook

The graphical editor automatically opens the runbook for editing, as you can see below. The graphical editor has three panes: Library, Canvas, and Configuration.

The Azure runbook graphical editor
The Azure runbook graphical editor

Editing the Runbook

You’ve created an empty runbook. Your next task is to edit the runbook to make it do something. In this example, you’ll modify the runbook to perform a simple logic: output the message Hello Wold using the Write-Output cmdlet.

1. First, add the Write-Output cmdlet to the canvass. Type Write-Output on the library pane’s search box to quickly do so. Once you see Write-Output under the CMDLETS tree, click the ellipsis (…) → Add to canvas.

As you can see below, the Write-Output cmdlet is now inside the canvas. At this point, the Write-Output object you see on the canvass is called an activity.

Adding a cmdlet to the canvas
Adding a cmdlet to the canvas

2. On the Configuration pane, change the activity label to Display Hello World. Next, click on Parameters.

Changing the label
Changing the label

3. On the next page, you’ll see the list of the Write-Output cmdlet parameters. In this example, click the mandatory parameter INPUTOBJECT.

Click the mandatory parameter
Click the mandatory parameter

4. Now, choose the data source for the INPUTOBJECT parameter. Select the PowerShell expression option from the Data source drop-down in this example. In the Expression box, type the “Hello World” expression (including the quotes), and click OK.

Selecting the parameter value
Selecting the parameter value

5. On the Activity Parameter Configuration, you’ll see that the INPUTOBJECT now has a checkmark indicating that you’ve already added the mandatory parameters. Click OK.

Click OK on the parameter configuration
Click OK on the parameter configuration

Testing the Runbook

You’ve created and configured a runbook, but does it work? To find out, the editor has a test pane where you can safely execute the runbook for testing.

1. Click Test Pane at the top of the canvass.

Click Test Pane at the top of the screen to open the Test Pane
Click Test Pane at the top of the screen to open the Test Pane

2. Once the Test pane is open, click Start to run the runbook.

Note: Performing a runbook testing in the test pane automatically saves the current runbook.

Running a runbook test
Running a runbook test

3. Wait for the test execution until you see the Completed message. The output pane shows the expected result: the Hello World message. Close the Test pane to go back to the editor.

Viewing the runbook test result and closing the test page.
Viewing the runbook test result and closing the test page.

4. When you’ve returned to the editor, click the Publish button → Yes, to publish this runbook version.

Publishing the runbook
Publishing the runbook

As a result, the runbook status changes to Published.

Azure Runbook status
Azure Runbook status

Creating an Azure Runbook with PowerShell

You can also create a PowerShell runbook using PowerShell. This section will show you how to create a PowerShell runbook using the Az PowerShell module cmdlets.

Creating an Automation Account

First, you must create the Automation account that will later contain your runbooks.

1. Open PowerShell with elevated privileges on your local machine.

2. Sign in to Azure PowerShell by running the following cmdlet.

Connect-AzAccount

3. If you have more than one Azure subscription, run the below command to select the correct subscription to use.

Get-AzSubscription
Select-AzSubscription 'Subscription name or ID'
Selecting the Azure subscription
Selecting the Azure subscription

4. Next, run the below command to create a resource group. This command creates a resource group with the name aa-rg-poweshell in the eastus region.

New-AzResourceGroup -Name aa-rg-powershell -Location eastus
aa-rg-poweshell in the eastus region
aa-rg-poweshell in the eastus region

5. Now that you have a resource group run the below command to create the automation account. This command creates an automation account with the name az-automation-account in the eastus region.

New-AzAutomationAccount `
    -Name 'az-automation-account' `
    -Location 'eastus' `
    -ResourceGroupName 'aa-rg-powershell'
az-automation-account
az-automation-account

Creating a PowerShell Runbook

To create a new runbook using PowerShell, the New-AzAutomationRunbook cmdlet is your go-to command. Follow these steps to create the runbook.

Copy the following code snippet and run it in PowerShell to create a new Azure runbook. This code creates a runbook of type PowerShell named az-automation-runbook in the az-automation-account automation account.

$params = @{
    AutomationAccountName = 'az-automation-account'
    Name                  = 'az-automation-runbook'
    ResourceGroupName     = 'aa-rg-powershell'
    Type                  = 'PowerShell'
}
New-AzAutomationRunbook @params
Creating a new Azure runbook in PowerShell
Creating a new Azure runbook in PowerShell

Adding Code to the Runbook

You have successfully created a PowerShell runbook with PowerShell, but it doesn’t have any code. This section will teach you how to add code to the PowerShell runbook.

1. Open your code editor and create a new file called HelloWorld.ps1.

2. Copy and paste the following code into the code editor and save the file afterward.

Write-Output -InputObject "Hello PowerShell"
HelloWorld.ps1.
HelloWorld.ps1.

3. Now, import the PowerShell code into your Azure runbook by running the Import-AzAutomationRunbook command below. The command imports the code in HelloWorld.ps1 into the az-automation-runbook runbook.

The -Force parameter overwrites the existing runbook with the same name.

Import-AzAutomationRunbook `
    -ResourceGroupName aa-rg-powershell `
    -AutomationAccountName az-automation-account `
    -Path .\HelloWorld.ps1 `
    -Type PowerShell `
    -Name az-automation-runbook `
    -Force

The below screenshot shows a successful automation runbook import.

Importing the runbook code
Importing the runbook code

Publishing the Runbook

Unlike the graphical editor in the Azure Portal, there’s no Test pane equivalent in Azure PowerShell to test your Azure runbooks. The only way to start a runbook in PowerShell is to publish it first.

To publish an Azure runbook, run the Publish-AzAutomationRunbook cmdlet, as shown below. This cmdlet publishes the az-automation-runbook runbook.

Publish-AzAutomationRunbook `
    -Name az-automation-runbook `
    -AutomationAccountName az-automation-account `
    -ResourceGroup aa-rg-powershell

As you can see below, the runbook state is now published.

Publish-AzAutomationRunbook
Publish-AzAutomationRunbook

Starting the Runbook

After you’ve successfully published the Azure runbook, run it by executing the Start-AzAutomationRunbook command below

Start-AzAutomationRunbook `
    -AutomationAccountName az-automation-account `
    -Name az-automation-runbook `
    -ResourceGroupName aa-rg-powershell `
    -Wait

Note: The -Wait switch causes the Start-AzAutomationRunbook to wait for the runbook to finish running before returning the result.

Starting the Azure runbook
Starting the Azure runbook

Automating with Azure Runbook: Stopping Azure VMs on Schedule

So far, you have created an Azure Runbook from scratch and added code to it using the Portal and PowerShell. Which method do you feel comfortable exploring?

In this example, you’ll create and configure a runbook that stops a selected Azure VM or all VMs in a resource group. But, instead of writing your own code, you’ll import an existing runbook from the Azure Runbook Gallery.

Note: This activity requires that you have at least one Azure VM running to be the target of the Azure runbook.

Importing an Azure Runbook from the Gallery

1. First, navigate to the Automation accounts blade in the Azure Portal.

2. You should see the automation accounts you previously created in the Portal and PowerShell. Click the ata-automation-account that’s in the aa-rg-portal resource group.

Open the automation account
Open the automation account

3. Click Runbooks → Browse Gallery.

Clicking Browse Gallery
Clicking Browse Gallery

4. You’ll see many runbooks in the gallery, find the one named Stop Azure V2 VMs and click it.

Click the Stop Azure V2 VMs runbook
Click the Stop Azure V2 VMs runbook

5. When the Stop Azure V2 VMs page opens, click Select.

Click Select
Click Select

6. On the Import a runbook page, enter stop-az-vm as the runbook Name. Leave all other fields intact and click Import.

Importing the runbook from the gallery
Importing the runbook from the gallery

7. The runbook opens in the graphical editor automatically. At this point, you don’t need to make any changes yet. Click Publish, Yes, to publish this runbook version.

Publishing the runbook
Publishing the runbook

8. Click the Automation account link in the breadcrumbs to return to the automation account blade.

Return to the Automation account
Return to the Automation account

Creating the ‘Run As Account’

Your runbook involves a step to connect to Azure, which means there must be an account that has access to the target Azure resources, and here is where the Azure RunAsAccount comes in.

The RunAsAccount is a service principal in Azure Active Directory (AAD) with the required permissions. The Automation service creates and maintains this account for you—but first, you must create it.

1. Click the Run as accounts blade → Azure Run As Account.

Click the Run as accounts blade
Click the Run as accounts blade

2. On the Add Azure Run As Account dialog, click Create.

Creating the Azure Run As Account
Creating the Azure Run As Account

3. Click on the new Azure Run As Account to view its properties.

Open the new Run As Account properties
Open the new Run As Account properties

As you can see below, the Run As account also created other assets or shared resources in the automation accounts, such as Connection and Certificate. The Run As account is also tied to a service principal object in Azure that has a Contributor role to the subscription.

The Azure Run As Account properties
The Azure Run As Account properties

Note: The Run As Account expires based on the certificate expiration date. Click the Renew certificate button to renew the Run As Account along.

Adding a Schedule

To fully automate the task, the task has to run unattended at a specified interval. Suppose you require VMs to stop every Friday at 17:00; adding a schedule asset will help you achieve that goal.

1. Under the Shared Resource, click Schedules → Add a schedule.

Click Add a schedule
Click Add a schedule

2. Next, configure the schedule as follows:

  • Name: Stop VMs on Fridays EOB
  • Starts: <date> <time>. This example sets the start date and time at July 15, 2022 5:00 PM.
  • Time zone: Choose the appropriate time zone.
  • Recurrence: Recurring
  • Recur every: 1 Week
  • On these days: Friday
  • Set Expiration: Yes
  • Expires: <date> <time>. Set the schedule expiration approximately one year from now.

Once you’ve completed the schedule details, click Create.

Creating a new schedule asset
Creating a new schedule asset

You’ve successfully published a schedule inside your automation account.

The published schedule asset
The published schedule asset

3. Now that you’ve created a schedule, you must link it to the runbook. To do so, open the runbook blade again by clicking on Runbooks → stop-az-vm.

Opening the runbook
Opening the runbook

4. Next, click Link to schedule on the Overview blade.

Click the Link to schedule
Click the Link to schedule

5. On the next page, click Schedule.

Click Schedule
Click Schedule

6. Click the Stop VMs on Fridays EOB schedule from the list.

Selecting the schedule
Selecting the schedule

7. Finally, click OK to finish linking the schedule to the runbook.

Linking the schedule to the runbook
Linking the schedule to the runbook

You’ve successfully linked the schedule to the runbook.

Viewing the runbook schedules
Viewing the runbook schedules

Running a Final Test

You’ve finished configuring the runbook and scheduled the job to run. But before you leave the runbook as it is, run a final test to ensure that the runbook works as expected.

1. Click Overview → Edit to open the graphical editor.

Opening the graphical editor
Opening the graphical editor

2. On the graphical editor, click the Test pane.

Test pane.
Test pane.

3. Do not change the parameters at this point and click Start. The runbook will connect to Azure and attempt to stop all running VMs inside the subscription.

To run against a specific resource group or VM, enter the resource group or VM name, or both.

As you can see below, the runbook stopped the two VMs in this Azure subscription.

Running a runbook test
Running a runbook test

4. Finally, close the test pane and the graphical editor.

Conclusion

In this article, you’ve learned how to create a Microsoft Azure Automation account and how to create runbooks using the graphical editor and PowerShell. You’ve also learned how to test your Azure Runbook to confirm that they are working as expected.

Runbooks lets you automate various tasks in Azure, such as VM creation, database backup, etc. Automation can save you time and money by automating repetitive tasks. Try creating your own runbooks to automate tasks in your Azure environment.

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!