Администрирование модулей в службе автоматизации Azure

Служба автоматизации Azure использует несколько модулей PowerShell для включения командлетов в последовательностях runbook и ресурсов DSC в конфигурациях DSC. Поддерживаются следующие модули:

• Модули Azure PowerShell Az.
• другие модули PowerShell;
• Внутренний Orchestrator.AssetManagement.Cmdlets модуль (недоступен в гибридном рабочем Runbook для Linux).
• Модули Python 2 и Python 3.
• созданные вами пользовательские модули.

При создании учетной записи службы автоматизации Azure эта служба по умолчанию импортирует ряд модулей. См. раздел Стандартные модули.

Песочницы

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

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

Из-за количества модулей и командлетов трудно заранее определить, какие командлеты выполнят неподдерживаемые вызовы. Обычно возникают проблемы с командлетами, требующими повышенного доступа и учетных данных в качестве параметра, или с командлетами, связанными с сетью. В песочнице не поддерживаются командлеты, выполняющие сетевые операции полного стека, включая Connect-AipService из модуля AIPService PowerShell и Resolve-DnsName из модуля DNSClient.

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

Стандартные модули

Все новые учетные записи службы автоматизации имеют последнюю версию модуля PowerShell Az, импортированного по умолчанию. Модуль Az заменяет AzureRM и рекомендуется использовать модуль с Azure. Модуль по умолчанию в новой учетной записи автоматизации включает существующие 24 модуля AzureRM и более 60 модулей Az.

Существует собственный вариант обновления модулей до последнего модуля Az пользователем для учетных записей службы автоматизации. Эта операция будет обрабатывать все зависимости модуля на серверной стороне, убирая сложности ручного обновления модулей или выполнения рутинной процедуры для обновления модулей Azure.

Если у существующей учетной записи службы автоматизации есть только модули AzureRM, параметр Update Az modules обновит учетную запись службы автоматизации с выбранной пользователем версией модуля Az.

Если у существующей учетной записи службы автоматизации есть AzureRM и некоторые модули Az, параметр импортирует оставшиеся модули Az в учетную запись службы автоматизации. Существующие модули Az будут иметь приоритет, и операция обновления не затронет эти модули. Это позволяет гарантировать, что операция модуля обновления не приводит к сбою выполнения модуля Runbook, непреднамеренно обновляя модуль, используемый модулем Runbook. Рекомендуется сначала удалить существующие модули Az, а затем выполнить операции обновления, чтобы получить последний модуль Az, импортированный в учетную запись службы автоматизации. Такие типы модулей, не импортированные по умолчанию, называются пользовательскими. Пользовательские модули всегда имеют приоритет над модулями по умолчанию.

Например, если у вас уже есть Az.Aks модуль, импортированный с версией 2.3.0, предоставленной модулем Az 6.3.0, и вы пытаетесь обновить модуль Az до последней версии 6.4.0. Операция обновления импортирует все модули Az из пакета 6.4.0, кроме Az.Aks. Чтобы получить последнюю версию Az.Aks, сначала удалите существующий модуль, а затем выполните операцию обновления или также можно обновить этот модуль отдельно, как описано в разделе Import Az modules , чтобы импортировать другую версию конкретного модуля.

В следующей таблице перечислены модули, которые Azure Automation импортирует по умолчанию при создании учетной записи автоматизации. Служба автоматизации может импортировать более новые версии этих модулей. Однако вы не сможете удалить исходную версию из учетной записи службы автоматизации, даже если удалите более новую версию.

Модули по умолчанию также называются глобальными модулями. На портале Azure свойство Global Module будет иметь значение true, если просматривается модуль, который был импортирован при создании учетной записи.

Внутренние командлеты

Служба автоматизации Azure предоставляет внутренние командлеты, которые доступны исключительно при выполнении модулей Runbook в среде песочницы Azure или гибридной рабочей роли Runbook Windows. Модуль Orchestrator.AssetManagement.Cmdlets, содержащий эти внутренние командлеты, устанавливается по умолчанию в учетной записи Автоматизации, в частности, когда роль гибридного рабочего процесса Runbook устанавливается на компьютере с Windows.

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

Обратите внимание, что именование внутренних командлетов отличается от командлетов Az и AzureRM. Имена внутренних командлетов не содержат такие слова, как Azure или Az, но используют слово Automation. Рекомендуем использовать их вместо командлетов Az или AzureRM во время выполнения плана операций в песочнице Azure или на гибридном рабочем узле Runbook в Windows, так как они требуют меньше параметров и запускаются в контексте задания во время выполнения.

Следует использовать командлеты Az и AzureRM для манипуляций с ресурсами автоматизации вне контекста рабочего процесса runbook.

Модули Python

В службе автоматизации Azure можно создавать ранбуки для Python 2. Сведения о модуле Python см. в статье Управление пакетами Python 2 в службе автоматизации Azure.

Пользовательские модули

Служба автоматизации Azure поддерживает пользовательские модули PowerShell, которые вы создаете для использования с вашими runbooks и конфигурациями DSC. Один из типов пользовательских модулей — модуль интеграции, который дополнительно содержит файл метаданных для определения пользовательской функциональности его командлетов. Пример использования модуля интеграции приведен в разделе Добавление типа подключения.

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

Перейдите на модули Az

Этот раздел объясняет, как выполнить миграцию на модули Az в Автоматизации. Дополнительные сведения см. в статье Перенос Azure PowerShell с AzureRM на Az.

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

Тестируйте runbooks и конфигурации DSC перед миграцией модулей

Перед миграцией на модули Az тщательно протестируйте все runbook и конфигурации DSC в отдельной учетной записи службы автоматизации.

Остановите и отмените запланированное выполнение всех runbooks, использующих модули AzureRM

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

Когда вы будете готовы удалить расписания, вы можете использовать либо портал Azure, либо командлет Remove-AzAutomationSchedule. См. раздел Удаление расписания.

Удаление модулей AzureRM

Перед импортом модулей Az можно удалить модули AzureRM. Однако в этом случае синхронизация системы управления исходным кодом может прерваться, что приведет к сбою всех скриптов, выполнение которых еще запланировано. Если вы решили удалить эти модули, ознакомьтесь с разделом Удаление AzureRM.

Импорт модулей Az

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

• Если Runbook вызывает Cmdlet из модуля;
• если runbook импортирует модуль явным образом с помощью командлета Import-Module;
• Если runbook импортирует модуль явным образом с помощью инструкции использование модуля. Инструкция using работает в версиях, начиная с Windows PowerShell 5.0, и поддерживает импорт классов и типов перечисления.
• Когда runbook импортирует другой зависимый модуль.

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

• Просмотр галереи доступен на панели автоматизации процессов>Модули.
• На странице "Модули" отображаются два новых столбца : версия модуля и версия среды выполнения

1. Войдите на портал Azure.

2. Найдите и выберите раздел Учетные записи службы автоматизации.

3. На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.

4. В учетной записи службы автоматизации в области Общие ресурсы выберите Модули.

5. Выберите Добавить модуль. На странице Добавление модуля можно выбрать один из следующих параметров:

   1. Найдите файл — выбирает файл на локальном компьютере.
   2. Выберите из галереи - вы можете просматривать и выбирать существующий модуль из галереи.

6. Нажмите Выбрать, чтобы выбрать модуль.

7. Выберите Версия среды выполнения и нажмите Импорт.

   

8. На странице Модули можно просмотреть импортированный модуль в учетной записи службы автоматизации.

Этот процесс импорта можно также выполнить с помощью коллекции PowerShell, выполнив поиск импортируемого модуля. Когда вы найдете модуль, выберите его и перейдите на вкладку Azure Automation. Выберите Развернуть в Azure Automation.

Тестирование модулей runbook

После того как вы импортировали модули Az в учетную запись службы автоматизации, можно начать редактирование ваших runbooks и конфигураций DSC, чтобы использовать новые модули. Один из способов тестирования изменений в runbook, чтобы использовать новые командлеты, — это воспользоваться командой Enable-AzureRmAlias -Scope Process в начале runbook. Если добавить эту команду в модуль runbook, скрипт может выполняться без изменений.

Авторские модули

При создании пользовательского модуля PowerShell для использования в службе автоматизации Azure рекомендуем следовать рекомендациям, приведенным в данном разделе. Чтобы подготовить модуль к импорту, необходимо создать по крайней мере DLL-файл модуля psd1, psm1 или PowerShell с тем же именем, что и у папки модуля. Затем заархивируйте папку модуля, чтобы служба автоматизации Azure могла импортировать ее как один файл. Пакет ZIP должен иметь то же имя, что и вложенная папка модуля.

Дополнительные сведения о создании модуля PowerShell см. в статье Как написать модуль сценария PowerShell.

Папка версии

Параллельное управление версиями модулей PowerShell позволяет использовать в PowerShell несколько версий модуля. Это может быть полезно, если у вас есть более старые сценарии, которые были протестированы и работали только с определенной версией модуля PowerShell, но для других сценариев требуется более новая версия того же модуля PowerShell.

Чтобы создать модули PowerShell, которые содержат несколько версий, создайте папку модуля, а затем создайте в ней папки для каждой версии модуля, которую нужно использовать. В следующем примере модуль с названием TestModule предоставляет две версии: 1.0.0 и 2.0.0.

TestModule
   1.0.0
   2.0.0

В каждую из папок версий скопируйте файлы .dll, .psm1 или .psd1 вашего модуля PowerShell в соответствующую папку. Затем заархивируйте папку модуля, чтобы служба автоматизации Azure могла импортировать ее как один ZIP-файл. Хотя служба автоматизации отображает только одну из версий импортированного модуля, если пакет модуля содержит параллельные версии модуля, они доступны для использования в конфигурациях Runbook или DSC.

Хотя служба автоматизации поддерживает модули, содержащие параллельные версии в одном пакете, она не поддерживает использование нескольких версий модуля в рамках импорта пакетов модулей. Например, вы импортируете модуль A, который содержит версии 1 и 2, в учетную запись службы автоматизации. После обновления модуля A для включения версий 3 и 4 при импорте в учетную запись службы автоматизации можно использовать только версии 3 и 4 в любых конфигурациях Runbook или DSC. Если нужны все версии (1, 2, 3 и 4), ZIP-файл для импорта должен содержать их.

Если вы планируете использовать разные версии одного и того же модуля в разных сценариях, всегда указывайте версию, которую вы собираетесь использовать, с помощью командлета Import-Module и добавьте параметр -RequiredVersion <version>. Это актуально даже в том случае, если вы хотите использовать последнюю версию. Это связано с тем, что задания runbook могут выполняться в одной и той же изолированной среде. Если в песочнице уже был явно загружен модуль определенной версии по указанию предыдущего задания, будущие задания не будут автоматически загружать последнюю версию этого модуля. Это связано с тем, что в песочнице уже загружена определенная версия.

Чтобы указать конкретную версию ресурса DSC, используйте следующую команду:

Import-DscResource -ModuleName "<ModuleName>" -ModuleVersion "<version>"

Справочная информация

Добавьте краткие сведения, описание и ссылку на справочную информацию (URI) в каждый командлет вашего модуля. В PowerShell справочную информацию для командлетов можно определить с помощью командлета Get-Help. В следующем примере показано, как определить синопсис и URI справки в файле модуля .psm1.

<#
     .SYNOPSIS
      Gets a Contoso User account
#>
function Get-ContosoUser {
[CmdletBinding](DefaultParameterSetName='UseConnectionObject', `
HelpUri='https://www.contoso.com/docs/information')]
[OutputType([String])]
param(
   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $UserName,

   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $Password,

   [Parameter(ParameterSetName='ConnectionObject', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [Hashtable]
   $Connection
)

switch ($PSCmdlet.ParameterSetName) {
   "UserAccount" {
      $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $UserName, $Password
      Connect-Contoso -Credential $cred
   }
   "ConnectionObject" {
      Connect-Contoso -Connection $Connection
  }
}
}

Если эта информация предоставлена, в консоли PowerShell можно отобразить текст справки с помощью командлета Get-Help. Этот текст также отображается на портале Azure.

Тип подключения

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

В следующем примере runbook для доступа к ресурсам Contoso и возврата данных из внешней службы используется ресурс подключения Contoso с именем ContosoConnection. В этом примере поля сопоставляются со свойствами UserName и Password объекта PSCredential, а затем передаются в командлет.

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $contosoConnection.UserName, $contosoConnection.Password
Connect-Contoso -Credential $cred
}

Наиболее простой и лучший способ — это передать объект подключения непосредственно в командлет.

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

Connect-Contoso -Connection $contosoConnection
}

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

Тип выходных данных

Укажите тип выходных данных для всех командлетов в модуле. Определение типа выходных данных для командлета позволяет технологии IntelliSense на этапе разработки помочь в определении свойств выходных данных командлета во время его создания. Такой подход особенно полезен при графической разработке runbook, где знание особенностей модуля на этапе проектирования является ключом к созданию удобного пользовательского опыта.

Добавьте [OutputType([<MyOutputType>])], где MyOutputType является допустимым типом. Дополнительные сведения об OutputType см. в статье о функциях OutputTypeAttribute. В следующем коде приведен пример добавления OutputType в командлет.

function Get-ContosoUser {
[OutputType([String])]
param(
   [string]
   $Parameter1
)
# <script location here>
}

Это поведение похоже на упреждающий ввод выходных данных командлета в среде службы интеграции PowerShell, при котором не нужно запускать командлет.

Состояние командлета

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

$globalNum = 0
function Set-GlobalNum {
   param(
       [int] $num
   )

   $globalNum = $num
}
function Get-GlobalNumTimesTwo {
   $output = $globalNum * 2

   $output
}

Зависимость модуля

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

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

Модуль не должен зависеть от каких-либо уникальных параметров реестра на узле. Их примером могут служить параметры, которые задаются при установке продукта.

Пути к файлам модуля

Убедитесь, что длина путей ко всем файлам в модуле не превышает 140 символов. Любые пути, длина которых превышает 140 символов, вызывают проблемы с импортом последовательностей runbook. Службе автоматизации не удается импортировать файл в сеанс PowerShell с помощью Import-Module, если путь к такому файлу состоит из более чем 140 символов.

Импорт модулей

В этом разделе описывается несколько способов импорта модуля в учетную запись службы автоматизации.

Импорт модулей на портале Azure

Чтобы импортировать модуль на портале Azure, выполните следующие действия.

1. Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
2. На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
3. В разделе Общие ресурсы выберите Модули.
4. Выберите Добавить модуль.
5. Выберите файл ZIP, содержащий модуль.
6. Нажмите кнопку ОК, чтобы начать процесс импорта.

Импорт модулей с помощью PowerShell

Для импорта модуля в учетную запись службы автоматизации можно использовать командлет New-AzAutomationModule. Командлет принимает URL-адрес для ZIP-архива модуля.

$moduleName = "<ModuleName>"
$contentLinkUri = "<ModuleUri>"
$runtimeVersion = "<RuntimeVersion>" # 5.1 or 7.2
$resourceGroupName = "<ResourceGroupName>"
$automationAccountName = "<AutomationAccountName>"
New-AzAutomationModule -Name $moduleName -RuntimeVersion $runtimeVersion -ContentLinkUri $contentLinkUri -ResourceGroupName $resourceGroupName -AutomationAccountName $automationAccountName

Вы также можете использовать тот же командлет для импорта модуля напрямую из коллекции PowerShell. Не забудьте скачать ModuleName и ModuleVersion из PowerShell Gallery.

$moduleName = "<ModuleName>"
$moduleVersion = "<ModuleVersion>"
$runtimeVersion = "<RuntimeVersion>" # 5.1 or 7.2
$resourceGroupName = "<ResourceGroupName>"
$automationAccountName = "<AutomationAccountName>"
New-AzAutomationModule -AutomationAccountName $automationAccountName -RuntimeVersion $runtimeVersion -ResourceGroupName $resourceGroupName -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"

Импорт модулей из коллекции PowerShell

Вы можете импортировать модули коллекции PowerShell либо непосредственно из коллекции, либо из учетной записи службы автоматизации.

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

1. Перейдите на страницу https://www.powershellgallery.com и найдите модуль для импорта.
2. В разделе Параметры установки на вкладке Служба автоматизации Azure выберите Deploy to Azure Automation (Развертывание в службу автоматизации Azure). Портал Azure можно открыть с помощью этого действия.
3. На странице "Импорт" выберите учетную запись службы автоматизации и нажмите кнопку ОК.

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

1. Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
2. На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
3. В разделе Общие ресурсы выберите Модули.
4. Выберите Обзор коллекции, а затем найдите модуль в коллекции.
5. Выберите модуль для импорта и нажмите Импорт.
6. Нажмите кнопку ОК, чтобы начать процесс импорта.

Удаление модулей

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

Удаление модулей на портале Azure

Чтобы удалить модуль на портале Azure, выполните следующие действия.

1. Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
2. На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
3. В разделе Общие ресурсы выберите Модули.
4. Выберите модуль, который требуется удалить.
5. На странице "Модуль" выберите Удалить. Если это один из стандартных модулей, выполняется откат к версии, имевшейся на момент создания учетной записи службы автоматизации.

Удаление модулей с помощью PowerShell

Чтобы удалить модуль с помощью PowerShell, выполните следующую команду:

Remove-AzAutomationModule -Name <moduleName> -AutomationAccountName <automationAccountName> -ResourceGroupName <resourceGroupName>

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

• Дополнительные сведения об использовании модулей Azure PowerShell см. в статье Начало работы с Azure PowerShell.

• Дополнительные сведения о создании модулей PowerShell см. в статье Написание модуля Windows PowerShell.