Instalación del módulo Az de PowerShell para Azure Stack Hub

  • Artículo
  • Tiempo de lectura: 11 minutos

En este artículo se explica cómo instalar el módulo Az de Azure PowerShell y los módulos del administrador de Azure Stack Hub compatibles con PowerShellGet. Los módulos Az se pueden instalar en plataformas Windows, macOS y Linux.

También puede ejecutar módulos Az para Azure Stack Hub en un contenedor de Docker. Para obtener instrucciones, consulte Uso de Docker para ejecutar PowerShell para Azure Stack Hub.

Si desea instalar el módulo PowerShell Resource Modules (AzureRM) para Azure Stack Hub, consulte Instalación del módulo AzureRM de PowerShell para Azure Stack Hub.

Importante

Probablemente no habrá nuevas versiones del módulo Azure Resource Modules. Los módulos Azure Resource Modules solo tienen soporte técnico para correcciones críticas. En el futuro, solo habrá publicaciones de Az para Azure Stack Hub.

Puede usar perfiles de API para especificar los puntos de conexión compatibles para los proveedores de recursos de Azure Stack Hub.

Los perfiles de API proporcionan una manera de administrar las diferencias de versión entre Azure y Azure Stack Hub. Un perfil de versión de la API es un conjunto de módulos de PowerShell de Azure Resource Manager con versiones específicas de la API. Cada plataforma de la nube tiene un conjunto de perfiles de versión de API compatibles. Por ejemplo, Azure Stack Hub admite una versión de perfil específica, como 2020-09-01-hybrid. Cuando se instala un perfil, se instalan los módulos de PowerShell Azure Resource Manager que se corresponden con el perfil especificado.

Puede instalar los módulos Az de PowerShell compatibles con Azure Stack Hub en un escenario desconectado, parcialmente conectado o conectado a Internet. Este artículo le guía por las instrucciones detalladas para estos escenarios.

1. Comprobación de los requisitos previos

Ahora se admiten los módulos de Az en Azure Stack Hub con la actualización 2002 o posterior y con las revisiones actuales instaladas. Para más información, consulte las notas de la versión de Azure Stack Hub.

Los módulos de Az de Azure PowerShell funcionan con PowerShell 5.1 o versiones posteriores en Windows o con PowerShell Core 6.x y versiones posteriores en cualquier plataforma. Debe instalar la última versión de PowerShell Core disponible para su sistema operativo. Azure PowerShell no tiene otros requisitos cuando se ejecuta en PowerShell Core.

Para comprobar la versión de PowerShell, ejecute el comando:

$PSVersionTable.PSVersion

Requisitos previos para Windows

Para usar Azure PowerShell en PowerShell 5.1 en Windows:

  1. Actualice a Windows PowerShell 5.1 si es necesario. Si tiene Windows 10, ya tiene PowerShell 5.1 instalado.
  2. Instale .NET Framework 4.7.2 o posterior.
  3. Asegúrese de tener instalada la versión más reciente de PowerShellGet. Ejecute los siguientes cmdlets:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force

2. Requisitos previos para Linux y Mac

Se necesita PowerShell Core 6.x o una versión posterior. Consulte este vínculo para obtener instrucciones.

3. Desinstale las versiones existentes de los módulos de PowerShell para Azure Stack Hub.

Antes de instalar la versión requerida, asegúrese de desinstalar los módulos de Azure Resource Manager o de Az PowerShell para Azure Stack Hub instalados previamente. Desinstale los módulos mediante uno de los dos métodos siguientes:

  1. Para desinstalar los módulos de PowerShell de Azure Resource Manager y Az existentes, cierre todas las sesiones de PowerShell activas y ejecute los siguientes cmdlets:

    Get-Module -Name Azure* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
Get-Module -Name Azs.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
Get-Module -Name Az.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue

    Si se produce algún error, como "el módulo ya se está utilizando", cierre las sesiones de PowerShell que usan los módulos y vuelva a ejecutar el script anterior.

  2. Elimine todas las carpetas que empiecen con Azure, Az o Azs. de las carpetas C:\Program Files\WindowsPowerShell\Modules y C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. Al eliminar estas carpetas se quitan todos los módulos de PowerShell existentes.

4. Escenario conectado: Instalación con conectividad a Internet

El módulo Az de Azure Stack funcionará con PowerShell 5.1 o versiones posteriores en una máquina Windows o con PowerShell 6.x o versiones posteriores en una plataforma Linux o macOS. El método de instalación preferido es mediante los cmdlets de PowerShellGet. Este método funciona igual en las plataformas admitidas.

  1. Ejecute el siguiente comando desde una sesión de PowerShell para actualizar PowerShellGet, como mínimo, a la versión 2.2.3.

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force

  2. Para que la actualización surta efecto, cierre la sesión de PowerShell y abra una nueva sesión de PowerShell.

  1. Ejecute el siguiente comando desde una sesión de PowerShell:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-Module -Name Az.BootStrapper -Force
Install-AzProfile -Profile 2020-09-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 2.1.1

  1. Ejecute el siguiente comando desde una sesión de PowerShell:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-Module -Name Az.BootStrapper -Force
Install-AzProfile -Profile 2019-03-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 2.0.2-preview -AllowPrerelease

Nota

La versión 2.0.2 del módulo de Azure Stack Hub supone un cambio importante. Consulte Migración desde AzureRM a Az de Azure PowerShell en Azure Stack Hub para más información.

Advertencia

No puede tener los módulos Azure Resource Manager (AzureRM) y Az instalados para PowerShell 5.1 para Windows al mismo tiempo. Si necesita mantener Azure Resource Manager disponible en el sistema, instale el módulo Az para PowerShell Core 6.x o versiones posteriores. Para ello, instale PowerShell Core 6.x o versiones posteriores y, a continuación, siga estas instrucciones en un terminal de PowerShell Core.

5. Escenario desconectado: Instalación sin conexión a Internet

En un escenario sin conexión, primero hay que descargar los módulos de PowerShell en una máquina que tenga conexión a Internet. A continuación, debe transferirlos al Kit de desarrollo de Azure Stack (ASDK) para instalarlos.

Inicie sesión en un equipo con conexión a Internet y use los scripts siguientes para descargar los paquetes de Azure Resource Manager y Azure Stack Hub, según la versión de Azure Stack Hub.

La instalación consta de cinco pasos:

  1. Instale PowerShell de Azure Stack Hub en una máquina conectada.
  2. Habilite las características adicionales de almacenamiento.
  3. Transporte los paquetes de PowerShell a su estación de trabajo desconectada.
  4. Realice manualmente el arranque del proveedor de NuGet en su estación de trabajo desconectada.
  5. Confirme la instalación de PowerShell.

Instalación de PowerShell de Azure Stack Hub

Azure Stack Hub 2102 o una versión posterior.

Puede usar los módulos de Azure Resource Manager o Az. Para Azure Resource Manager, consulte las instrucciones en Instalación del módulo AzureRM de PowerShell. En el código siguiente se guardan los módulos del repositorio en línea de confianza https://www.powershellgallery.com/.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
Import-Module -Name PackageManagement -ErrorAction Stop

$savedModulesPath = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 1.10.0
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.1.1

Azure Stack Hub 2008 o una versión anterior.

Puede usar los módulos de Azure Resource Manager o Az. Para Azure Resource Manager, consulte las instrucciones en Instalación del módulo AzureRM de PowerShell. En el código siguiente se guardan los módulos del repositorio en línea de confianza https://www.powershellgallery.com/.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
Import-Module -Name PackageManagement -ErrorAction Stop

$savedModulesPath = "<Path that is used to save the packages>"
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 0.10.0-preview
Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.0.2-preview

Nota:

En máquinas sin conexión a Internet, le recomendamos ejecutar el siguiente cmdlet para deshabilitar la colección de datos de telemetría. Puede experimentar una degradación del rendimiento de los cmdlets sin necesidad de deshabilitar la colección de datos de telemetría. Esto solo es aplicable para las máquinas sin conexión a Internet.

Disable-AzDataCollection

Adición de los paquetes a la estación de trabajo

  1. Copie los paquetes descargados en un dispositivo USB.

  2. Inicie sesión en la estación de trabajo desconectada y copie los paquetes desde el dispositivo USB en una ubicación en dicha estación de trabajo.

  3. Realice manualmente el arranque del proveedor de NuGet en su estación de trabajo desconectada. Para obtener instrucciones, consulte Arranque manual del proveedor de NuGet en una máquina no conectada a Internet.

  4. Registre esta ubicación como el repositorio predeterminado e instale los módulos AzureRM y AzureStack desde este repositorio:

 # requires -Version 5
 # requires -RunAsAdministrator
 # requires -Module PowerShellGet
 # requires -Module PackageManagement

 $SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
 $RepoName = "MyNuGetSource"

 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

 Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted

 Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.1.1 -Scope AllUsers

 Install-Module -Name Az -Repository $RepoName -RequiredVersion 1.10.0 -Scope AllUsers

# requires -Version 5
# requires -RunAsAdministrator
# requires -Module PowerShellGet
# requires -Module PackageManagement

$SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
$RepoName = "MyNuGetSource"

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted

Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.0.2-preview -AllowPrerelease -Scope AllUsers

Install-Module -Name Az -Repository $RepoName -RequiredVersion 0.10.0-preview -Scope AllUsers

Confirmación de la instalación de PowerShell

Ejecute el comando siguiente para comprobar la instalación:

Get-Module -Name "Az*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

6. Configuración de PowerShell para usar un servidor proxy

En escenarios donde se necesita un servidor proxy para acceder a Internet, primero configure PowerShell para que use un servidor proxy existente:

  1. Abra un símbolo del sistema de PowerShell con privilegios elevados.

  2. Ejecute los comandos siguientes:

    #To use Windows credentials for proxy authentication
[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials

#Alternatively, to prompt for separate credentials that can be used for #proxy authentication
[System.Net.WebRequest]::DefaultWebProxy.Credentials = Get-Credential

7. Uso del módulo Az

Puede usar los cmdlets y los ejemplos de código basados en Azure Resource Manager. Sin embargo, querrá cambiar el nombre de los módulos y los cmdlets. Los nombres de módulo se han cambiado para que AzureRM y Azure se conviertan en Az e igual para los cmdlets. Por ejemplo, el nombre del módulo AzureRM.Compute ha cambiado a Az.Compute. New-AzureRMVM se ha convertido en New-AzVM y Get-AzureStorageBlob ahora es Get-AzStorageBlob.

Para obtener una explicación más detallada e instrucciones para migrar el script de AzureRM a Az y conocer los cambios importantes en el módulo Az de Azure Stack Hub, consulte Migración desde AzureRM a Az de Azure PowerShell.

Problemas conocidos

Error al instalar los módulos Az

  • Aplicable a: Este problema se aplica a la versión 2002 y versiones posteriores.
  • Causa: Al instalar el módulo, se produce un error. El mensaje de error dice: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. O bien, puede que incluya el texto siguiente: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
  • Corrección: En la misma sesión, ejecute el siguiente cmdlet:
    Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
    Cierre la sesión e inicie una nueva sesión de PowerShell con privilegios elevados.
  • Repetición: Comunes

Cuando la instalación del módulo Az produce de forma incorrecta un error que indica que se requieren derechos de administrador

  • Aplicable a: Este problema se aplica a la versión 2002 y versiones posteriores.
  • Causa: Al instalar el módulo desde un símbolo del sistema con privilegios elevados, se produce un error. El error indica: Administrator rights required.
  • Corrección: Cierre la sesión e inicie una nueva sesión de PowerShell con privilegios elevados. Asegúrese de que no hay ningún módulo Az existente. Se ha cargado el módulo de cuentas en la sesión.
  • Repetición: Comunes

Error del cmdlet New-AzVmss al usar el perfil 2020-09-01-hybrid

  • Aplicable a: Este problema se aplica al perfil 2020-09-01-hybrid.
  • Causa: El cmdlet New-AzVmss no funciona con el perfil 2020-09-01-hybrid.
  • Corrección: Use una plantilla para crear un conjunto de escalado de máquinas virtuales. Puede encontrar un ejemplo de las plantillas de Resource Manager para Azure Stack Hub en el repositorio de GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm, y puede encontrar instrucciones sobre el uso de Resource Manager en Azure Stack Hub con Visual Studio Code.
  • Repetición: Comunes

Error al ejecutar un script de PowerShell

  • Aplicable a: Este problema se aplica a la versión 2002 y versiones posteriores.

  • Causa: al ejecutar scripts o comandos de PowerShell mediante los módulos específicos de Azure Stack Hub necesitará que el script o el comando estén disponibles en el módulo. Puede ver el siguiente error:

    Method 'get_SerializationSettings' in type 'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly 'Microsoft.Azure.Commands.ResourceManager.Common, Version=4.0.0.0, 
Culture=neutral, PublicKeyToken=31bf3856ad364e35' does not have an implementation.

    El módulo actual es el módulo Az de PowerShell, que ha reemplazado al módulo AzureRM. Si intenta ejecutar un script que llama a los comandos de AzureRM cuando está instalado el módulo Az, el script producirá errores. O si intenta ejecutar un script que llama a los comandos de Az cuando está instalado el módulo AzureRM, el script también producirá errores.

  • Solución: desinstale el módulo AzureRM e instale el módulo Az. Para obtener instrucciones, consulte Instalación del módulo Az de PowerShell para Azure Stack Hub. Si usa las herramientas de Azure Stack Hub, use las herramientas de Az. Clone el repositorio de herramientas de la rama az o descárguelas de la rama az. Para obtener instrucciones, consulte Descarga de herramientas de Azure Stack Hub desde GitHub.

  • Repetición: Comunes

Error que se produce con New-AzADServicePrincipal y New-AzADApplication

  • Se aplica a: entornos de Azure Stack con Azure Active Directory (Azure AD).

  • Causa: Azure Active Directory Graph introdujo un cambio importante para restringir el IdentifierUri para que las aplicaciones de Active Directory sean los subdominios de un dominio comprobado en el directorio. Antes del cambio, esta restricción solo regía para las aplicaciones multiinquilino. Ahora esta restricción también rige para las aplicaciones de un solo inquilino. El cambio generará el siguiente error: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

  • Corrección: puede solucionar esta restricción de dos maneras.

    • Tendrá que usar un nombre de entidad de seguridad de servicio que sea un subdominio del inquilino del directorio. Por ejemplo, si el directorio es contoso.onmicrosoft.com, el nombre de entidad de seguridad de servicio debe tener el formato <foo>.contoso.onmicrosoft.com. Use el siguiente cmdlet:

      New-AzADServicePrincipal -Role Owner -DisplayName <foo>.contoso.onmicrosoft.com

      Para obtener más información sobre la identidad y el uso de entidades de servicio con Azure Stack Hub, consulte Introducción a los proveedores de identidades en Azure Stack Hub.

    • Para crear la aplicación de Azure AD, indique un IdentifierUri válido y, a continuación, cree la entidad de servicio que asocia la aplicación mediante el siguiente cmdlet:

      $app=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.onmicrosoft.com
New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId

  • Repetición: Comunes

Pasos siguientes