Instalación de módulos Az y Azure Stack de PowerShell para Azure Stack Hub

Versión de Azure Stack Hub	Versión de PowerShell de AzureStack
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

Para más información sobre los módulos de AzureStack, consulte PSGallery.

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

No habrá nuevas versiones de módulos de recursos de Azure. Los módulos Azure Resource Modules solo tienen soporte técnico para correcciones críticas. En el futuro, solo habrá versiones 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 en un símbolo del sistema con privilegios elevados:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   
   powershell -noprofile
   $PSVersionTable
   Uninstall-Module PowershellGet -AllVersions -Force -Confirm:$false
   Get-module PowershellGet
   Find-module PowershellGet
   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. Si Uninstall-Module no se ha hecho correctamente, elimine todas las carpetas que comienzan por Azure, Az o Azs. de las ubicaciones $env:PSModulePath. Para Windows PowerShell, las ubicaciones pueden ser C:\Program Files\WindowsPowerShell\Modules y C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. Para PowerShell Core, las ubicaciones pueden ser C:\Program Files\PowerShell\7\Modules y C:\Users\{yourusername}\Documents\PowerShell\Modules. Al eliminar estas carpetas se quitan todos los módulos de Azure 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.

3. Ejecute lo siguiente para instalar módulos de Az.

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module -Name Az.BootStrapper -Force
   Install-AzProfile -Profile 2020-09-01-hybrid -Force
   

4. Instale los módulos de PowerShell de AzureStack.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

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

1. Puede usar los módulos AzureRM o Az . El código siguiente guarda los módulos Az del repositorio https://www.powershellgallery.com/en línea de confianza .

   [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 2.0.1
   

2. Una vez instalados los módulos Az, continúe con la instalación de los módulos De AzureStack.

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.4.0
   

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
   

5. Instale los módulos Az.

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

6. Instale los módulos de AzureStack.

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -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 módulos de AzureRM. 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

• Aplicable: entornos de Azure Stack mediante Microsoft Entra ID.

• 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.

  • Cree la aplicación Microsoft Entra que proporcione un valor válido IdentifierUri 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

Error: "Error de autenticación de SharedTokenCacheCredential"

• Aplicable a: este problema se aplica a todas las versiones admitidas.
• Causa: Se produce un error de autenticación de SharedTokenCacheCredential al tener varias versiones de AzAccounts instaladas con la versión 2.1.1 del módulo de PowerShell de Azure Stack Hub.
• Corrección: quite todas las versiones de AzAccounts e instale solo la versión 2.2.8 de AzAccounts compatible.
• Repetición: Comunes

Pasos siguientes

• Descarga de herramientas de Azure Stack Hub desde GitHub
• Configuración del entorno de PowerShell del usuario de Azure Stack Hub
• Configuración del entorno de PowerShell del operador de Azure Stack Hub
• Administración de perfiles de la versión de API en Azure Stack Hub