Администрирование модулей в службе автоматизации Azure
Служба автоматизации Azure использует несколько модулей PowerShell для включения командлетов в последовательностях runbook и ресурсов DSC в конфигурациях DSC. Поддерживаются следующие модули:
- Azure PowerShell Az.Automation;
- Azure PowerShell AzureRM.Automation;
- другие модули PowerShell;
- внутренний модуль
Orchestrator.AssetManagement.Cmdlets; - модули Python 2;
- созданные вами пользовательские модули.
При создании учетной записи службы автоматизации Azure эта служба по умолчанию импортирует ряд модулей. См. раздел Стандартные модули.
Песочницы
Когда служба автоматизации выполняет задания компиляции DSC и runbook, она загружает модули в песочницы, где могут выполняться runbook и компилироваться конфигурации DSC. Она также автоматически помещает все ресурсы DSC в модули на опрашиваемом сервере DSC. Компьютеры могут извлекать ресурсы при применении конфигураций DSC.
Облачная песочница поддерживает максимум 48 системных вызовов и ограничивает все остальные вызовы в целях безопасности. Другие функции, например управление учетными данными и некоторые сетевые подключения, не поддерживаются в облачной песочнице.
Из-за количества модулей и командлетов трудно заранее узнать, какой из командлетов выполнит неподдерживаемые вызовы. Обычно возникают проблемы с командлетами, требующими повышенного доступа и учетных данных в качестве параметра, или с командлетами, связанными с сетью. В песочнице не поддерживаются командлеты, выполняющие полностековые сетевые операции, включая Connect-AipService из модуля AIPService PowerShell и Resolve-DnsName из модуля DNSClient.
Это все известные ограничения песочницы. Чтобы избежать проблем, рекомендуем развертывать гибридную рабочую роль Runbook или использовать Функции Azure.
Важно!
Не включайте ключевое слово "AzureRm" в скрипты, предназначенные для выполнения с помощью модуля Az. Добавление этого ключевого слова даже в комментарий может привести к загрузке AzureRm и конфликту с модулем Az.
Стандартные модули
Все новые учетные записи службы автоматизации имеют последнюю версию модуля PowerShell Az, импортированного по умолчанию. Модуль Az заменяет AzureRM и рекомендуется использовать модуль с Azure. Модули по умолчанию в новой учетной записи службы автоматизации включают существующие 24 модуля AzureRM и 60+ модули Az.
Существует собственный вариант обновления модулей до последнего модуля Az пользователем для учетных записей службы автоматизации. Эта операция будет обрабатывать все зависимости модуля во внутренней части, тем самым удаляя мешки обновления модулей вручную или выполняя модуль Runbook для обновления модулей 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 импортируются по умолчанию при создании учетной записи службы автоматизации. Служба автоматизации может импортировать более новые версии этих модулей. Однако вы не сможете удалить исходную версию из учетной записи службы автоматизации, даже если удалите более новую версию.
Модули по умолчанию также называются глобальными модулями. На портале Azure свойство Global Module будет иметь значение true, если просматривается модуль, который был импортирован при создании учетной записи.
Примечание.
В учетных записях службы автоматизации, используемых для развертывания компонента Запуск и остановка виртуальных машин в нерабочее время, не рекомендуется изменять модули и последовательности runbook.
Внутренние командлеты
Служба автоматизации Azure поддерживает только те внутренние командлеты, которые доступны при выполнении последовательностей runbook в среде песочницы Azure или при использовании гибридной рабочей роли Runbook Windows. Внутренний модуль Orchestrator.AssetManagement.Cmdlets устанавливается по умолчанию в учетной записи службы автоматизации при установке гибридной рабочей роли Runbook Windows на компьютер.
Внутренние командлеты определены в следующей таблице. При взаимодействии с ресурсами учетной записи службы автоматизации эти командлеты используются вместо командлетов Azure PowerShell. Они могут получать секреты из зашифрованных переменных, учетных данных и зашифрованных соединений.
| Имя | Описание |
|---|---|
| Get-AutomationCertificate | Get-AutomationCertificate [-Name] <string> [<CommonParameters>] |
| Get-AutomationConnection | Get-AutomationConnection [-Name] <string> [-DoNotDecrypt] [<CommonParameters>] |
| Get-AutomationPSCredential | Get-AutomationPSCredential [-Name] <string> [<CommonParameters>] |
| Get-AutomationVariable | Get-AutomationVariable [-Name] <string> [-DoNotDecrypt] [<CommonParameters>] |
| Set-AutomationVariable | Set-AutomationVariable [-Name] <string> -Value <Object> [<CommonParameters>] |
| Start-AutomationRunbook | Start-AutomationRunbook [-Name] <string> [-Parameters <IDictionary>] [-RunOn <string>] [-JobId <guid>] [<CommonParameters>] |
| Wait-AutomationJob | Wait-AutomationJob -Id <guid[]> [-TimeoutInMinutes <int>] [-DelayInSeconds <int>] [-OutputJobsTransitionedToRunning] [<CommonParameters>] |
Обратите внимание, что именование внутренних командлетов отличается от командлетов Az и AzureRM. Имена внутренних командлетов не содержат таких слов, как Azure или Az, но в них используется слово Automation. Рекомендуем использовать командлеты Az или AzureRM во время выполнения runbook в песочнице Azure или в гибридной рабочей роли Runbook Windows, так как для них нужно меньше параметров и они запускаются в контексте задания во время выполнения.
Командлеты Az и AzureRM следует использовать для выполнения операций с ресурсами службы автоматизации вне контекста runbook.
Модули Python
В службе автоматизации Azure можно создавать последовательности runbook для Python 2. Сведения о модуле Python см. в статье Управление пакетами Python 2 в службе автоматизации Azure.
Пользовательские модули
Служба автоматизации Azure поддерживает пользовательские модули PowerShell, созданные для использования с runbook и конфигурациями DSC. Один из типов пользовательских модулей — модуль интеграции, который дополнительно содержит файл метаданных для определения пользовательской функциональности его командлетов. Пример использования модуля интеграции приведен в разделе Добавление типа подключения.
Служба автоматизации Azure может импортировать пользовательский модуль, чтобы обеспечить доступность его командлетов. Она сохраняет модуль и использует его в песочнице Azure в фоновом режиме так же, как и другие модули.
Миграция в модули Az
В этом разделе описывается миграция в модули Az в службе автоматизации. Дополнительные сведения см. в статье Перенос Azure PowerShell с AzureRM на Az.
Мы не рекомендуем использовать модули AzureRM и Az в одной учетной записи службы автоматизации. Если вам непременно необходимо выполнить миграцию с AzureRM на Az, лучше перенести весь модуль полностью. Служба автоматизации часто повторно использует песочницы в учетной записи службы автоматизации, чтобы сократить время запуска. Если вы не перенесете модуль полностью и при этом сначала запустите задание, использующее только модули AzureRM, а затем — другое задание, использующее только модули Az, вскоре произойдет сбой песочницы и появится сообщение об ошибке из-за несовместимости модулей. Это приведет к возникновению случайных сбоев для продольных runbook и конфигураций.
Примечание.
При создании учетной записи службы автоматизации даже после миграции в модули Az служба автоматизации по-прежнему установит модули AzureRM по умолчанию.
Тестирование runbook и конфигураций DSC перед миграцией модулей
Перед миграцией на модули Az тщательно протестируйте все runbook и конфигурации DSC в отдельной учетной записи службы автоматизации.
Остановка и отмена выполнения по расписанию всех runbook, использующих модули AzureRM
Чтобы имеющиеся runbook или конфигурации DSC, использующие модули AzureRM, не запускались, необходимо остановить их все и отменить их выполнение по расписанию. Сначала проверьте отдельно каждую последовательность runbook и конфигурацию DSC, а также их расписания и убедитесь, что вы сможете при необходимости перепланировать элемент в будущем.
Когда будете готовы удалить расписания, можно использовать портал Azure или командлет Remove-AzureRmAutomationSchedule. См. раздел Удаление расписания.
Удаление модулей AzureRM
Перед импортом модулей Az можно удалить модули AzureRM. Однако в этом случае синхронизация системы управления исходным кодом может прерваться, что приведет к сбою всех скриптов, выполнение которых еще запланировано. Если вы решили удалить эти модули, ознакомьтесь с разделом Удаление AzureRM.
Импорт модулей Az
При импорте модуля Az в учетную запись службы автоматизации он не импортируется автоматически в сеанс PowerShell, используемый последовательностями runbook. Модули импортируются в сеанс PowerShell в следующих ситуациях:
- если runbook вызывает командлет из модуля;
- если runbook импортирует модуль явным образом с помощью командлета Import-Module;
- если runbook импортирует модуль явным образом с помощью инструкции модуля using. Инструкция using работает в версиях, начиная с Windows PowerShell 5.0, и поддерживает импорт классов и типов перечисления.
- если runbook импортирует другой зависимый модуль.
Вы можете импортировать модули Az в учетную запись Службы автоматизации из портала Azure. Поскольку от модуля Az.Accounts зависят другие модули Az, обязательно импортируйте его перед остальными.
Примечание.
При внедрении поддержки PowerShell 7.1 (предварительная версия) параметр коллекции "Обзор" был обновлен со следующими изменениями:
- Обзор коллекции доступен в колонке "Модули автоматизации>процессов".
- На странице "Модули" отображаются два новых столбца : версия модуля и версия среды выполнения
Войдите на портал Azure.
Найдите и выберите раздел Учетные записи службы автоматизации.
На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
В учетной записи службы автоматизации в области Общие ресурсы выберите Модули.
Выберите Добавить модуль. На странице "Добавление модуля" можно выбрать один из следующих параметров:
- Найдите файл — выбирает файл на локальном компьютере.
- Перейдите из коллекции . Вы можете просматривать и выбирать существующий модуль из коллекции.
Щелкните " Выбрать ", чтобы выбрать модуль.
Выберите версию среды выполнения и нажмите кнопку "Импорт".
На странице "Модули" можно просмотреть импортированный модуль в учетной записи службы автоматизации.
Этот процесс импорта можно также выполнить с помощью коллекции PowerShell, выполнив поиск импортируемого модуля. При поиске модуля выберите его и перейдите на вкладку служба автоматизации Azure. Выберите "Развернуть" для служба автоматизации Azure.
Тестирование модулей runbook
После импорта модулей Az в учетную запись службы автоматизации можно начать редактирование runbook и конфигураций 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-файл для импорта должен содержать их.
Если вы планируете использовать разные версии одного модуля в нескольких runbook, следует всегда объявлять версию, которую вы хотите использовать, с помощью командлета 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.
Connection type
Если модуль подключается к внешней службе, определите тип соединения, используя пользовательский модуль интеграции. Каждый командлет в модуле должен принимать экземпляр этого типа соединения (объект соединения) в качестве параметра. Пользователи могут сопоставлять параметры ресурса подключения с соответствующими параметрами командлета при каждом вызове командлета.
В следующем примере 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, выполните следующие действия.
- Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
- На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
- В разделе Общие ресурсы выберите Модули.
- Выберите Добавить модуль.
- Выберите файл ZIP, содержащий модуль.
- Нажмите кнопку ОК, чтобы начать процесс импорта.
Импорт модулей с помощью PowerShell
Для импорта модуля в учетную запись службы автоматизации можно использовать командлет New-AzAutomationModule. Командлет принимает URL-адрес для пакета ZIP модуля.
New-AzAutomationModule -Name <ModuleName> -ContentLinkUri <ModuleUri> -ResourceGroupName <ResourceGroupName> -AutomationAccountName <AutomationAccountName>
Вы также можете использовать тот же командлет для импорта модуля напрямую из коллекции PowerShell. Не забудьте получить ModuleName и ModuleVersion из коллекции PowerShell.
$moduleName = <ModuleName>
$moduleVersion = <ModuleVersion>
New-AzAutomationModule -AutomationAccountName <AutomationAccountName> -ResourceGroupName <ResourceGroupName> -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"
Импорт модулей из коллекции PowerShell
Вы можете импортировать модули коллекции PowerShell либо непосредственно из коллекции, либо из учетной записи службы автоматизации.
Чтобы импортировать модуль непосредственно из коллекции PowerShell, выполните следующие действия.
- Перейдите на страницу https://www.powershellgallery.com и найдите модуль для импорта.
- В разделе Параметры установки на вкладке Служба автоматизации Azure выберите Deploy to Azure Automation (Развертывание в службу автоматизации Azure). Портал Azure можно открыть с помощью этого действия.
- На странице "Импорт" выберите учетную запись службы автоматизации и нажмите кнопку ОК.
Чтобы импортировать модуль коллекции PowerShell непосредственно из учетной записи службы автоматизации, выполните следующие действия.
- Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
- На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
- В разделе Общие ресурсы выберите Модули.
- Выберите Обзор коллекции, а затем найдите модуль в коллекции.
- Выберите модуль для импорта и нажмите Импорт.
- Нажмите кнопку ОК, чтобы начать процесс импорта.
Удаление модулей
Если у вас возникли проблемы с модулем или необходимо выполнить откат к его предыдущей версии, его можно удалить из учетной записи службы автоматизации. Вы не можете удалить исходные версии стандартных модулей, импортированные при создании учетной записи службы автоматизации. Если удаляемый модуль является более новой версией одного из стандартных модулей, выполняется откат к версии, которая была установлена вместе с учетной записью службы автоматизации. Все остальные модули, удаляемые из учетной записи службы автоматизации, удаляются полностью.
Удаление модулей на портале Azure
Чтобы удалить модуль на портале Azure, выполните следующие действия.
- Найдите и выберите раздел Automation Accounts (Учетные записи службы автоматизации) на портале.
- На странице Учетные записи автоматизации выберите в списке нужную учетную запись службы автоматизации.
- В разделе Общие ресурсы выберите Модули.
- Выберите модуль, который требуется удалить.
- На странице "Модуль" выберите Удалить. Если это один из стандартных модулей, выполняется откат к версии, имевшейся на момент создания учетной записи службы автоматизации.
Удаление модулей с помощью PowerShell
Чтобы удалить модуль с помощью PowerShell, выполните следующую команду:
Remove-AzAutomationModule -Name <moduleName> -AutomationAccountName <automationAccountName> -ResourceGroupName <resourceGroupName>
Следующие шаги
Дополнительные сведения об использовании модулей Azure PowerShell см. в статье Начало работы с Azure PowerShell.
Дополнительные сведения о создании модулей PowerShell см. в статье Написание модуля Windows PowerShell.