PowerShell Az- en Azure Stack-modules voor Azure Stack Hub installeren

Belangrijk

Alle versies van de PowerShell-module Azure Resource Manager (AzureRM) zijn verouderd en worden niet ondersteund. De Az PowerShell-module is nu de aanbevolen PowerShell-module voor interactie met Azure en Azure Stack Hub. In dit artikel wordt beschreven hoe u aan de slag gaat met de Az PowerShell-module. Zie Migrate from AzureRM to Azure PowerShell Az in Azure Stack Hub (Migreren van AzureRM naar Azure PowerShell Az in Azure Stack Hub) voor informatie over het migreren naar de Az PowerShell-module. Zie Inleiding tot de Azure Az PowerShell-module voor meer informatie over de verbeterde functionaliteit van de Az-modules die zijn geïmplementeerd in de wereldwijde Azure-module.

Versie van Azure Stack Hub	AzureStack PowerShell-versie
2102	2.1.1
2108	2.2.0
2206	2.3.0
2301+	2.4.0

Zie de PSGallery voor meer informatie over AzureStack-modules.

In dit artikel wordt uitgelegd hoe u de Azure PowerShell Az en compatibele Azure Stack Hub-beheerdersmodules installeert met behulp van PowerShellGet. U kunt de Az-modules installeren op Windows-, macOS- en Linux-platforms.

U kunt ook de Az-modules voor Azure Stack Hub uitvoeren in een Docker-container. Zie Docker gebruiken om PowerShell voor Azure Stack Hub uit te voeren voor instructies.

U kunt API-profielen gebruiken om de compatibele eindpunten voor de Azure Stack Hub-resourceproviders op te geven. API-profielen bieden een manier om versieverschillen tussen Azure en Azure Stack Hub te beheren. Een API-versieprofiel is een set Azure Resource Manager PowerShell-modules met specifieke API-versies. Elk cloudplatform heeft een set ondersteunde API-versieprofielen. Azure Stack Hub ondersteunt bijvoorbeeld een specifieke profielversie, zoals 2020-09-01-hybride. Wanneer u een profiel installeert, worden de Azure Resource Manager PowerShell-modules die overeenkomen met het opgegeven profiel geïnstalleerd.

U kunt Azure Stack Hub-compatibele PowerShell Az-modules installeren in scenario's met internetverbinding, gedeeltelijk verbonden of niet-verbonden scenario's. In dit artikel worden de gedetailleerde instructies voor deze scenario's beschreven.

Uw vereisten verifiëren

Az-modules worden ondersteund in Azure Stack Hub met update 2002 of hoger en met alle huidige hotfixes geïnstalleerd. Zie de opmerkingen bij de release van Azure Stack Hub voor meer informatie.

De Azure PowerShell Az-modules werken met PowerShell 5.1 of hoger in Windows of PowerShell Core 6.x en hoger op alle platforms. Installeer de nieuwste versie van PowerShell Core die beschikbaar is voor uw besturingssysteem. Azure PowerShell heeft geen andere vereisten wanneer deze worden uitgevoerd op PowerShell Core.

Voer de volgende opdracht uit om uw PowerShell-versie te controleren:

$PSVersionTable.PSVersion

Vereisten voor Windows

Azure PowerShell gebruiken in PowerShell 5.1 in Windows:

1. Werk indien nodig bij naar Windows PowerShell 5.1 . Als u Windows 10 gebruikt, is PowerShell 5.1 al geïnstalleerd.

2. Installeer .NET Framework 4.7.2 of hoger.

3. Zorg ervoor dat u de nieuwste versie van PowerShellGet hebt. Voer de volgende cmdlets uit vanaf een prompt met verhoogde bevoegdheid:

   [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
   

Vereisten voor Linux en Mac

PowerShell Core 6.x of nieuwere versie is nodig. Volg de koppeling voor instructies.

Bestaande versies van de Azure Stack Hub PowerShell-modules verwijderen

Voordat u de vereiste versie installeert, moet u ervoor zorgen dat u eerder geïnstalleerde Azure Stack Hub Azure Resource Manager of Az PowerShell-modules verwijdert. Verwijder de modules met een van de volgende twee methoden:

• Als u de bestaande Azure Resource Manager- en Az PowerShell-modules wilt verwijderen, sluit u alle actieve PowerShell-sessies en voert u de volgende cmdlets uit:

  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
  

  Als er een fout optreedt, zoals 'De module is al in gebruik', sluit u de PowerShell-sessies die gebruikmaken van de modules en voert u deze cmdlets opnieuw uit.

• Als Uninstall-Module dit niet lukt, verwijdert u alle mappen die beginnen met Azure, Az of Azs vanaf de $env:PSModulePath locaties. Voor Windows PowerShell kunnen de locaties C:\Program Files\WindowsPowerShell\Modules en C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules zijn. Voor PowerShell Core kunnen de locaties mogelijk C:\Program Files\PowerShell\7\Modules en C:\Users\{yourusername}\Documents\PowerShell\Modules zijn. Als u deze mappen verwijdert, worden alle bestaande Azure PowerShell-modules verwijderd.

Verbonden: installeren met internetverbinding

De Azure Stack Az-module werkt met PowerShell 5.1 of hoger op een Windows-computer, powerShell 6.x of hoger op een Linux- of macOS-platform. Het gebruik van de PowerShellGet-cmdlets is de voorkeursmethode voor de installatie. Deze methode werkt op dezelfde manier op de ondersteunde platforms.

1. Voer de volgende opdracht uit vanuit een PowerShell-sessie om PowerShellGet bij te werken naar minimaal versie 2.2.3:

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

2. Sluit uw PowerShell-sessie en open vervolgens een nieuwe PowerShell-sessie, zodat de update van kracht kan worden.

3. Voer de volgende opdrachten uit om Az-modules te installeren:

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

4. Installeer de AzureStack PowerShell-modules:

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Verbinding verbroken: installeren zonder internetverbinding

In een niet-verbonden scenario downloadt u eerst de PowerShell-modules naar een computer met internetverbinding. Vervolgens brengt u ze over naar de Azure Stack Development Kit (ASDK) voor installatie.

Meld u aan bij een computer met internetverbinding en gebruik de volgende scripts om de Azure Resource Manager- en Azure Stack Hub-pakketten te downloaden, afhankelijk van uw versie van Azure Stack Hub.

De installatie heeft vijf stappen:

1. Installeer Azure Stack Hub PowerShell op een verbonden computer.
2. Schakel extra opslagfuncties in.
3. Transporteer de PowerShell-pakketten naar uw niet-verbonden werkstation.
4. Bootstrap de NuGet-provider handmatig op uw niet-verbonden werkstation.
5. Bevestig de installatie van PowerShell.

Azure Stack Hub PowerShell installeren

1. Met de volgende code worden Az-modules geïnstalleerd vanuit de betrouwbare onlineopslagplaats:

   [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. Nadat de Az-modules zijn geïnstalleerd, gaat u verder met het installeren van de AzureStack-modules:

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

Opmerking

Op computers zonder internetverbinding raden we u aan om de cmdlet UitschakelenAzDataCollection uit te voeren om het verzamelen van telemetriegegevens uit te schakelen. Anders kunt u te maken krijgen met prestatievermindering van de cmdlets. Dit is alleen van toepassing op computers zonder internetverbinding.

Uw pakketten toevoegen aan uw werkstation

1. Kopieer de gedownloade pakketten naar een USB-apparaat.

2. Meld u aan bij het niet-verbonden werkstation en kopieer de pakketten van het USB-apparaat naar een locatie op het werkstation.

3. Bootstrap de NuGet-provider handmatig op uw niet-verbonden werkstation. Zie De NuGet-provider handmatig opstarten op een computer die niet is verbonden met internet voor instructies.

4. Registreer deze locatie als de standaardopslagplaats en installeer de AzureRM en AzureStack modules uit deze opslagplaats:

    # 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. Installeer de Az-modules.

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

6. De AzureStack-modulesL installeren

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

De installatie van PowerShell bevestigen

Bevestig de installatie door de volgende opdracht uit te voeren:

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

PowerShell configureren voor het gebruik van een proxyserver

In scenario's waarvoor een proxyserver toegang tot internet is vereist, configureert u eerst PowerShell voor het gebruik van een bestaande proxyserver:

1. Open een PowerShell-prompt met verhoogde bevoegdheid.

2. Voer de volgende opdrachten uit:

   #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
   

De Az-module gebruiken

U kunt nog steeds de cmdlets en codevoorbeelden gebruiken op basis van AzureRM-modules. U moet echter de naam van de modules en cmdlets wijzigen. De modulenamen zijn zodanig gewijzigd dat AzureRM en Azure worden Az, en hetzelfde voor cmdlets. De naam van de AzureRM.Compute module is bijvoorbeeld gewijzigd in Az.Compute. New-AzureRMVM is New-AzVM, en Get-AzureStorageBlob is nu Get-AzStorageBlob.

Zie Migrate van AzureRM naar Azure PowerShell Az voor uitgebreidere discussies en richtlijnen voor het verplaatsen van AzureRM-scripts naar Az en informatie over belangrijke wijzigingen in de Az-module van Azure Stack Hub.

Bekende problemen

Er is een fout opgetreden bij het installeren van de Az-modules

• Van toepassing: dit probleem is van toepassing op 2002 en hoger
• Oorzaak: Bij het installeren van de module wordt een fout gegenereerd. Het foutbericht begint: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Of het foutbericht kan de volgende tekst bevatten: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Herstel: voer de volgende cmdlet uit in dezelfde sessie:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Sluit uw sessie en start een nieuwe PowerShell-sessie met verhoogde bevoegdheid.
• Voorkomen: Algemeen

Bij het installeren van de Az-module wordt ten onrechte een foutmelding gegenereerd die aangeeft dat beheerdersrechten vereist zijn.

• Van toepassing: dit probleem is van toepassing op 2002 en hoger
• Oorzaak: Bij het installeren van de module vanaf een prompt met verhoogde bevoegdheid wordt er een fout gegenereerd. De foutmelding luidt: Administrator rights required.
• Herstel: sluit uw sessie en start een nieuwe PowerShell-sessie met verhoogde bevoegdheid. Zorg ervoor dat er geen bestaande Az is. Accounts module geladen in de sessie.
• Voorkomen: Algemeen

Cmdlet New-AzVmss mislukt wanneer u het 2020-09-01 hybride profiel gebruikt.

• Van toepassing: dit probleem is van toepassing op het hybride profiel 2020-09-01.
• Oorzaak: De cmdlet New-AzVmss werkt niet met het hybride profiel 2020-09-01.
• Herstel: gebruik een sjabloon voor het maken van een schaalset voor virtuele machines. U vindt een voorbeeld van de Azure Stack Hub Resource Manager-sjablonen in de GitHub-opslagplaats AzureStack-QuickStart-Templates/101-vmss-windows-vm en u vindt instructies over het gebruik van Azure Stack Hub Resource Managers met Visual Studio Code.
• Voorkomen: Algemeen

Er is een fout opgetreden bij het uitvoeren van een PowerShell-script

• Van toepassing: dit probleem is van toepassing op 2002 en hoger.

• Oorzaak: Wanneer u scripts of PowerShell-opdrachten uitvoert met behulp van de specifieke Modules van Azure Stack Hub, hebt u uw script of opdracht nodig om beschikbaar te zijn in de module. Mogelijk ziet u de volgende fout:

  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.
  

  De huidige module is de PowerShell Az-module, die de PowerShell AzureRM-module heeft vervangen. Als u probeert een script uit te voeren dat azureRM-opdrachten aanroept wanneer de Az-module is geïnstalleerd, genereert uw script fouten. Of als u probeert een script uit te voeren dat Az-opdrachten aanroept wanneer de AzureRM-module is geïnstalleerd, genereert uw script fouten.

• Herstel: Verwijder de AzureRM-module en installeer de Az-module. Zie PowerShell Az-module installeren voor Azure Stack Hub voor instructies. Als u de Hulpprogramma's van Azure Stack Hub gebruikt, gebruikt u de Az-hulpprogramma's. Kloon de hulpprogramma-opslagplaats van de az vertakking of download de AzureStack-Tools van de az vertakking. Zie Azure Stack Hub-hulpprogramma's downloaden van GitHub voor instructies

• Voorkomen: Algemeen

Fout opgetreden met New-AzADServicePrincipal en New-AzADApplication

• Van toepassing: Azure Stack-omgevingen met behulp van Microsoft Entra-id.

• Oorzaak: Azure Active Directory Graph heeft een ingrijpende wijziging doorgevoerd om het gebruik van IdentifierUri te beperken, waardoor Active Directory-toepassingen alleen subdomeinen van een geverifieerd domein in de directory kunnen zijn. Vóór de wijziging werd deze beperking alleen afgedwongen voor de apps met meerdere tenants. Deze beperking is nu ook van toepassing op apps met één tenant. De wijziging resulteert in de volgende fout: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• Herstel: U kunt deze beperking op twee manieren omzeilen.

  • U moet een service-principalnaam gebruiken die een subdomein van de directory-tenant is. Als de map bijvoorbeeld is contoso.onmicrosoft.com, moet de naam van de service-principal de vorm hebben van <foo>.contoso.onmicrosoft.com. Gebruik de volgende cmdlet:

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

    Zie Overzicht van id-providers voor Azure Stack Hub voor meer informatie over identiteiten en het gebruik van service-principals met Azure Stack Hub.

  • Maak de Microsoft Entra-app met een geldige IdentifierUri en maak vervolgens de service-principal die de app koppelt met behulp van de volgende cmdlet.

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

• Voorkomen: Algemeen

Fout: "SharedTokenCacheCredential-authenticatie mislukt"

• Van toepassing: dit probleem is van toepassing op alle ondersteunde releases.
• Oorzaak: Er is een fout opgetreden bij het uitvoeren van een sharedTokenCacheCredential-verificatie wanneer er meerdere versies van AzAccounts zijn geïnstalleerd met Azure Stack Hub PowerShell Module versie 2.1.1.
• Herstel: verwijder alle versies van AzAccounts en installeer alleen de ondersteunde AzAccounts-versie 2.2.8.
• Voorkomen: Algemeen

Volgende stappen

• Azure Stack Hub-hulpprogramma's downloaden van GitHub
• De PowerShell-omgeving van de Azure Stack Hub-gebruiker configureren
• De PowerShell-omgeving van de Azure Stack Hub-operator configureren
• API-versieprofielen beheren in Azure Stack Hub