Administración de módulos en Azure Automation

Azure Automation usa una serie de módulos de PowerShell para habilitar cmdlets en runbooks y recursos de DSC en configuraciones de DSC. Los módulos compatibles incluyen:

• Azure PowerShell Az.Automation
• Azure PowerShell AzureRM.Automation
• Otros módulos de PowerShell
• Módulo Orchestrator.AssetManagement.Cmdlets interno
• Módulos de Python 2
• Módulos personalizados creados por el usuario

Cuando se crea una cuenta de Automation, Azure Automation importa algunos módulos de forma predeterminada. Consulte Módulos predeterminados.

Espacios aislados

Cuando Automation ejecuta trabajos de compilación de runbook y DSC, carga los módulos en espacios aislados en los que se pueden ejecutar los runbooks y se pueden compilar las configuraciones de DSC. Automation también coloca automáticamente los recursos de DSC en los módulos del servidor de extracción de DSC. Las máquinas pueden extraer los recursos cuando aplican las configuraciones de DSC.

El espacio aislado de nube admite 48 llamadas del sistema como máximo y, por motivos de seguridad, restringe todas las demás. Otras funcionalidades, como la administración de credenciales y algunas redes, no se admiten en el espacio aislado de nube.

Debido al número de módulos y cmdlets incluidos, es difícil saber de antemano cuál de los cmdlets realizará llamadas no admitidas. Por lo general, se han detectado problemas con cmdlets que requieren acceso con privilegios elevados, que requieren una credencial como parámetro o con cmdlets relacionados con redes. Los cmdlets que realizan operaciones de red de pila completa no se admiten en el espacio aislado, lo que incluye Connect-AipService del módulo AIPService de PowerShell y Resolve-DnsName del módulo DNSClient.

Estas son limitaciones conocidas del espacio aislado. La solución recomendada es implementar una instancia de Hybrid Runbook Worker o usar Azure Functions.

Módulos predeterminados

Todas las nuevas cuentas de Automation tienen la versión más reciente del módulo Az de PowerShell importado de manera predeterminada. El módulo Az reemplaza a AzureRM y es el módulo recomendado para usar con Azure. Los módulos predeterminados de la nueva cuenta de Automation incluyen los 24 módulos AzureRM existentes y más de 60 módulos Az.

Hay una opción nativa para actualizar los módulos al módulo Az más reciente por el usuario para las cuentas de Automation. La operación controlará todas las dependencias del módulo en el back-end, lo que elimina las complicaciones de actualizar los módulos manualmente o ejecutar el runbook para actualizar los módulos de Azure.

Si la cuenta de Automation existente solo tiene módulos AzureRM, la opción Actualizar módulos Az actualizará la cuenta de Automation con la versión seleccionada por el usuario del módulo Az.

Si la cuenta de Automation existente tiene AzureRM y algunos módulos Az, la opción importará los módulos Az restantes a la cuenta de Automation. Los módulos Az existentes tendrán preferencia y la operación de actualización no actualizará esos módulos. Esto es para asegurarse de que la operación del módulo de actualización no conduce a ningún error de ejecución de runbook mediante la actualización involuntaria de un módulo que usa un runbook. La manera recomendada para este escenario es eliminar primero los módulos Az existentes y, a continuación, realizar las operaciones de actualización para importar el módulo Az más reciente en la cuenta de Automation. Estos tipos de módulos, no importados de manera predeterminada, se conocen como personalizados. Los módulos personalizados siempre tendrán preferencia sobre los módulos predeterminados.

Por ejemplo: si ya tiene el módulo Az.Aks importado con la versión 2.3.0 que proporciona el módulo Az 6.3.0 e intenta actualizar el módulo Az a la versión 6.4.0 más reciente. La operación de actualización importará todos los módulos Az desde el paquete 6.4.0, excepto Az.Aks. Para tener la versión más reciente de Az.Aks, elimine primero el módulo existente y, a continuación, realice la operación de actualización, o bien también puede actualizar este módulo por separado, como se describe en Importación de módulos Az para importar una versión diferente de un módulo específico.

En la tabla siguiente se enumeran los módulos que importa Azure Automation de manera predeterminada al crear la cuenta de Automation. Automation puede importar versiones más recientes de estos módulos. Pero no se puede quitar la versión original de la cuenta de Automation aunque se elimine una versión más reciente.

Los módulos predeterminados también se conocen como módulos globales. En Azure Portal, la propiedadMódulo global será true al ver un módulo que se importó al crear la cuenta.

Cmdlets internos

Azure Automation admite cmdlets internos que solo están disponibles cuando se ejecutan runbooks en el entorno de espacio aislado de Azure o en una instancia de Hybrid Runbook Worker de Windows. El módulo interno Orchestrator.AssetManagement.Cmdlets se instala de forma predeterminada en la cuenta de Automation y cuando el rol Hybrid Runbook Worker de Windows está instalado en la máquina.

En la tabla siguiente se definen los cmdlets internos. Estos cmdlets están diseñados para usarse en lugar de los cmdlets de Azure PowerShell para interactuar con los recursos de la cuenta de Automation. Los cmdlets recuperan secretos a partir de variables cifradas, credenciales y conexiones cifradas.

Tenga en cuenta que los cmdlets internos difieren en la nomenclatura de los cmdlets de Az y AzureRM. Los nombres de los cmdlets internos no contienen palabras como Azure o Az, sino que usan la palabra Automation. Se recomienda su uso antes que el uso de los cmdlets Az o AzureRM durante la ejecución del runbook en un espacio aislado de Azure o en una instancia de Hybrid Runbook Worker de Windows porque requieren menos parámetros y se ejecutan en el contexto del trabajo durante la ejecución.

Use los cmdlets de Az o AzureRM para manipular recursos de Automation fuera del contexto de un runbook.

Módulos de Python

En Azure Automation se pueden crear runbooks de Python 2. Para obtener información sobre un módulo de Python, ver Administrar paquetes de Python 2 en Azure Automation.

Módulos personalizados

Azure Automation admite módulos de PowerShell personalizados que se crean para usar con los runbooks y configuraciones de DSC. Un tipo de módulo personalizado es un módulo de integración que puede contener un archivo de metadatos para definir la funcionalidad personalizada para los cmdlets del módulo. Un ejemplo del uso de un módulo de integración se proporciona en Incorporación de un tipo de conexión.

Azure Automation puede importar un módulo personalizado para que sus cmdlets estén disponibles. En segundo plano, almacena el módulo y lo usa en los espacios aislados de Azure, al igual que ocurre con otros módulos.

Migración a módulos Az

En esta sección se explica cómo migrar a los módulos Az en Automation. Para más información, vea Migración de Azure PowerShell de AzureRM a Az.

No es recomendable ejecutar módulos Az y AzureRM en la misma cuenta de Automation. Cuando esté seguro de que quiere migrar de AzureRM a Az, es mejor confirmar completamente una migración entera. Automation suele reutilizar espacios aislados dentro de la cuenta de Automation para ahorrar en los tiempos de inicio. Si no realiza una migración completa del módulo, puede iniciar un trabajo que usa solo módulos AzureRM y luego iniciar otro trabajo que usa solo módulos Az. El espacio aislado pronto se bloquea, y recibe un error que indica que los módulos no son compatibles. Esta situación da lugar a bloqueos que se producen aleatoriamente de cualquier runbook o configuración específicos.

Prueba de los runbooks y las configuraciones de DSC antes de la migración de módulos

Asegúrese de probar todos los runbooks y las configuraciones de DSC cuidadosamente en una cuenta de Automation independiente antes de migrar a los módulos Az.

Detención y anulación de la programación de todos los runbooks que usan módulos de AzureRM

Para asegurarse de no ejecutar ningún runbook ni configuración de DSC existente que use módulos AzureRM, debe detener y anular la programación de todos los runbooks y las configuraciones afectados. En primer lugar, asegúrese de revisar cada runbook o configuración de DSC y sus programaciones por separado para garantizar que puede volver a programar el elemento en el futuro en caso necesario.

Cuando esté listo para quitar las programaciones, puede usar Azure Portal o el cmdlet Remove-AzureRmAutomationSchedule. Consulte Eliminación de una programación.

Eliminación de los módulos AzureRM

Es posible quitar los módulos AzureRM antes de importar los módulos Az. Sin embargo, si lo hace, puede interrumpir la sincronización del control de código fuente y provocar errores en los scripts que siguen programados. Si decide quitar los módulos, ver Desinstalación de AzureRM.

Importación de módulos Az

Al importar un módulo Az en la cuenta de Automation, no se importa automáticamente ese módulo en la sesión de PowerShell que usan los runbooks. Los módulos se importan en la sesión de PowerShell en las situaciones siguientes:

• Cuando un runbook invoca un cmdlet desde un módulo.
• Cuando un runbook importa el módulo de forma explícita con el cmdlet Import-Module.
• Cuando un runbook importa el módulo de forma explícita con la instrucciónusing module. La instrucción using se admite a partir de Windows PowerShell 5.0 y es compatible con las clases y la importación de tipos de enumeración.
• Cuando un runbook importa otro módulo dependiente.

Puede importar los módulos Az en la cuenta de Automation desde Azure Portal. Dado que Az.Accounts es una dependencia para los otros módulos Az, asegúrese de importar este módulo antes que cualquier otro.

• Examinar galería está disponible en la hoja Automatización de procesos>Módulos.
• La página Módulos muestra dos columnas nuevas: la versión del módulo y la versión el entorno de ejecución.

1. Inicie sesión en Azure Portal.

2. Busque y seleccione Cuentas de Automation.

3. En la página Cuentas de Automation, seleccione su cuenta de Automation en la lista.

4. En la cuenta de Automation, en Recursos compartidos, seleccione Módulos.

5. Seleccione Agregar un módulo. En la página Agregar un módulo, puede seleccionar cualquiera de las siguientes opciones:

   1. Buscar un archivo: esta opción selecciona un archivo de la máquina local.
   2. Examinar desde la galería: puede examinar y seleccionar un módulo existente de la galería.

6. Haga clic en Seleccionar para seleccionar un módulo.

7. Seleccione Versión del entorno de ejecución y haga clic en Importar.

   

8. En la página Módulos, puede ver el módulo importado en la cuenta de Automation.

También puede realizar esta importación con la Galería de PowerShell mediante la búsqueda del módulo que se va a importar. Cuando encuentre el módulo, selecciónelo y elija la pestaña Azure Automation. Seleccione Implementar en Azure Automation.

Prueba de los runbooks

Una vez que los módulos Az se han importado en la cuenta de Automation, puede empezar a editar los runbooks y las configuraciones de DSC para usar los nuevos módulos. Una manera de probar la modificación de un runbook para usar los nuevos cmdlets consiste en utilizar el comando Enable-AzureRmAlias -Scope Process al principio del runbook. Al incorporar este comando al runbook, el script se puede ejecutar sin cambios.

Creación de módulos

Se recomienda que tenga en cuenta los aspectos de esta sección al crear un módulo de PowerShell personalizado para usarlo en Azure Automation. Para preparar el módulo para la importación, debe crear al menos un archivo .dll de módulo psd1, psm1 o PowerShell con el mismo nombre que la carpeta del módulo. Después, debe comprimir la carpeta del módulo para que Azure Automation pueda importarla como un único archivo. El paquete .zip debe tener el mismo nombre que la carpeta de módulo que contiene.

Para más información sobre la creación de un módulo de PowerShell, consulte Cómo escribir un módulo de script de PowerShell.

Carpeta de versiones

El control de versiones de módulos en paralelo de PowerShell le permite usar más de una versión de un módulo en PowerShell. Esto puede ser útil si tiene scripts anteriores que se han probado y solo funcionan con una versión determinada de un módulo de PowerShell, pero para otros necesita una versión más reciente del mismo módulo.

A fin de crear módulos de PowerShell para que contengan varias versiones, cree la carpeta del módulo y, después, cree una carpeta en su interior para cada versión del módulo que quiera usar. En el ejemplo siguiente, un módulo denominado TestModule proporciona dos versiones: 1.0.0 y 2.0.0.

TestModule
   1.0.0
   2.0.0

Dentro de cada una de las carpetas de versión, copie los archivos .dll de módulo de PowerShell o .psm1 y .psd1 que componen un módulo en la carpeta de la versión correspondiente. Comprima la carpeta del módulo para que Azure Automation pueda importarla como un único archivo .zip. Aunque Automation solo muestra una de las versiones del módulo importadas, si el paquete del módulo contiene versiones en paralelo del módulo, todas están disponibles para su uso en los runbooks o configuraciones de DSC.

Aunque Automation admite módulos que contienen versiones en paralelo en el mismo paquete, no admite el uso de varias versiones de un módulo entre importaciones de paquetes de módulos. Por ejemplo, puede importar el módulo A, que contiene las versiones 1 y 2 a la cuenta de Automation. Después, actualice el módulo A para incluir las versiones 3 y 4; cuando lo importe en la cuenta de Automation, solo las versiones 3 y 4 se pueden usar en cualquier runbook o configuración de DSC. Si necesita que todas las versiones (1, 2, 3 y 4) estén disponibles, se deben incluir en el archivo .zip.

Si va a usar otras versiones del mismo módulo entre runbooks, siempre debe declarar la versión que quiera utilizar en el runbook con el cmdlet Import-Module e incluir el parámetro -RequiredVersion <version>. Incluso si la versión que quiere usar es la más reciente. Esto se debe a que los trabajos de runbook se pueden ejecutar en el mismo espacio aislado. Si el espacio aislado ya ha cargado de forma explícita un módulo de un número de versión concreto, porque un trabajo anterior de ese espacio aislado lo haya indicado, los trabajos futuros de ese espacio aislado no cargarán automáticamente la versión más reciente de ese módulo. Esto se debe a que alguna versión ya está cargada en el espacio aislado.

Para un recurso de DSC, use el comando siguiente para especificar una versión concreta:

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

Información de ayuda

Incluya una sinopsis, una descripción y un identificador URI de ayuda para todos los cmdlets del módulo. En PowerShell, puede definir la información de ayuda de los cmdlets mediante el cmdlet Get-Help. En el ejemplo siguiente se muestra cómo definir una sinopsis y un identificador URI de ayuda en un archivo de módulo .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
  }
}
}

Proporcionar esta información permite mostrar el texto de ayuda mediante el cmdlet Get-Help en la consola de PowerShell. Este texto también se muestra en Azure Portal.

Tipo de conexión

Si el módulo se conecta a un servicio externo, defina un tipo de conexión mediante un módulo de integración personalizado. Cada cmdlet del módulo debería aceptar una instancia de ese tipo de conexión (objeto de conexión) como parámetro. Los usuarios asignan parámetros del recurso de conexión a los parámetros correspondientes del cmdlet cada vez que llaman a un cmdlet.

El ejemplo de runbook siguiente usa un recurso de conexión de Contoso denominado ContosoConnection para acceder a los recursos de Contoso y devolver datos desde el servicio externo. En este ejemplo, los campos se asignan a las propiedades UserName y Password de un objeto PSCredential y, a continuación, se pasan al cmdlet.

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

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

Existe otra forma más fácil y eficaz de enfocar este comportamiento y consiste en pasar directamente el objeto de conexión al cmdlet:

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

Connect-Contoso -Connection $contosoConnection
}

Para habilitar un comportamiento como este en sus cmdlets, permítales que acepten directamente un objeto de conexión como parámetro en lugar de usar solamente campos de conexión en los parámetros. Normalmente, necesitará un conjunto de parámetros para cada uno de ellos, de forma que los usuarios que no utilizan Automation puedan llamar a los cmdlets sin necesidad de crear una tabla hash que actúe como objeto de conexión. El conjunto de parámetros UserAccount se usa para pasar las propiedades de los campos de conexión. ConnectionObject permite pasar directamente la conexión.

Tipo de salida

Defina el tipo de salida de todos los cmdlets del módulo. Definir un tipo de salida en un cmdlet permite que IntelliSense le ayude a determinar, en tiempo de diseño, las propiedades de salida del cmdlet durante la creación. Este procedimiento recomendado resulta especialmente útil durante la creación gráfica de un runbook, para el que la información en tiempo de diseño resulta esencial para facilitar la experiencia del usuario con el módulo.

Agregue [OutputType([<MyOutputType>])], donde MyOutputType es un tipo válido. Para más información sobre OutputType, consulte About Functions OutputTypeAttribute (Acerca de las funciones OutputTypeAttribute). El siguiente código es un ejemplo de cómo agregar OutputType a un cmdlet:

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

Este comportamiento es similar a la funcionalidad "type ahead" de la salida de los cmdlets del entorno del servicio de integración de PowerShell, sin necesidad de ejecutarla.

Estado del cmdlet

Cree todos los cmdlets del módulo sin estado. Pueden ejecutarse varios trabajos de runbook simultáneamente en el mismo elemento AppDomain y el mismo proceso y espacio aislado. Si no hay ningún estado compartido en esos niveles, los trabajos pueden afectar entre sí. Este comportamiento puede provocar problemas intermitentes y difíciles de diagnosticar. A continuación, se muestra un ejemplo de lo que no hay que hacer:

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

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

   $output
}

Dependencia de los módulos

Asegúrese de que el módulo está totalmente contenido en un paquete que se puede copiar mediante XCopy. Los módulos de Automation se distribuyen en los espacios aislados de Automation cuando los runbooks se ejecutan. Los módulos deben funcionar de forma independiente con respecto al host que los ejecuta.

Debe ser capaz de comprimir y mover un paquete de módulos y conseguir que funcione con normalidad cuando se importe en el entorno de PowerShell de otro host. Para que esto ocurra, asegúrese de que el módulo no dependa de ningún archivo que esté fuera de la carpeta del módulo que se comprime cuando el módulo se importa en Automation.

El módulo no debe depender de ninguna configuración de registro única en un host. Un ejemplo es la configuración que se realiza cuando se instala un producto.

Rutas de acceso a los archivos del módulo

Asegúrese de que todos los archivos del módulo tienen rutas de acceso con menos de 140 caracteres. Las rutas de acceso con más de 140 caracteres provocan problemas de importación de runbooks. Automation no puede importar ningún archivo con un tamaño de ruta de acceso superior a 140 caracteres en la sesión de PowerShell con Import-Module.

Importación de módulos

En esta sección se definen varias formas de importar un módulo en la cuenta de Automation.

Importación de módulos en Azure Portal

Para importar un módulo en Azure Portal:

1. En el portal, busque y seleccione Cuentas de Automation.
2. En la página Cuentas de Automation, seleccione su cuenta de Automation en la lista.
3. En Recursos compartidos, seleccione Módulos.
4. Seleccione Agregar un módulo.
5. Seleccione el archivo .zip que contiene el módulo.
6. Seleccione Aceptar para iniciar el proceso de importación.

Importación de módulos mediante PowerShell

Puede usar el cmdlet New-AzAutomationModule para importar un módulo en la cuenta de Automation. El cmdlet toma una dirección URL para un paquete .zip del módulo.

New-AzAutomationModule -Name <ModuleName> -ContentLinkUri <ModuleUri> -ResourceGroupName <ResourceGroupName> -AutomationAccountName <AutomationAccountName>

También puede usar el mismo cmdlet para importar un módulo directamente desde la Galería de PowerShell. Asegúrese de captar ModuleName y ModuleVersion de la Galería de PowerShell.

$moduleName = <ModuleName>
$moduleVersion = <ModuleVersion>
New-AzAutomationModule -AutomationAccountName <AutomationAccountName> -ResourceGroupName <ResourceGroupName> -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"

Importación de módulos desde la Galería de PowerShell

Puede importar módulos de la Galería de PowerShell directamente desde la galería o desde la cuenta de Automation.

Para importar un módulo directamente desde la Galería de PowerShell:

1. Vaya a https://www.powershellgallery.com y busque el módulo que desea importar.
2. En Opciones de instalación, en la pestaña Azure Automation, seleccione Implementar en Azure Automation. Esta acción abre Azure Portal.
3. En la página Importar, seleccione su cuenta de Automation y seleccione Aceptar.

Para importar un módulo de la Galería de PowerShell directamente desde la cuenta de Automation:

1. En el portal, busque y seleccione Cuentas de Automation.
2. En la página Cuentas de Automation, seleccione su cuenta de Automation en la lista.
3. En Recursos compartidos, seleccione Módulos.
4. Seleccione Examinar galería y busque el módulo en la galería.
5. Seleccione el módulo que quiere importar y, después, haga clic en Importar.
6. Seleccione Aceptar para iniciar el proceso de importación.

Eliminación de los módulos

Si tiene problemas con un módulo o necesita revertir a una versión anterior de un módulo, puede eliminarlo de la cuenta de Automation. No se pueden eliminar las versiones originales de los módulos predeterminados que se importan al crear una cuenta de Automation. Si el módulo que desea eliminar es una versión más reciente de uno de los módulos predeterminados, se revertirá a la versión que se instaló con la cuenta de Automation. En caso contrario, se quitará cualquier módulo que se elimine de la cuenta de Automation.

Eliminación de módulos en Azure Portal

Para eliminar un módulo en Azure Portal:

1. En el portal, busque y seleccione Cuentas de Automation.
2. En la página Cuentas de Automation, seleccione su cuenta de Automation en la lista.
3. En Recursos compartidos, seleccione Módulos.
4. Seleccione el módulo que quiera quitar.
5. En la página Módulo, seleccione Eliminar. Si este módulo es uno de los módulos predeterminados, se revertirá a la versión que existía cuando se creó la cuenta de Automation.

Eliminación de módulos mediante PowerShell

Para quitar un módulo a través de PowerShell, ejecute el siguiente comando:

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

Pasos siguientes

• Para más información sobre el uso de los módulos de Azure PowerShell, consulte Introducción a Azure PowerShell.

• Para más información sobre la creación de módulos de PowerShell, consulte Escritura de un módulo de Windows PowerShell.