Skip to content

Commit be39d5e

Browse files
ShawnJacksonShawnJackson
authored
Merge pull request #92119 from v-rihow/pre-post-scripts
edit pass: pre-post-scripts
2 parents 6408582 + f8f21d8 commit be39d5e

File tree

1 file changed

+43
-40
lines changed

1 file changed

+43
-40
lines changed

‎articles/automation/pre-post-scripts.md

Lines changed: 43 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Configure pre and post-scripts on your Update Management deployment in Azure
3-
description: This article describes how to configure and manage pre and post-scripts for update deployments
3+
description: This article describes how to configure and manage pre-scripts and post-scripts for update deployments.
44
services: automation
55
ms.service: automation
66
ms.subservice: update-management
@@ -12,39 +12,39 @@ manager: carmonm
1212
---
1313
# Manage pre and post-scripts
1414

15-
Pre and post-scripts let you run PowerShell runbooks in your Automation Account before (pre-task) and after (post-task) an update deployment. Pre and post-scripts run in the Azure context and not locally. Pre-scripts run at the beginning of the update deployment. Post scripts run at the end of the deployment and after any reboots that are configured.
15+
Pre-scripts and post-scripts let you run PowerShell runbooks in your Azure Automation account before (pre-task) and after (post-task) an update deployment. Pre and post-scripts run in the Azure context, not locally. Pre-scripts run at the beginning of the update deployment. Post-scripts run at the end of the deployment and after any reboots that are configured.
1616

1717
## Runbook requirements
1818

19-
For a runbook to be used as a pre or post script, the runbook needs to be imported into your automation account and published. To learn more about this process, see [Publishing a runbook](manage-runbooks.md#publish-a-runbook).
19+
For a runbook to be used as a pre or post-script, the runbook must be imported into your Automation account and published. To learn more about this process, see [Publish a runbook](manage-runbooks.md#publish-a-runbook).
2020

21-
## Using a pre/post script
21+
## Using a pre-script or post-script
2222

23-
To use a pre and or post script in an Update Deployment, start by creating an Update Deployment. Select **Pre-scripts + Post Scripts**. This action opens the **Select Pre-scripts + Post-scripts** page.
23+
To use a pre-script or post-script in an update deployment, start by creating an update deployment. Select **Pre-scripts + Post-Scripts**. This action opens the **Select Pre-scripts + Post-scripts** page.
2424

2525
![Select scripts](./media/pre-post-scripts/select-scripts.png)
2626

27-
Select the script you want to use, in this example, you used the **UpdateManagement-TurnOnVms** runbook. When you select the runbook the **Configure Script** page opens, choose **Pre-Script**. Click **OK** when done.
27+
Select the script you want to use. In this example, we use the **UpdateManagement-TurnOnVms** runbook. When you select the runbook, the **Configure Script** page opens. Select **Pre-Script**, and then select **OK**.
2828

29-
Repeat this process for the **UpdateManagement-TurnOffVms** script. But when choosing the **Script type**, choose **Post-Script**.
29+
Repeat this process for the **UpdateManagement-TurnOffVms** script. But when you choose the **Script type**, select **Post-Script**.
3030

31-
The **Selected items** section now shows both your scripts selected and on is a pre-script and the other is a post-script.
31+
The **Selected items** section now shows both your scripts selected. One is a pre-script and the other is a post-script:
3232

3333
![Selected items](./media/pre-post-scripts/selected-items.png)
3434

35-
Finish configuring your Update Deployment.
35+
Finish configuring your update deployment.
3636

37-
When your Update Deployment is complete, you can go to **Update deployments** to view the results. As you can see, the status of the pre-script and post-script are provided.
37+
When your update deployment is complete, you can go to **Update deployments** to view the results. As you can see, the status is provided for the pre-script and post-script:
3838

3939
![Update results](./media/pre-post-scripts/update-results.png)
4040

41-
By clicking into the update deployment run, you're provided additional details to the pre and post-scripts. A link to the script source at the time of the run is provided.
41+
By selecting the update deployment run, you're shown additional details to the pre and post-scripts. A link to the script source at the time of the run is provided.
4242

4343
![Deployment run results](./media/pre-post-scripts/deployment-run.png)
4444

4545
## Passing parameters
4646

47-
When you configure pre and post-scripts, you can pass in parameters just like scheduling a runbook. Parameters are defined at the time of update deployment creation. Pre and Post-scripts support the following types:
47+
When you configure pre and post-scripts, you can pass in parameters just like scheduling a runbook. Parameters are defined at the time of update deployment creation. Pre and post-scripts support the following types:
4848

4949
* [char]
5050
* [byte]
@@ -58,24 +58,27 @@ When you configure pre and post-scripts, you can pass in parameters just like sc
5858

5959
If you need another object type, you can cast it to another type with your own logic in the runbook.
6060

61-
In addition to your standard runbook parameters, an additional parameter is provided. This parameter is **SoftwareUpdateConfigurationRunContext**. This parameter is a JSON string, and if you define the parameter in your pre or post script, it's automatically passed in by the update deployment. The parameter contains information about the update deployment, which is a subset of information returned by the [SoftwareUpdateconfigurations API](/rest/api/automation/softwareupdateconfigurations/getbyname#updateconfiguration) The following table shows you the properties that are provided in the variable:
61+
In addition to your standard runbook parameters, another parameter is provided: **SoftwareUpdateConfigurationRunContext**
6262

63+
This parameter is a JSON string, and if you define the parameter in your pre or post-script, it's automatically passed in by the update deployment. The parameter contains information about the update deployment, which is a subset of information returned by the [SoftwareUpdateconfigurations API](/rest/api/automation/softwareupdateconfigurations/getbyname#updateconfiguration).
64+
65+
The following table shows you the properties that are provided in the variable.
6366

6467
### SoftwareUpdateConfigurationRunContext properties
6568

6669
|Property |Description |
6770
|---------|---------|
68-
|SoftwareUpdateConfigurationName | The name of the Software Update Configuration |
71+
|SoftwareUpdateConfigurationName | The name of the software update configuration. |
6972
|SoftwareUpdateConfigurationRunId | The unique ID for the run. |
70-
|SoftwareUpdateConfigurationSettings | A collection of properties related to the Software Update Configuration |
71-
|SoftwareUpdateConfigurationSettings.operatingSystem | The operating systems targeted for the update deployment |
72-
|SoftwareUpdateConfigurationSettings.duration | The maximum duration of the update deployment run as `PT[n]H[n]M[n]S` as per ISO8601, also called the "maintenance window" |
73-
|SoftwareUpdateConfigurationSettings.Windows | A collection of properties related to Windows computers |
74-
|SoftwareUpdateConfigurationSettings.Windows.excludedKbNumbers | A list of KBs that are excluded from the update deployment |
75-
|SoftwareUpdateConfigurationSettings.Windows.includedUpdateClassifications | Update classifications selected for the update deployment |
76-
|SoftwareUpdateConfigurationSettings.Windows.rebootSetting | Reboot settings for the update deployment |
77-
|azureVirtualMachines | A list of resourceIds for the Azure VMs in the update deployment |
78-
|nonAzureComputerNames|A list of the Non-Azure computers FQDNs in the update deployment|
73+
|SoftwareUpdateConfigurationSettings | A collection of properties related to the software update configuration. |
74+
|SoftwareUpdateConfigurationSettings.operatingSystem | The operating systems targeted for the update deployment. |
75+
|SoftwareUpdateConfigurationSettings.duration | The maximum duration of the update deployment run as `PT[n]H[n]M[n]S` as per ISO8601; also called the *maintenance window*. |
76+
|SoftwareUpdateConfigurationSettings.Windows | A collection of properties related to Windows computers. |
77+
|SoftwareUpdateConfigurationSettings.Windows.excludedKbNumbers | A list of KBs that are excluded from the update deployment. |
78+
|SoftwareUpdateConfigurationSettings.Windows.includedUpdateClassifications | Update classifications selected for the update deployment. |
79+
|SoftwareUpdateConfigurationSettings.Windows.rebootSetting | Reboot settings for the update deployment. |
80+
|azureVirtualMachines | A list of resourceIds for the Azure VMs in the update deployment. |
81+
|nonAzureComputerNames|A list of the non-Azure computers FQDNs in the update deployment.|
7982

8083
The following example is a JSON string passed in to the **SoftwareUpdateConfigurationRunContext** parameter:
8184

@@ -107,15 +110,15 @@ The following example is a JSON string passed in to the **SoftwareUpdateConfigur
107110
   }
108111
```
109112

110-
A full example with all properties can be found at: [Software Update Configurations - Get By Name](/rest/api/automation/softwareupdateconfigurations/getbyname#examples)
113+
A full example with all properties can be found at: [Get software update configuration by name](/rest/api/automation/softwareupdateconfigurations/getbyname#examples).
111114

112115
> [!NOTE]
113-
> The `SoftwareUpdateConfigurationRunContext` object can contain duplicate entries for machines. This can cause Pre and Post scripts to run multiple times on the same machine. To workaround this behavior, use `Sort-Object -Unique` to select only unique VM names in your script.
116+
> The `SoftwareUpdateConfigurationRunContext` object can contain duplicate entries for machines. This can cause pre and post-scripts to run multiple times on the same machine. To work around this behavior, use `Sort-Object -Unique` to select only unique VM names in your script.
114117
115118

116119
## Stopping a deployment
117120

118-
If you want to stop a deployment based on a pre-script, you must [throw](automation-runbook-execution.md#throw) an exception. If you don't throw an exception, the deployment and Post script will still run. The code snippet below shows how to throw an exception.
121+
If you want to stop a deployment based on a pre-script, you must [throw](automation-runbook-execution.md#throw) an exception. If you don't, the deployment and post-script will still run. The following code snippet shows how to throw an exception.
119122

120123
```powershell
121124
#In this case, we want to terminate the patch job if any run fails.
@@ -132,11 +135,11 @@ foreach($summary in $finalStatus)
132135

133136
## Samples
134137

135-
Samples for pre and post-scripts can be found in the [Script Center Gallery](https://gallery.technet.microsoft.com/scriptcenter/site/search?f%5B0%5D.Type=RootCategory&f%5B0%5D.Value=WindowsAzure&f%5B0%5D.Text=Windows%20Azure&f%5B1%5D.Type=SubCategory&f%5B1%5D.Value=WindowsAzure_automation&f%5B1%5D.Text=Automation&f%5B2%5D.Type=SearchText&f%5B2%5D.Value=update%20management&f%5B3%5D.Type=Tag&f%5B3%5D.Value=Patching&f%5B3%5D.Text=Patching&f%5B4%5D.Type=ProgrammingLanguage&f%5B4%5D.Value=PowerShell&f%5B4%5D.Text=PowerShell), [PowerShell Gallery](https://www.powershellgallery.com/packages?q=Tags%3A%22UpdateManagement%22+Tags%3A%22Automation%22), or imported through the Azure portal. To import them through the portal, in your Automation Account, under **Process Automation**, select **Runbooks Gallery**. Use **Update Management** for the filter.
138+
Samples for pre and post-scripts can be found in the [Script Center Gallery](https://gallery.technet.microsoft.com/scriptcenter/site/search?f%5B0%5D.Type=RootCategory&f%5B0%5D.Value=WindowsAzure&f%5B0%5D.Text=Windows%20Azure&f%5B1%5D.Type=SubCategory&f%5B1%5D.Value=WindowsAzure_automation&f%5B1%5D.Text=Automation&f%5B2%5D.Type=SearchText&f%5B2%5D.Value=update%20management&f%5B3%5D.Type=Tag&f%5B3%5D.Value=Patching&f%5B3%5D.Text=Patching&f%5B4%5D.Type=ProgrammingLanguage&f%5B4%5D.Value=PowerShell&f%5B4%5D.Text=PowerShell) and the [PowerShell Gallery](https://www.powershellgallery.com/packages?q=Tags%3A%22UpdateManagement%22+Tags%3A%22Automation%22), or you can import them through the Azure portal. To do that, in your Automation account, under **Process Automation**, select **Runbooks Gallery**. Use **Update Management** for the filter.
136139

137140
![Gallery list](./media/pre-post-scripts/runbook-gallery.png)
138141

139-
Or you can search for them by their script name as seen in the following list:
142+
Or you can search for them by their script name, as shown in the following list:
140143

141144
* Update Management - Turn On VMs
142145
* Update Management - Turn Off VMs
@@ -145,17 +148,17 @@ Or you can search for them by their script name as seen in the following list:
145148
* Update Management - Run Script with Run Command
146149

147150
> [!IMPORTANT]
148-
> After you import the runbooks, you must **Publish** them before they can be used. To do that find the runbook in your Automation Account, select **Edit**, and click **Publish**.
151+
> After you import the runbooks, you must publish them before they can be used. To do that, find the runbook in your Automation account, select **Edit**, and then select **Publish**.
149152
150-
The samples are all based on the basic template that is defined in the following example. This template can be used to create your own runbook to use with pre and post-scripts. The necessary logic for authenticating with Azure and handling the `SoftwareUpdateConfigurationRunContext` parameter are included.
153+
The samples are all based on the basic template that's defined in the following example. This template can be used to create your own runbook to use with pre and post-scripts. The necessary logic for authenticating with Azure and handling the `SoftwareUpdateConfigurationRunContext` parameter is included.
151154

152155
```powershell
153156
<#
154157
.SYNOPSIS
155158
Barebones script for Update Management Pre/Post
156159
157160
.DESCRIPTION
158-
This script is intended to be run as a part of Update Management Pre/Post scripts.
161+
This script is intended to be run as a part of Update Management pre/post-scripts.
159162
It requires a RunAs account.
160163
161164
.PARAMETER SoftwareUpdateConfigurationRunContext
@@ -202,7 +205,7 @@ $variable = Get-AutomationVariable -Name $runId
202205

203206
## Interacting with machines
204207

205-
Pre and post-tasks run as a runbook in your Automation Account and not directly on the machines in your deployment. Pre and post-tasks also run in the Azure context and don't have access to Non-Azure machines. The following sections show how you can interact with the machines directly whether they're an Azure VM or a Non-Azure machine:
208+
Pre and post-tasks run as a runbook in your Automation account and not directly on the machines in your deployment. Pre and post-tasks also run in the Azure context and don't have access to non-Azure machines. The following sections show how you can interact with the machines directly, whether they're Azure VMs or non-Azure machines.
206209

207210
### Interacting with Azure machines
208211

@@ -211,22 +214,22 @@ Pre and post-tasks are run as runbooks and don't natively run on your Azure VMs
211214
* A Run As account
212215
* A runbook you want to run
213216

214-
To interact with Azure machines, you should use the [Invoke-AzureRmVMRunCommand](/powershell/module/azurerm.compute/invoke-azurermvmruncommand) cmdlet to interact with your Azure VMs. For an example of how to do this, see the runbook example [Update Management - Run Script with Run Command](https://gallery.technet.microsoft.com/Update-Management-Run-40f470dc).
217+
To interact with Azure machines, you should use the [Invoke-AzureRmVMRunCommand](/powershell/module/azurerm.compute/invoke-azurermvmruncommand) cmdlet to interact with your Azure VMs. For an example of how to do this, see the runbook example [Update Management – run script with Run command](https://gallery.technet.microsoft.com/Update-Management-Run-40f470dc).
215218

216-
### Interacting with Non-Azure machines
219+
### Interacting with non-Azure machines
217220

218-
Pre and post-tasks run in the Azure context and don't have access to Non-Azure machines. To interact with the Non-Azure machines, you must have the following items:
221+
Pre and post-tasks run in the Azure context and don't have access to non-Azure machines. To interact with the non-Azure machines, you must have the following items:
219222

220223
* A Run As account
221224
* Hybrid Runbook Worker installed on the machine
222225
* A runbook you want to run locally
223-
* Parent runbook
226+
* A parent runbook
224227

225-
To interact with Non-Azure machines, a parent runbook is run in the Azure context. This runbook calls a child runbook with the [Start-AzureRmAutomationRunbook](/powershell/module/azurerm.automation/start-azurermautomationrunbook) cmdlet. You must specify the `-RunOn` parameter and provide the name of the Hybrid Runbook Worker for the script to run on. For an example, see the runbook example [Update Management - Run Script Locally](https://gallery.technet.microsoft.com/Update-Management-Run-6949cc44).
228+
To interact with non-Azure machines, a parent runbook is run in the Azure context. This runbook calls a child runbook with the [Start-AzureRmAutomationRunbook](/powershell/module/azurerm.automation/start-azurermautomationrunbook) cmdlet. You must specify the `-RunOn` parameter and provide the name of the Hybrid Runbook Worker for the script to run on. For more info, see the runbook example [Update Management – run script locally](https://gallery.technet.microsoft.com/Update-Management-Run-6949cc44).
226229

227230
## Abort patch deployment
228231

229-
If your pre script returns an error, you may want to abort your deployment. To do this, you must [throw](/powershell/module/microsoft.powershell.core/about/about_throw) an error in your script for any logic that would constitute a failure.
232+
If your pre-script returns an error, you might want to abort your deployment. To do that, you must [throw](/powershell/module/microsoft.powershell.core/about/about_throw) an error in your script for any logic that would constitute a failure.
230233

231234
```powershell
232235
if (<My custom error logic>)
@@ -238,11 +241,11 @@ if (<My custom error logic>)
238241

239242
## Known issues
240243

241-
* You can't pass a boolean, objects, or arrays to parameters when using pre and post-scripts. The runbook will fail. For a complete list of supported types, see [parameters](#passing-parameters).
244+
* You can't pass a boolean, objects, or arrays to parameters when you're using pre and post-scripts. If you do, the runbook fails. For a complete list of supported types, see [Passing parameters](#passing-parameters).
242245

243246
## Next steps
244247

245-
Continue to the tutorial to learn how to manage updates for your Windows virtual machines.
248+
Go on to the following tutorial to learn how to manage updates for your Windows virtual machines:
246249

247250
> [!div class="nextstepaction"]
248251
> [Manage updates and patches for your Azure Windows VMs](automation-tutorial-update-management.md)

0 commit comments

Comments
 (0)