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

Important

Toutes les versions du module PowerShell Azure Resource Manager (AzureRM) sont obsolètes et hors support. Le module Az PowerShell est désormais le module PowerShell recommandé pour interagir avec Azure et Azure Stack Hub. Cet article explique comment bien démarrer avec le module Az PowerShell. Pour plus d’informations sur la migration vers le module Az PowerShell, consultez Migrer d’AzureRM vers Azure PowerShell Az dans Azure Stack Hub. Pour plus d’informations sur les fonctionnalités accrues des modules Az, qui ont été adoptés dans Azure global, consultez Présentation du module Azure Az PowerShell.

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 compatibles avec Azure Stack Hub à l’aide de PowerShellGet. Vous pouvez installer les modules Az sur les 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.

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. Lorsque vous installez un profil, les modules PowerShell Azure Resource Manager correspondant 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 tout au long des instructions détaillées pour ces scénarios.

Vérifier vos prérequis

Les modules Az sont pris en charge sur Azure Stack Hub avec la mise à jour 2002 ou ultérieure et tous les correctifs logiciels actuels installés. 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 sur Windows, ou PowerShell Core 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. Azure PowerShell n’a aucune autre configuration requise lors de l’exécution sur PowerShell Core.

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

$PSVersionTable.PSVersion

Conditions préalables pour Windows

Pour utiliser Azure PowerShell dans PowerShell 5.1 sur Windows :

1. Mettez à 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 version ultérieure.

3. Vérifiez que vous disposez de la dernière version de PowerShellGet. Exécutez les applets de commande suivantes à partir d'une invite de commandes élevée :

   [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
   

Conditions préalables pour Linux et Mac

PowerShell Core 6.x ou version ultérieure est nécessaire. Suivez le lien pour obtenir des instructions.

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

Avant d’installer la version requise, veillez à désinstaller les modules Azure Stack Hub Azure Resource Manager ou Az PowerShell précédemment installés. Désinstallez les modules à l’aide de l’une des deux méthodes suivantes :

• Pour désinstaller les modules Azure Resource Manager et Az PowerShell existants, 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 telle que « Le module est déjà utilisé », fermez les sessions PowerShell qui utilisent les modules et réexécutez ces applets de commande.

• Si Uninstall-Module ce n’est pas le cas, supprimez tous les dossiers qui commencent par Azure, Az ou Azs des $env:PSModulePath emplacements. 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.

Connecté : installer avec une connectivité Internet

Le module Azure Stack Az fonctionne avec PowerShell 5.1 ou version ultérieure sur une machine Windows, ou PowerShell 6.x ou version ultérieure 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 à partir d’une session PowerShell pour mettre à jour PowerShellGet vers une version minimale de la version 2.2.3 :

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

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

3. Exécutez les commandes suivantes 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 les modules AzureStack PowerShell :

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Déconnecté : Installer sans connexion Internet

Dans un scénario déconnecté, vous téléchargez d’abord les modules PowerShell sur un ordinateur disposant d’une connectivité Internet. Ensuite, vous les transférez vers le Kit de développement Azure Stack (ASDK) pour l’installation.

Connectez-vous à un ordinateur disposant d’une connectivité Internet et utilisez les scripts suivants pour télécharger les packages Azure Resource Manager et Azure Stack Hub, en fonction de votre version d’Azure Stack Hub.

L’installation comporte cinq étapes :

1. Installez Azure Stack Hub PowerShell sur une machine connectée.
2. Activer des fonctionnalités de stockage supplémentaires.
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ée.
5. Confirmez l’installation de PowerShell.

Installer Azure Stack Hub PowerShell

1. Le code suivant installe les modules Az à partir du dépôt en ligne digne de confiance :

   [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 l’applet de commande Disable-AzDataCollection pour désactiver la collecte de données de télémétrie. Sinon, vous pouvez rencontrer une dégradation des performances des applets de commande. Cela s’applique uniquement aux machines sans connexion Internet.

Ajouter vos packages à votre station de travail

1. Copiez les packages téléchargés sur un périphérique USB.

2. Connectez-vous à la station de travail déconnectée et 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ée. Pour obtenir des instructions, consultez Démarrer manuellement le fournisseur NuGet sur un ordinateur qui n’est pas connecté à Internet.

4. Définissez cet emplacement comme référentiel par défaut et installez les modules AzureRM et AzureStack à partir de ce référentiel :

    # 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. Installer les modules AzureStackL

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

Confirmer l’installation de PowerShell

Confirmez l’installation en exécutant la commande suivante :

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

Configurer PowerShell pour utiliser un serveur proxy

Dans les scénarios nécessitant un serveur proxy pour accéder à Internet, vous devez d’abord configurer PowerShell pour utiliser 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
   

Utiliser le module Az

Vous pouvez toujours utiliser les applets de commande et les exemples de code basés sur les modules AzureRM. Toutefois, vous devez modifier le nom des modules et des applets de commande. Les noms des modules ont été modifiés de telle sorte qu’Azure AzureRM devienne Azet le même pour les applets de commande. Par exemple, le AzureRM.Compute module a été renommé en Az.Compute. New-AzureRMVM est New-AzVM, et Get-AzureStorageBlob est maintenant Get-AzStorageBlob.

Pour une discussion et des conseils plus approfondis sur le déplacement de scripts AzureRM vers Az et des informations sur les modifications majeures 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

• Applicable : ce problème s’applique à 2002 et versions ultérieures
• Cause : lors de l’installation du module, une erreur est levée. Le message d’erreur commence : Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. ou 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 : exécutez l’applet de commande suivante dans la même session :
  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

• Applicable : ce problème s’applique à 2002 et versions ultérieures
• Cause : lors de l’installation du module à partir d’une invite avec élévation de privilèges, une erreur est levée. L’erreur indique Administrator rights required.
• Correction : fermez votre session et 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

L'applet de commande New-AzVmss échoue avec le profil hybride 2020-09-01

• Applicable : ce problème s’applique au profil hybride 2020-09-01-hybrid.
• Cause : l’applet de commande New-AzVmss ne fonctionne pas avec le profil hybride 2020-09-01.
• Remédiation : utilisez un modèle pour créer un groupe de machines virtuelles. Vous trouverez un exemple de modèles Azure Stack Hub Resource Manager dans le référentiel GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm et vous trouverez des instructions sur l’utilisation des gestionnaires de ressources Azure Stack Hub avec Visual Studio Code.
• Occurrence : Courant

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

• Applicable : ce problème s’applique à 2002 et versions ultérieures.

• Cause : lors de l’exécution de scripts ou de commandes PowerShell à l’aide des modules spécifiques à Azure Stack Hub, vous aurez besoin que votre script ou commande soit disponible dans le module. L’erreur suivante peut s’afficher :

  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 actuel est le module PowerShell Az, qui a remplacé le module AzureRM PowerShell. Si vous tentez d’exécuter un script qui appelle des commandes AzureRM lorsque le module Az est installé, votre script génère des erreurs. Ou si vous tentez d’exécuter un script qui appelle des commandes Az lorsque 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 Le module Installer PowerShell Az pour Azure Stack Hub. Si vous utilisez Azure Stack Hub Tools, utilisez les outils Az. Clonez le référentiel d’outils à partir de la branche az ou téléchargez le 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 l’ID Microsoft Entra.

• Cause : Azure Active Directory Graph a introduit un changement significatif pour restreindre les applications Active Directory aux sous-domaines du domaine vérifié dans l’annuaire. Avant la modification, cette restriction n'a été appliquée que pour les applications multi-locataires. Maintenant, cette restriction s’applique également aux applications monolocataires. La modification entraîne 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 devez utiliser un nom principal du service qui est un sous-domaine du locataire de l'annuaire. Par exemple, si le répertoire est contoso.onmicrosoft.com, le nom du principal de service doit être de la forme .<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 de 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 une valeur valide IdentifierUri , 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 »

• Applicable : ce problème s’applique à toutes les versions prises en charge.
• Cause : une erreur d’authentification SharedTokenCacheCredential a échoué 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 d’AzAccounts 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