Installer les modules PowerShell Az et Azure Stack pour Azure Stack Hub

Version d’Azure Stack Hub	Version d’AzureStack PowerShell
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

Pour plus d’informations sur les modules AzureStack, consultez PSGallery.

Cet article explique comment installer les modules d’administrateur Azure PowerShell Az et Azure Stack Hub compatibles avec PowerShellGet. Les modules Az peuvent être installés sur des plateformes Windows, macOS et Linux.

Vous pouvez également exécuter les modules Az pour Azure Stack Hub dans un conteneur Docker. Pour obtenir des instructions, consultez Utiliser Docker pour exécuter PowerShell pour Azure Stack Hub.

Si vous souhaitez installer le module PowerShell Resource Modules (AzureRM) pour Azure Stack Hub, consultez Installer le module PowerShell AzureRM pour Azure Stack Hub.

Important

Il n’y aura pas de nouvelles versions de module Azure Resource Modules. Les modules Azure Resource Modules ne sont pris en charge que pour les correctifs critiques. À l’avenir, il n’y aura que des versions Az pour Azure Stack Hub.

Vous pouvez utiliser des profils d’API pour spécifier les points de terminaison compatibles pour les fournisseurs de ressources Azure Stack Hub.

Les profils d’API permettent de gérer les différences de version entre Azure et Azure Stack Hub. Un profil de version d’API est un ensemble de modules PowerShell Azure Resource Manager avec des versions d’API spécifiques. Chaque plateforme cloud a un ensemble de profils de version d’API pris en charge. Par exemple, Azure Stack Hub prend en charge une version de profil spécifique telle que 2020-09-01-hybrid. Quand vous installez un profil, les modules PowerShell Azure Resource Manager qui correspondent au profil spécifié sont installés.

Vous pouvez installer des modules PowerShell Az compatibles avec Azure Stack Hub dans des scénarios connectés à Internet, partiellement connectés ou déconnectés. Cet article vous guide dans les instructions détaillées de ces scénarios.

1. Vérifier la configuration requise

Les modules Az sont pris en charge sur Azure Stack Hub avec la Mise à jour 2002 ou ultérieure et avec les correctifs logiciels actuels. Pour plus d’informations, consultez les notes de publication d’Azure Stack Hub.

Les modules Azure PowerShell Az fonctionnent avec PowerShell 5.1 ou version ultérieure sous Windows, ou avec PowerShell 6.x et versions ultérieures sur toutes les plateformes. Vous devez installer la dernière version de PowerShell Core disponible pour votre système d’exploitation. Il n’y a pas d’autres exigences à remplir pour exécuter Azure PowerShell sur PowerShell Core.

Pour vérifier votre version de PowerShell, exécutez la commande :

$PSVersionTable.PSVersion

Prérequis pour Windows

Pour utiliser Azure PowerShell dans PowerShell 5.1 sur Windows :

1. Mettrez à jour vers Windows PowerShell 5.1 si nécessaire. Si vous êtes sur Windows 10, PowerShell 5.1 est déjà installé.

2. Installez .NET Framework 4.7.2 ou ultérieur.

3. Veillez à disposer de la dernière version de PowerShellGet. Exécutez les cmdlets suivantes à partir d’une invite de commandes avec élévation de privilèges :

   [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. Prérequis pour Linux et Mac

PowerShell Core 6.x ou version ultérieure est nécessaire. Pour obtenir des instructions, suivez le lien

3. Désinstaller les versions existantes des modules Azure Stack Hub PowerShell

Avant d’installer la version nécessaire, vérifiez que vous avez désinstallé les modules Azure Stack Hub Azure Resource Manager ou Az PowerShell. Désinstallez les modules en appliquant l’une des deux méthodes suivantes :

1. Pour désinstaller les modules PowerShell Az et Azure Resource Manager, fermez toutes les sessions PowerShell actives et exécutez les applets de commande suivantes :

   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 vous rencontrez une erreur du type « Le module est déjà en cours d’utilisation », fermez les sessions PowerShell qui utilisent les modules, puis réexécutez le script ci-dessus.

2. Si Uninstall-Module échoue, supprimez tous les dossiers qui commencent par Azure, Az ou Azs. des emplacements $env:PSModulePath. Pour Windows PowerShell, les emplacements peuvent être C:\Program Files\WindowsPowerShell\Modules et C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. Pour PowerShell Core, les emplacements peuvent être C:\Program Files\PowerShell\7\Modules et C:\Users\{yourusername}\Documents\PowerShell\Modules. La suppression de ces dossiers supprime tous les modules Azure PowerShell existants.

4. Connecté : Installer avec une connexion Internet

Le module Azure Stack Az fonctionne avec PowerShell 5.1 ou ultérieur sur un ordinateur Windows, ou PowerShell 6.x ou ultérieur sur une plateforme Linux ou macOS. L’utilisation des applets de commande PowerShellGet est la méthode d’installation par défaut. Cette méthode fonctionne de la même façon sur les plateformes prises en charge.

1. Exécutez la commande suivante dans une session PowerShell pour mettre à jour PowerShellGet vers la version 2.2.3 au minimum

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

2. Fermez votre session PowerShell, puis ouvrez-en une nouvelle pour que la mise à jour puisse prendre effet.

3. Exécutez la commande suivante pour installer les modules Az.

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

4. Installez des modules AzureStack PowerShell.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Avertissement

Vous ne pouvez pas avoir en même temps les modules Azure Resource Manager (AzureRM) et Az installés pour PowerShell 5.1 pour Windows. Si vous devez conserver Azure Resource Manager sur votre système, installez le module Az pour PowerShell Core 6.x ou version ultérieure. Pour cela, installez PowerShell Core 6.x ou ultérieur et suivez ces instructions dans un terminal PowerShell Core.

5. Déconnecté : Installer sans connexion à Internet

Dans un scénario hors connexion, téléchargez d’abord les modules PowerShell sur un ordinateur qui dispose d’une connexion Internet. Transférez-les ensuite vers le Kit de développement Azure Stack (ASDK) pour l’installation.

Connectez-vous à un ordinateur disposant d’une connexion Internet et utilisez le script suivant pour télécharger les packages Azure Resource Manager et Azure Stack Hub, selon votre version d’Azure Stack Hub.

L’installation comporte cinq étapes :

1. Installez Azure Stack Hub PowerShell sur une machine connectée.
2. Activez les fonctionnalités de stockage supplémentaire.
3. Transportez les packages PowerShell vers votre station de travail déconnectée.
4. Démarrez manuellement le fournisseur NuGet sur votre station de travail déconnecté.
5. Confirmez l’installation de PowerShell.

Installer Azure Stack Hub PowerShell

1. Vous pouvez utiliser des modules AzureRM ou Az . Le code suivant enregistre les modules Az à partir d’un dépôt https://www.powershellgallery.com/en ligne fiable .

   [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. Une fois les modules Az installés, procédez à l’installation des modules AzureStack.

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

Remarque

Sur les ordinateurs sans connexion Internet, nous vous recommandons d’exécuter la cmdlet suivante pour désactiver la collecte des données de télémétrie. Les performances des cmdlets pourraient se dégrader si la collecte des données de télémétrie n’est pas désactivée. Cela s’applique uniquement aux ordinateurs sans connexion Internet

Disable-AzDataCollection

Ajouter vos packages à votre station de travail

1. Copiez les packages téléchargés sur un appareil USB.

2. Connectez-vous à la station de travail déconnectée, puis copiez les packages du périphérique USB vers un emplacement sur la station de travail.

3. Démarrez manuellement le fournisseur NuGet sur votre station de travail déconnecté. Pour plus d’instructions, consultez la section Démarrage manuel du fournisseur NuGet sur un ordinateur qui n’est pas connecté à Internet.

4. Inscrivez cet emplacement en tant que dépôt par défaut, puis installez les modules AzureRM et AzureStack à partir de ce dépôt :

    # 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. Installez les modules Az.

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

6. Installez les modules AzureStack.

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

Confirmer l’installation de PowerShell

Vérifiez l’installation en exécutant la commande suivante :

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

6. Configurer PowerShell pour l’utilisation d’un serveur proxy

Dans les scénarios qui requièrent un serveur proxy pour accéder à Internet, commencez par configurer PowerShell pour l’utilisation d’un serveur proxy existant :

1. Ouvrez une invite PowerShell avec élévation de privilèges.

2. Exécutez les commandes suivantes :

   #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. Utiliser le module Az

Vous pouvez utiliser les applets de commande et les exemples de code basés sur les modules AzureRM. Toutefois, vous pouvez changer le nom des modules et des applets de commande. Les noms de module ont été changés pour que AzureRM et Azure deviennent Az, et il en va de même pour les applets de commande. Par exemple, le module AzureRM.Compute a été renommé Az.Compute. New-AzureRMVM est devenu New-AzVM et Get-AzureStorageBlob est désormais Get-AzStorageBlob.

Pour une discussion plus approfondie et des conseils sur le déplacement du script AzureRM vers Az et sur les changements cassants dans le module Az d’Azure Stack Hub, consultez Migrer d’AzureRM vers Azure PowerShell Az.

Problèmes connus

Erreur générée au moment de l’installation des modules Az

• Champ d’application : Ce problème concerne les versions 2002 et ultérieures
• Cause : Au moment de l’installation du module, une erreur est générée. Le message d’erreur indique : Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Sinon, le message d’erreur peut inclure le texte suivant : PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Correction : Dans la même session, exécutez l’applet de commande suivante :
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Fermez votre session, puis démarrez une nouvelle session PowerShell avec élévation de privilèges.
• Occurrence : Courant

Au moment de l’installation du module Az, une erreur relative aux droits d’administrateur est générée à tort

• Champ d’application : Ce problème concerne les versions 2002 et ultérieures
• Cause : Quand le module est installé à partir d’une invite de commandes avec élévation de privilèges, une erreur est générée. L’erreur indique Administrator rights required.
• Correction : Fermez votre session, puis démarrez une nouvelle session PowerShell avec élévation de privilèges. Vérifiez qu’il n’existe aucun module Az.Accounts chargé dans la session.
• Occurrence : Courant

Échec de la cmdlet New-AzVmss lors de l’utilisation du profil 2020-09-01-hybrid

• Champ d’application : ce problème s’applique au profil 2020-09-01-hybrid.
• Cause : la cmdlet New-AzVmss ne fonctionne pas avec le profil 2020-09-01-hybrid.
• Correction : utilisez un modèle pour créer un groupe de machines virtuelles identiques. Vous trouverez un exemple des modèles Resource Manager d’Azure Stack Hub dans le référentiel GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm. Vous trouverez également des instructions sur l’utilisation de Resource Manager Azure Stack Hub avec Visual Studio Code.
• Occurrence : Courant

Erreur générée lors de l’exécution d’un script PowerShell

• Champ d’application : Ce problème concerne les versions 2002 et ultérieures.

• Cause : Lors de l’exécution de scripts ou de commandes PowerShell à l’aide des modules spécifiques à Azure Stack Hub, votre script ou votre commande doit être disponible dans le module. L'erreur suivante peut apparaître :

  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.
  

  Le module actif est le module PowerShell Az, qui a remplacé le module PowerShell AzureRM. Si vous tentez d’exécuter un script qui appelle des commandes AzureRM quand le module Az est installé, votre script génère des erreurs. De même, si vous tentez d’exécuter un script qui appelle des commandes Az quand le module AzureRM est installé, votre script génère des erreurs.

• Correction : Désinstallez le module AzureRM et installez le module Az. Pour obtenir des instructions, consultez Installer le module PowerShell Az pour Azure Stack Hub. Si vous utilisez les outils Azure Stack Hub, utilisez les outils Az. Clonez le dépôt d’outils à partir de la branche az ou téléchargez AzureStack-Tools à partir de la branche az. Pour obtenir des instructions, consultez Télécharger les outils Azure Stack Hub à partir de GitHub.

• Occurrence : Courant

Erreur levée avec New-AzADServicePrincipal et New-AzADApplication

• Applicable : environnements Azure Stack utilisant Microsoft Entra ID.

• Cause : Azure Active Directory Graph a introduit un changement cassant afin de restreindre le IdentifierUri pour les applications Active Directory aux sous-domaines d’un domaine vérifié dans l’annuaire. Avant le changement, cette restriction était appliquée uniquement pour les applications mutualisées. Désormais, cette restriction s’applique également aux applications à locataire unique. Le changement produit l’erreur suivante : Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• Correction : vous pouvez contourner cette restriction de deux manières.

  • Vous pouvez utiliser un nom de principal de service correspondant à un sous-domaine du locataire d’annuaire. Par exemple, si l’annuaire est contoso.onmicrosoft.com, le nom du principal de service doit être au format <foo>.contoso.onmicrosoft.com. Utilisez l’applet de commande suivante :

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

    Pour plus d’informations sur l’identité et l’utilisation des principaux de service avec Azure Stack Hub, consultez Vue d’ensemble des fournisseurs d’identité pour Azure Stack Hub.

  • Créez l’application Microsoft Entra en fournissant un valideIdentifierUri, puis créez le principal de service associant l’application à l’aide de l’applet de commande suivante :

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

• Occurrence : Courant

Erreur : « Échec de l’authentification SharedTokenCacheCredential »

• Champ d’application : Ce problème s’applique à toutes les versions prises en charge.
• Cause : une erreur Échec de l’authentification SharedTokenCacheCredential se produit lors de l’installation de plusieurs versions d’AzAccounts avec le module PowerShell Azure Stack Hub version 2.1.1.
• Correction : supprimez toutes les versions d’AzAccounts et installez uniquement la version 2.2.8 prise en charge.
• Occurrence : Courant

Étapes suivantes

• Télécharger les outils Azure Stack Hub à partir de GitHub
• Configurer l’environnement PowerShell de l’utilisateur Azure Stack Hub
• Configurer l’environnement PowerShell de l’opérateur Azure Stack Hub
• Gérer les profils de version d’API dans Azure Stack Hub