Instalar módulos Az y Azure Stack de PowerShell para Azure Stack Hub

Importante

Todas las versiones del módulo de PowerShell de Azure Resource Manager (AzureRM) están obsoletas y no son compatibles. El módulo Az powerShell es ahora el módulo de PowerShell recomendado para interactuar con Azure y Azure Stack Hub. En este artículo se describe cómo empezar a trabajar con el módulo Az powerShell. Para más información sobre cómo migrar al módulo Az PowerShell, consulte Migración de AzureRM a Azure PowerShell Az en Azure Stack Hub. Para más información sobre la mayor funcionalidad de los módulos Az, que se han adoptado en Azure global, consulte Introducción al módulo de Azure Az PowerShell.

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 los módulos de administrador de Azure PowerShell Az y compatibles de Azure Stack Hub mediante PowerShellGet. Puede instalar los módulos Az en plataformas Windows, macOS y Linux.

También puede ejecutar los 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.

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 API es un conjunto de módulos de PowerShell de Azure Resource Manager con versiones de API específicas. Cada plataforma en 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. Al instalar un perfil, se instalan los módulos de PowerShell de Azure Resource Manager que corresponden al perfil especificado.

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

Comprobación de los requisitos previos

Los módulos Az se admiten en Azure Stack Hub con la actualización 2002 o posterior y con todas las correcciones actuales instaladas. Consulte las notas de la versión de Azure Stack Hub para más información.

Los módulos Az de Azure PowerShell funcionan con PowerShell 5.1 o posterior en Windows, o PowerShell Core 6.x y versiones posteriores en todas las plataformas. Debe instalar la versión más reciente de PowerShell Core disponible para el sistema operativo. Azure PowerShell no tiene ningún otro requisito cuando se ejecuta en PowerShell Core.

Para comprobar la versión de PowerShell, ejecute el siguiente 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 está en Windows 10, ya tiene Instalado PowerShell 5.1.

2. Instale .NET Framework 4.7.2 o posterior.

3. Asegúrese de que tiene la versión más reciente de PowerShellGet. Ejecute los siguientes cmdlets desde 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
   

Requisitos previos para Linux y Mac

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

Desinstalación de versiones existentes de los módulos de PowerShell de Azure Stack Hub

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

• Para desinstalar los módulos existentes de Azure Resource Manager y Az PowerShell, 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 un error como "El módulo ya está en uso", cierre las sesiones de PowerShell que usan los módulos y vuelva a ejecutar estos cmdlets.

• Si Uninstall-Module no se realizó correctamente, elimine todas las carpetas que comienzan con Azure, Az o Azs de las $env:PSModulePath localizaciones. 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 los módulos existentes de Azure PowerShell.

Conectado: instalación con conectividad a Internet

El módulo Az de Azure Stack funciona con PowerShell 5.1 o posterior en una máquina Windows, o PowerShell 6.x o posterior en una plataforma Linux o macOS. El uso de los cmdlets de PowerShellGet es el método de instalación preferido. Este método funciona del mismo modo en las plataformas admitidas.

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

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
   

2. Cierre la sesión de PowerShell y abra una nueva sesión de PowerShell para que la actualización pueda surtir efecto.

3. Ejecute los siguientes comandos 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
   

Desconectado: instalar sin conexión a Internet

En un escenario desconectado, primero descargará los módulos de PowerShell en una máquina que tenga conectividad a Internet. A continuación, los transferirá al Kit de desarrollo de Azure Stack (ASDK) para su instalación.

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

La instalación tiene cinco pasos:

1. Instale PowerShell de Azure Stack Hub en una máquina conectada.
2. Habilite características de almacenamiento adicionales.
3. Transporte de los paquetes de PowerShell a la estación de trabajo desconectada.
4. Inicie manualmente el 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. El código siguiente instala los módulos Az desde el repositorio 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 las máquinas sin conexión a Internet, se recomienda ejecutar el cmdlet Disable-AzDataCollection para deshabilitar la recopilación de datos de telemetría. De lo contrario, puede experimentar una degradación del funcionamiento de los cmdlets. Esto solo es aplicable a las máquinas sin conexión a Internet.

Añade tus paquetes a tu 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 del dispositivo USB en una ubicación de la estación de trabajo.

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

4. Registre esta ubicación como repositorio predeterminado e instale los AzureRM módulos 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. Instalación de los módulos de AzureStackL

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

Confirmación de la instalación de PowerShell

Para confirmar la instalación, ejecute el siguiente comando:

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

Configuración de PowerShell para usar un servidor proxy

En escenarios que requieren un servidor proxy para acceder a Internet, primero debe configurar PowerShell para que use un servidor proxy existente:

1. Abra PowerShell con permisos 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
   

Uso del módulo Az

Todavía puede usar los cmdlets y ejemplos de código basados en módulos de AzureRM. Sin embargo, debe cambiar el nombre de los módulos y los cmdlets. Los nombres de módulo se cambiaron de forma que AzureRM y Azure se convierten en Az, y lo mismo para los cmdlets. Por ejemplo, se ha cambiado el nombre del AzureRM.Compute módulo a Az.Compute. New-AzureRMVM es New-AzVM, y Get-AzureStorageBlob es ahora Get-AzStorageBlob.

Para obtener una explicación más detallada e instrucciones para mover scripts de AzureRM a Az e información sobre los cambios importantes en el módulo Az de Azure Stack Hub, consulte Migración de AzureRM a Azure PowerShell Az.

Problemas conocidos

Error al instalar los módulos Az

• Aplicable: Este problema se aplica a 2002 y posteriores
• Causa: al instalar el módulo, se produce un error. El mensaje de error comienza: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. O el mensaje de error puede incluir el siguiente texto: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Solución: Ejecute el siguiente cmdlet en la misma sesión:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Cierre la sesión e inicie una nueva sesión de PowerShell con privilegios elevados.
• Ocurrencia: Común

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

• Aplicable: Este problema se aplica a 2002 y posteriores
• Causa: Al instalar el módulo desde un prompt elevado, se lanza un error. El error indica: Administrator rights required.
• Solución: Cierre la sesión e inicie una nueva sesión PowerShell elevada. Asegúrese de que no hay ningún módulo Az existente. Se ha cargado el módulo de cuentas en la sesión.
• Ocurrencia: Común

Se produce un error en el cmdlet New-AzVmss al usar el perfil 2020-09-01-hybrid

• Aplicable: este problema se aplica al perfil 2020-09-01-híbrido.
• Causa: El cmdlet New-AzVmss no funciona con el perfil 2020-09-01-hybrid.
• Corrección: use una plantilla para crear un conjunto de escalamiento de máquinas virtuales. Puede encontrar un ejemplo de las plantillas de Resource Manager de Azure Stack Hub en el repositorio de GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm y puede encontrar instrucciones sobre el uso de administradores de recursos de Azure Stack Hub con Visual Studio Code.
• Ocurrencia: Común

Error producido al ejecutar un script de PowerShell

• Aplicable: Este problema se aplica a 2002 y posteriores.

• Causa: al ejecutar scripts o comandos de PowerShell mediante los módulos específicos de Azure Stack Hub, necesitará el script o comando para que esté disponible en el módulo. Es posible que vea 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 de PowerShell. Si intenta ejecutar un script que llama a los comandos de AzureRM cuando se instala el módulo Az, el script producirá errores. O bien, si intenta ejecutar un script que llama a los comandos de Az cuando se instala el módulo AzureRM, el script producirá errores.

• Correcció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 desde la rama az o descargue el AzureStack-Tools desde la rama az . Para obtener instrucciones, consulte Descarga de herramientas de Azure Stack Hub desde GitHub.

• Ocurrencia: Común

Error producido con New-AzADServicePrincipal y New-AzADApplication

• Aplicable: entornos de Azure Stack mediante el identificador de Entra de Microsoft.

• Causa: Azure Active Directory Graph introdujo un cambio importante para restringir que las aplicaciones de Active Directory sean subdominios de un dominio verificado en el directorio. Antes del cambio, esta restricción solo se aplicaba a las aplicaciones multiinquilino. Ahora esta restricción también se aplica a las aplicaciones de un solo inquilino. El cambio producirá 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.

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

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

    Para 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 para Azure Stack Hub.

  • Cree la aplicación Microsoft Entra proporcionando un valor válido IdentifierUri, y a continuación, cree la entidad de servicio asociada a la aplicación utilizando el siguiente cmdlet:

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

• Ocurrencia: Común

Error: "Error de autenticación SharedTokenCacheCredential"

• Aplicable: Este problema se aplica a todas las versiones compatibles.
• Causa: se produce un error de autenticación 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.
• Ocurrencia: Común

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