Создание модульных runbook в службе автоматизации Azure

  • Статья

Рекомендуется в служба автоматизации Azure создавать повторно используемые модульные модули Runbook с дискретной функцией, вызываемой другими модулями Runbook. Родительский Runbook часто вызывает один или несколько дочерних Runbook для выполнения требуемых функций.

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

Встроенный Командлет
Задание Дочерние Runbook выполняются в том же задании, что и родительский. Для дочернего Runbook создается отдельное задание.
Выполнение Родительский модуль Runbook ожидает завершения дочернего модуля Runbook, прежде чем продолжить. Родительский модуль Runbook продолжается сразу после запуска дочернего модуля Runbook, или родительский модуль Runbook ожидает завершения дочернего задания.
Выходные данные Родительский модуль Runbook может напрямую получить выходные данные из дочернего модуля Runbook. Родительский модуль Runbook должен получить выходные данные из дочернего задания Runbook, или родительский модуль Runbook может напрямую получить выходные данные дочернего модуля Runbook.
Параметры Значения параметров дочернего Runbook указываются отдельно и могут иметь любой тип данных. Значения для параметров дочернего Runbook должны быть объединены в одну хэш-таблицу. Этот хэш-файл может включать только простые, массивные и объектные типы данных, использующие сериализацию JSON.
Учетная запись службы автоматизации. Родительский модуль Runbook может использовать только дочерний модуль Runbook в той же учетной записи службы автоматизации. Родительский модуль runbook может использовать дочерний модуль runbook из любой учетной записи службы автоматизации в той же подписке Azure и даже в другой подписке, если к ней есть подключение.
Публикация Дочерний модуль Runbook должен быть опубликован до публикации родительского модуля Runbook. Дочерний модуль Runbook публикуется в любое время до запуска родительского модуля Runbook.

Вызов дочернего модуля Runbook с помощью встроенного выполнения

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

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

При публикации Runbook все дочерние Runbook, которые он вызывает, уже должны быть опубликованы. Это связано с тем, что служба автоматизации Azure создает связь с любыми дочерними модулями runbook при компиляции модуля runbook. Если дочерние модули Runbook еще не опубликованы, родительский модуль Runbook отображается для правильной публикации, но создает исключение при запуске.

Если вы получаете исключение, можно повторно опубликовать родительский модуль Runbook, чтобы правильно ссылаться на дочерние модули Runbook. Вам не нужно повторно публиковать родительский модуль Runbook, если какой-либо дочерний модуль Runbook изменен, так как связь уже создана.

Параметры встроенного дочернего модуля runbook могут иметь любой тип данных, включая сложные объекты. Сериализация JSON отсутствует, так как при запуске модуля Runbook используется портал Azure или с помощью командлета Start-AzAutomationRunbook.

Типы Runbook

В настоящее время PowerShell 5.1 поддерживается, и только некоторые типы runbook могут вызывать друг друга:

Важно!

Выполнение дочерних скриптов .\child-runbook.ps1 не поддерживается в PowerShell 7.1 и PowerShell 7.2 . Используйте Start-AutomationRunbook (внутренний командлет) или Start-AzAutomationRunbook (из модуля Az.Automation ) для запуска другого модуля Runbook из родительского модуля Runbook.

Порядок публикации модулей Runbook имеет значение только для рабочих процессов PowerShell и графических модулей Runbook рабочих процессов PowerShell.

Когда модуль Runbook вызывает графический или дочерний модуль Runbook рабочего процесса PowerShell с помощью встроенного выполнения, он использует имя модуля Runbook. Имя должно начинаться с .\\ указания того, что скрипт находится в локальном каталоге.

Пример

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

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = PSWF-ChildRunbook -VM $vm -RepeatCount 2 -Restart $true

Ниже приведен тот же пример, но использование модуля Runbook PowerShell в качестве дочернего.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = .\PS-ChildRunbook.ps1 -VM $vm -RepeatCount 2 -Restart $true

Запуск дочернего модуля Runbook с помощью командлета

Важно!

Если модуль Runbook вызывает дочерний модуль Runbook с помощью Start-AzAutomationRunbook командлета с Wait параметром, а дочерний модуль Runbook выдает результат объекта, операция может столкнуться с ошибкой. Сведения об ошибке см. в разделе "Дочерние модули Runbook" с выходными данными объекта. В этой статье показано, как реализовать логику для опроса результатов с помощью командлета Get-AzAutomationJobOutputRecord .

Вы можете использовать Start-AzAutomationRunbook для запуска модуля Runbook, как описано в разделе "Запуск модуля Runbook с помощью Windows PowerShell". Для этого командлета используется два режима:

  • Командлет возвращает идентификатор задания при создании задания для дочернего модуля Runbook.
  • Командлет ожидает завершения дочернего задания и возвращает выходные данные дочернего модуля Runbook. Сценарий включает этот режим, указав Wait параметр.

Задание дочернего модуля runbook, запущенного с помощью командлета, выполняется отдельно от задания родительского модуля runbook. Это поведение приводит к большему число заданий, чем запуск встроенного модуля Runbook и затрудняет отслеживание заданий. Родительский модуль может запускать несколько дочерних модулей Runbook асинхронно, не ожидая завершения каждого из них. Чтобы реализовать аналогичный механизм параллельного выполнения дочерних модулей runbook при использовании встроенного вызова, в родительском модуле runbook нужно указать ключевое слово parallel.

Выходные данные дочернего модуля Runbook не возвращаются в родительский модуль Runbook надежно из-за времени. Кроме того, $VerbosePreference$WarningPreferenceи другие переменные могут не распространяться на дочерние модули Runbook. Чтобы избежать этих проблем, можно запустить дочерние модули Runbook в качестве отдельных заданий службы автоматизации с помощью Start-AzAutomationRunbookWait параметра. Этот метод блокирует родительский модуль Runbook до завершения дочернего модуля Runbook.

Если вы не хотите, чтобы родительский модуль Runbook был заблокирован при ожидании, можно запустить дочерний модуль Runbook без Start-AzAutomationRunbookWait параметра. В этом случае модуль runbook должен использовать Get-AzAutomationJob, чтобы дождаться завершения задания. Затем он с помощью командлетов Get-AzAutomationJobOutput и Get-AzAutomationJobOutputRecord получит нужные результаты.

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

Контекст подписки может быть потерян при запуске дочерних модулей Runbook в качестве отдельных заданий. Чтобы дочерний модуль runbook вызывал командлеты Az из определенной подписки Azure, он должен выполнить проверку подлинности в этой подписке независимо от родительского модуля runbook.

Если задания из одной учетной записи службы автоматизации работают с несколькими подписками, выбор подписки в одном задании может изменить текущий контекст подписки для других заданий. Чтобы избежать этой проблемы, используйте Disable-AzContextAutosave -Scope Process в начале каждого модуля runbook. Это действие сохраняет только контекст для выполнения этого модуля Runbook.

Пример

В следующем примере запускается дочерний модуль Runbook с параметрами, а затем ожидает завершения с помощью командлета с параметром Start-AzAutomationRunbookWait . После завершения дочернего модуля Runbook пример собирает выходные данные командлета из дочернего модуля Runbook. Для использования Start-AzAutomationRunbook сценарий должен выполнить проверку подлинности в подписке Azure.

# Ensure that the runbook does not inherit an AzContext
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

$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}

Start-AzAutomationRunbook `
    -AutomationAccountName 'MyAutomationAccount' `
    -Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -DefaultProfile $AzureContext `
    -Parameters $params -Wait

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

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

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