事前スクリプトと事後スクリプトを管理する

[アーティクル]
06/01/2023

事前スクリプトと事後スクリプトは、更新プログラムのデプロイの前 (事前タスク) と後 (事後タスク) に Azure Automation アカウントで実行する Runbook です。事前スクリプトと事後スクリプトは、ローカルではなく、Azure コンテキストで実行されます。事前スクリプトは、更新プログラムのデプロイの開始時に実行されます。 Windows では、事後スクリプトはデプロイの最後で、かつ構成されているすべての再起動の後に実行されます。 Linux の場合、事後スクリプトはマシンの再起動の後ではなく、デプロイの終了後に実行されます。

事前スクリプトと事後スクリプトの要件

Runbook を事前スクリプトまたは事後スクリプトとして使用するには、Automation アカウントにインポートし、Runbook を発行する必要があります。

現在、事前/事後スクリプトとしてサポートされているのは、PowerShell 5.1 Runbook と Python 2 Runbook のみです。 Python 3、グラフィカル、PowerShell ワークフロー、グラフィカル PowerShell ワークフローなどの他の種類の Runbook は、現在、事前スクリプトまたは事後スクリプトとしてサポートされていません。

事前スクリプトと事後スクリプトのパラメーター

事前スクリプトと事後スクリプトを構成する場合、Runbook のスケジュール設定と同様にパラメーターを渡すことができます。パラメーターは、更新プログラムの展開の作成の時点で定義されます。事前スクリプトと事後スクリプトでは、次の型がサポートされます。

[char]
[byte]
[int]
[long]
[decimal]
[single]
[double]
[DateTime]
[string]

事前スクリプトと事後スクリプトの Runbook パラメーターでは、boolean、object、または array 型はサポートされません。これらの値を指定すると、Runbook は失敗します。

別のオブジェクト型が必要な場合は、Runbook 内の独自のロジックで別の方にキャストできます。

標準の Runbook パラメーターに加えて、SoftwareUpdateConfigurationRunContext パラメーター (JSON 文字列の型) が提供されます。事前スクリプトまたは事後スクリプトにパラメーターを定義すると、更新プログラムのデプロイによって自動的に渡されます。パラメーターには、SoftwareUpdateconfigurations API から返された情報のサブセットである、更新プログラムの展開に関する情報が含まれます。以下のセクションでは、関連するプロパティを定義します。

SoftwareUpdateConfigurationRunContext プロパティ

プロパティ	タイプ	説明
SoftwareUpdateConfigurationName	String	ソフトウェア更新構成の名前。
SoftwareUpdateConfigurationRunId	GUID	実行の一意の ID。
SoftwareUpdateConfigurationSettings		ソフトウェア更新構成に関連したプロパティのコレクション。
SoftwareUpdateConfigurationSettings.OperatingSystem	int	更新プログラムの展開の対象となるオペレーティングシステム。 `1` = Windows および `2` = Linux
SoftwareUpdateConfigurationSettings.Duration	Timespan (HH:MM:SS)	ISO8601 に従って `PT[n]H[n]M[n]S` として実行される更新プログラムのデプロイの最大期間。メンテナンス期間とも呼ばれる。例: 02:00:00
SoftwareUpdateConfigurationSettings.WindowsConfiguration		Windows コンピューターに関連したプロパティのコレクション。
SoftwareUpdateConfigurationSettings.WindowsConfiguration.excludedKbNumbers	String	更新プログラムの展開から除外される KB のスペース区切りの一覧。
SoftwareUpdateConfigurationSettings.WindowsConfiguration.includedKbNumbers	String	更新プログラムの展開に含まれる KB のスペース区切りの一覧。
SoftwareUpdateConfigurationSettings.WindowsConfiguration.UpdateCategories	Integer	1 = "Critical"; 2 = "Security" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definition" 64 = "Tools" 128 = "Updates"
SoftwareUpdateConfigurationSettings.WindowsConfiguration.rebootSetting	String	更新プログラムの展開のための再起動設定。値は `IfRequired`、`Never`、`Always` です
SoftwareUpdateConfigurationSettings.LinuxConfiguration		Linux コンピューターに関連したプロパティのコレクション。
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageClassifications	Integer	0 = "Unclassified" 1 = "Critical" 2 = "Security" 4 = "Other"
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageNameMasks	String	更新プログラムの展開に含まれるパッケージ名のスペース区切りの一覧。
SoftwareUpdateConfigurationSettings.LinuxConfiguration.ExcludedPackageNameMasks	String	更新プログラムの展開から除外されるパッケージ名のスペース区切りの一覧。
SoftwareUpdateConfigurationSettings.LinuxConfiguration.RebootSetting	String	更新プログラムの展開のための再起動設定。値は `IfRequired`、`Never`、`Always` です
SoftwareUpdateConfiguationSettings.AzureVirtualMachines	文字列配列	更新プログラムの展開における Azure VM 用の resourceId の一覧。
SoftwareUpdateConfigurationSettings.NonAzureComputerNames	文字列配列	更新プログラムの展開における Azure 以外のコンピューターの FQDN の一覧。

次の例は、Linux コンピューターの SoftwareUpdateConfigurationSettings プロパティに渡される JSON 文字列です。

"SoftwareUpdateConfigurationSettings": {
     "OperatingSystem": 2,
     "WindowsConfiguration": null,
     "LinuxConfiguration": {
         "IncludedPackageClassifications": 7,
         "ExcludedPackageNameMasks": "fgh xyz",
         "IncludedPackageNameMasks": "abc bin*",
         "RebootSetting": "IfRequired"
     },
     "Targets": {
         "azureQueries": null,
         "nonAzureQueries": ""
     },
     "NonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
     ],
     "AzureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resourceGroupName/providers/Microsoft.Compute/virtualMachines/vm-01"
     ],
     "Duration": "02:00:00",
     "PSComputerName": "localhost",
     "PSShowComputerName": true,
     "PSSourceJobInstanceId": "2477a37b-5262-4f4f-b636-3a70152901e9"
 }

次の例は、Windows コンピューターの SoftwareUpdateConfigurationSettings プロパティに渡される JSON 文字列です。

"SoftwareUpdateConfigurationRunContext": {
    "SoftwareUpdateConfigurationName": "sampleConfiguration",
    "SoftwareUpdateConfigurationRunId": "00000000-0000-0000-0000-000000000000",
    "SoftwareUpdateConfigurationSettings": {
      "operatingSystem": "Windows",
      "duration": "02:00:00",
      "windows": {
        "excludedKbNumbers": [
          "168934",
          "168973"
        ],
        "includedUpdateClassifications": "Critical",
        "rebootSetting": "IfRequired"
      },
      "azureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-01",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-02",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-03"
      ],
      "nonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
      ]
    }
  }

すべてのプロパティを含む完全な例については:「ソフトウェア更新プログラムの構成を名前で取得する」を参照してください。

Note

SoftwareUpdateConfigurationRunContext オブジェクトには、マシン用の重複するエントリを含めることができます。これにより、同じマシンで事前スクリプトと事後スクリプトが複数回実行される可能性があります。この動作を回避するには、Sort-Object -Unique を使用して一意の VM 名だけを選択します。

デプロイで事前スクリプトまたは事後スクリプトを使用する

更新プログラムの展開において事前スクリプトまたは事後スクリプトを使用するには、更新プログラムの展開の作成から始めます。 [事前スクリプトと事後スクリプト] を選択します。この操作で、[Select Pre-scripts + Post-scripts] (事前スクリプト + 事後スクリプトの選択) ページが開きます。

Select scripts

使用するスクリプトを選択します。この例では、UpdateManagement-TurnOnVms Runbook を使用します。 Runbook を選択すると、[スクリプトの構成] ページが開きます。 [事前スクリプト] を選択してから、[OK] を選択します。

UpdateManagement-TurnOffVms スクリプトについて、このプロセスを繰り返します。ただし、[スクリプトの種類] を選択した場合は、[事後スクリプト] を選択します。

これで、[選択された項目] セクションに、ご自身が選択した両方のスクリプトが表示されます。 1 つは事前スクリプトで、もう 1 つは事後スクリプトです。

Selected items

更新プログラムの展開の構成を終了します。

更新プログラムの展開が完了したら、[更新プログラムの展開] に移動して結果を表示できます。見てわかるように、事前スクリプトと事後スクリプトの状態が表示されます。

Update results

更新プログラムのデプロイの実行を選択すると、事前スクリプトと事後スクリプトの追加の詳細情報が表示されます。実行の時点でのスクリプトソースへのリンクが表示されます。

Deployment run results

デプロイを停止する

事前スクリプトに基づくデプロイを停止する場合は、例外をスローする必要があります。そうしないと、デプロイと事後スクリプトが引き続き実行されます。次のコードスニペットは、PowerShell を利用して例外をスローする方法を示しています。

#In this case, we want to terminate the patch job if any run fails.
#This logic might not hold for all cases - you might want to allow success as long as at least 1 run succeeds
foreach($summary in $finalStatus)
{
    if ($summary.Type -eq "Error")
    {
        #We must throw in order to fail the patch deployment.
        throw $summary.Summary
    }
}

Python 2 では、例外処理は try ブロックで管理されます。

マシンを操作する

事前スクリプトと事後スクリプトは、デプロイ内のマシンで直接実行されるのではなく、Automation アカウント内で Runbook として実行されます。事前タスクと事後タスクは Azure コンテキストでも実行され、Azure 以外のマシンにはアクセスできません。以降のセクションでは、Azure VM であるか Azure 以外のマシンであるかにかかわらず、それらのマシンと直接対話できる方法について説明します。

Azure マシンの操作

事前タスクと事後タスクは、Runbook として実行され、デプロイ内の Azure VM でネイティブに実行されることはありません。 Azure VM と対話するには、次のものが必要です。

マネージド ID または実行アカウント
実行する Runbook

Azure マシンを操作するには、Invoke-AzVMRunCommand コマンドレットを使用して、Azure VM を操作する必要があります。この方法を示した例については、「Update Management - スクリプトを実行コマンドで実行する」にある Runbook の例を参照してください。

Azure 以外のマシンの操作

事前タスクと事後タスクは Azure コンテキストで実行され、Azure 以外のマシンにはアクセスできません。 Azure 以外のマシンと対話するには、次のものが必要です。

マネージド ID または実行アカウント
コンピューターにインストールされた Hybrid Runbook Worker
ローカルで実行する Runbook
親 Runbook

Azure 以外のマシンと対話するためには、親 Runbook が Azure コンテキストで実行されます。この Runbook は、Start-AzAutomationRunbook コマンドレットを使用して子 Runbook を呼び出します。 RunOn パラメーターを指定し、スクリプトを実行する Hybrid Runbook Worker の名前を指定する必要があります。 Runbook の例「Update Management - スクリプトをローカルで実行する」を参照してください。

修正プログラムのデプロイを中止する

事前スクリプトからエラーが返されたときに、展開を中止したい場合があります。それを行うには、スクリプト内で障害を起こしているロジックのエラーをスローする必要があります。

if (<My custom error logic>)
{
    #Throw an error to fail the patch deployment.
    throw "There was an error, abort deployment"
}

Python 2 では、特定の条件が発生したときにエラーをスローする場合、raise ステートメントを使用します。

If (<My custom error logic>)
   raise Exception('Something happened.')

サンプル

事前スクリプトと事後スクリプトのサンプルは Azure Automation の GitHub 組織と PowerShell ギャラリーにあります。または、Azure portal を使用してインポートできます。 Automation アカウントで、[プロセスオートメーション] の下にある [Runbook ギャラリー] を選択することで、行うことができます。フィルターに [更新管理] を使用します。

Gallery list

または、次の一覧に示すように、スクリプト名で検索できます。

更新管理 - VM 有効
更新管理 - VM 無効
更新管理 - スクリプトをローカルで実行する
更新管理 - 事前および事後スクリプトのテンプレート
更新管理 - スクリプトを実行コマンドで実行する

重要

Runbook をインポートした後、使用できるようにするには、発行する必要があります。それを行うには、Automation アカウントで Runbook を見つけて、[編集] を選択してから [発行] を選択します。

サンプルはすべて、次の例で定義されている基本のテンプレートに基づいています。このテンプレートを使用すると、事前スクリプトと事後スクリプトで使用する独自の Runbook を作成できます。 Azure に対して認証したり、SoftwareUpdateConfigurationRunContext パラメーターを処理したりするために必要なロジックが含まれています。

<#
.SYNOPSIS
 Barebones script for Update Management Pre/Post

.DESCRIPTION
  This script is intended to be run as a part of Update Management pre/post-scripts.
  It requires the Automation account's system-assigned managed identity.

.PARAMETER SoftwareUpdateConfigurationRunContext
  This is a system variable which is automatically passed in by Update Management during a deployment.
#>

param(
    [string]$SoftwareUpdateConfigurationRunContext
)

#region BoilerplateAuthentication
# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext
#endregion BoilerplateAuthentication

#If you wish to use the run context, it must be converted from JSON
$context = ConvertFrom-Json $SoftwareUpdateConfigurationRunContext
#Access the properties of the SoftwareUpdateConfigurationRunContext
$vmIds = $context.SoftwareUpdateConfigurationSettings.AzureVirtualMachines | Sort-Object -Unique
$runId = $context.SoftwareUpdateConfigurationRunId

Write-Output $context

#Example: How to create and write to a variable using the pre-script:
<#
#Create variable named after this run so it can be retrieved
New-AzAutomationVariable -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $runId -Value "" -Encrypted $false
#Set value of variable
Set-AutomationVariable -Name $runId -Value $vmIds
#>

#Example: How to retrieve information from a variable set during the pre-script
<#
$variable = Get-AutomationVariable -Name $runId
#>

Runbook をシステム割り当てマネージド ID で実行する場合は、コードをそのままにしておきます。ユーザー割り当てマネージド ID を使用する場合は、次のようにします。

22 行目から $AzureContext = (Connect-AzAccount -Identity).context を削除し、
それを $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context に置き換えた後、
クライアント ID を入力します。