Управление сценариями предварительного и последующего выполнения

  • Статья

Сценарии предварительного и последующего выполнения представляют собой модули runbook, которые выполняются в учетной записи службы автоматизации до и после задач развертывания обновлений. Сценарии предварительного и последующего выполнения выполняются в контексте Azure, а не в локальной среде. Сценарии предварительного выполнения запускаются в начале развертывания обновлений. В Windows скрипты последующего выполнения запускаются в конце развертывания и после каждой настроенной перезагрузки. В Linux скрипты последующего выполнения запускаются после развертывания, а не после перезагрузки компьютера.

Требования к сценариям предварительного и последующего выполнения

Чтобы модуль runbook можно было использовать в качестве сценария предварительного или последующего выполнения, его необходимо импортировать в учетную запись службы автоматизации и опубликовать как runbook.

В настоящее время поддерживаются только модули Runbook PowerShell 5.1 и Python 2. Другие типы модулей runbook, такие как Python 3, графический рабочий процесс, рабочий процесс PowerShell и графический рабочий процесс PowerShell, в настоящее время не поддерживаются в качестве сценариев предварительного и последующего выполнения.

Параметры сценариев предварительного и последующего выполнения

Настроив сценарии предварительного и последующего выполнения, вы сможете передавать в них параметры, как при создании расписания для модуля runbook. Параметры определяются при создании развертывания обновлений. Сценарии предварительного и последующего выполнения поддерживают следующие типы:

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

В параметрах runbook для сценариев предварительного и последующего выполнения не поддерживаются логические значения, объекты и массивы. Наличие таких значений приводит к сбою выполнения модуля runbook.

Если вам нужен другой тип объекта, вы можете привести его к другому типу с помощью собственной логики runbook.

Помимо стандартных параметров модулей runbook, поддерживается дополнительный параметр SoftwareUpdateConfigurationRunContext (с типом строки JSON). Если этот параметр определен для сценария предварительного или последующего выполнения, в него автоматически передается значение при развертывании обновлений. Этот параметр содержит сведения о развертывании обновлений, то есть подмножество информации, возвращаемой из API SoftwareUpdateconfigurations. В следующих разделах описываются соответствующие свойства.

Свойства SoftwareUpdateConfigurationRunContext

Свойство Тип Описание
SoftwareUpdateConfigurationName Строка Имя конфигурации обновления программного обеспечения.
SoftwareUpdateConfigurationRunId GUID Уникальный идентификатор для запуска.
SoftwareUpdateConfigurationSettings Коллекция свойств, связанных с конфигурацией обновления программного обеспечения.
SoftwareUpdateConfigurationSettings.OperatingSystem Int Операционные системы, на которых будут развертываться обновления. 1 = Windows и 2 = Linux
SoftwareUpdateConfigurationSettings.Duration TimeSpan (ЧЧ:ММ:СС) Максимальная продолжительность развертывания обновлений (период обслуживания) в формате PT[n]H[n]M[n]S по стандарту ISO8601.
Например: 02:00:00.
SoftwareUpdateConfigurationSettings.WindowsConfiguration Коллекция свойств, связанных с компьютерами Windows.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.excludedKbNumbers Строка Список номеров обновлений с разделением пробелами, которые не включаются в развертывание.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.includedKbNumbers Строка Список номеров обновлений с разделением пробелами, которые включаются в развертывание обновления.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.UpdateCategories Целое 1 = "Critical";
2 = "Security"
4 = "UpdateRollUp"
8 = "FeaturePack"
16 = "ServicePack"
32 = "Definition"
64 = "Tools"
128 = "Updates"
SoftwareUpdateConfigurationSettings.WindowsConfiguration.rebootSetting Строка Параметры перезагрузки для развертывания обновлений. Поддерживаются значения IfRequired, Never, Always
SoftwareUpdateConfigurationSettings.LinuxConfiguration Коллекция свойств, связанных с компьютерами Linux.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageClassifications Целое 0 = "Unclassified"
1 = "Critical"
2 = "Security"
4 = "Other"
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageNameMasks Строка Список имен пакетов с разделением пробелами, которые включаются в развертывание обновления.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.ExcludedPackageNameMasks Строка Список имен пакетов с разделением пробелами, которые не включаются в развертывание обновления.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.RebootSetting Строка Параметры перезагрузки для развертывания обновлений. Поддерживаются значения IfRequired, Never, Always
SoftwareUpdateConfiguationSettings.AzureVirtualMachines Массив строк Список идентификаторов ресурсов для виртуальных машин Azure, включенных в развертывание обновлений.
SoftwareUpdateConfigurationSettings.NonAzureComputerNames Массив строк Список полных доменных имен компьютеров, не связанных с Azure, включенных в развертывание обновлений.

В следующем примере приведена строка JSON, передаваемая в свойство SoftwareUpdateConfigurationSettings для компьютера Linux.

"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"
 }

В следующем примере приведена строка JSON, передаваемая в свойство SoftwareUpdateConfigurationSettings для компьютера Windows.

"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"
      ]
    }
  }

Полный пример со всеми свойствами можно найти по имени: получение конфигурации обновления программного обеспечения.

Примечание.

Объект SoftwareUpdateConfigurationRunContext может содержать повторяющиеся записи для компьютеров. В этом случае сценарии предварительного и последующего выполнения будут выполнены на одном компьютере несколько раз. Если такое поведение нежелательно, используйте Sort-Object -Unique для выбора только уникальных имен виртуальных машин.

Использование сценариев предварительного и последующего выполнения в развертывании

Чтобы применить сценарий предварительного или последующего выполнения при развертывании обновлений, прежде всего создайте развертывание обновлений. Выберите Сценарии предварительного и последующего выполнения. Откроется страница Выбор сценариев предварительного и последующего выполнения.

Select scripts

Выберите сценарий, который вы хотите использовать. В нашем примере используется модуль runbook с именем UpdateManagement-TurnOnVms. При выборе модуля runbook открывается страница Настройка сценария. Выберите Сценарий предварительного выполнения и щелкните ОК.

Повторите эту процедуру для сценария UpdateManagement-TurnOffVms. Но для параметра Тип сценария выберите Сценарий последующего выполнения.

Теперь раздел Выбранные элементы отображает оба выбранных сценария. Один из них — сценарий предварительного выполнения, а второй — сценарий последующего выполнения.

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.

Взаимодействие с компьютерами

Сценарии предварительного и последующего выполнения работают как обычные модули runbook в учетной записи службы автоматизации, а не на реально развернутых компьютерах. Задачи предварительного и последующего выполнения также работают в контексте Azure и не имеют доступа к компьютерам в других средах. В следующих разделах показано, как организовать взаимодействие с компьютерами напрямую, будь то виртуальные машины Azure или компьютеры, не связанные с Azure.

Взаимодействие с компьютерами Azure

Задачи предварительного и последующего выполнения работают как модули runbook, а не в среде ОС виртуальных машин Azure в развертывании. Чтобы взаимодействовать с виртуальными машинами Azure, вам потребуется следующее:

  • Управляемое удостоверение или учетная запись запуска от имени
  • модуль runbook, который вам нужно выполнить.

Для взаимодействия с виртуальными машинами Azure следует применять командлет Invoke-AzVMRunCommand. Такое взаимодействие описано в примере модуля runbook в статье Управление обновлениями — запуск сценария командой Run.

Взаимодействие с компьютерами, не связанными с Azure

Задачи предварительного и последующего выполнения работают в контексте Azure и не имеют доступ к компьютерам в других средах. Чтобы взаимодействовать с компьютерами, не связанными с Azure, вам потребуется следующее:

  • Управляемое удостоверение или учетная запись запуска от имени
  • установленная на компьютере гибридная рабочая роль Runbook;
  • модуль Runbook, который будет запускаться локально;
  • родительский модуль runbook.

Для взаимодействия с компьютерами, не связанными с Azure, в контексте Azure выполняется родительский модуль runbook. Он вызывает дочерний модуль runbook с помощью командлета Start-AzAutomationRunbook. Ему нужно передать параметр RunOn и имя гибридной рабочей роли Runbook, которая будет выполнять сценарий. Пример такого модуля runbook см. в статье Управление обновлениями — локальный запуск сценария.

Отмена развертывания обновлений

Если сценарий предварительного выполнения возвращает ошибку, иногда нужно прервать развертывание. Для этого нужно создавать исключения в сценарии по любому поводу, который для вашего развертывания считается сбоем.

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.')

Примеры

Примеры сценариев предварительного и последующего выполнения можно найти в разделе Организация GitHub для службы автоматизации Azure и в коллекции PowerShell, либо их можно импортировать через портал Azure. Для этого в учетной записи службы автоматизации выберите в разделе Автоматизация процессов элемент Коллекция модулей runbook. В качестве фильтра укажите Управление обновлениями.

Gallery list

Также вы можете искать сценарии по именам, которые указаны в списке ниже.

  • Update Management - Turn On VMs (Управление обновлениями — включить виртуальные машины).
  • Update Management - Turn Off VMs (Управление обновлениями — выключить виртуальные машины).
  • Update Management - Run Script Locally (Управление обновлениями — локальный запуск сценария).
  • Update Management - Template for Pre/Post Scripts (Управление обновлениями — шаблон для скриптов предварительного и последующего выполнения).
  • Update Management - Run Script with Run Command (Управление обновлениями — запуск сценария командой Run).

Важно!

Чтобы воспользоваться импортированным модулем runbook, его нужно опубликовать. Для этого найдите нужный модуль 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 выполнялся с управляемым удостоверением, назначаемым системой, оставьте код как есть. Если вы предпочитаете использовать управляемое удостоверение, назначаемое пользователем, сделайте следующее:

  1. Из строки 22 удалите ,$AzureContext = (Connect-AzAccount -Identity).context
  2. Замените его $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context.
  3. Введите идентификатор клиента.

Примечание.

Для неграфических модулей runbook PowerShell Add-AzAccount и Add-AzureRMAccount являются псевдонимами для Connect-AzAccount. Вы можете использовать эти командлеты или обновить модули в учетной записи службы автоматизации до последних версий. Обновление модулей может потребоваться, даже если учетная запись службы автоматизации только что создана.

Следующие шаги

Подробнее об управлении обновлениями см. в статье Управление обновлениями и исправлениями для виртуальных машин.