Menginstal modul PowerShell Az dan Azure Stack untuk Azure Stack Hub

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

Untuk informasi selengkapnya tentang modul AzureStack, lihat PSGallery.

Artikel ini menjelaskan tentang cara menginstal Azure PowerShell Az dan modul administrator Azure Stack Hub yang kompatibel menggunakan PowerShellGet. Modul Az dapat diinstal di platform Windows, macOS, dan Linux.

Anda juga dapat menjalankan modul Az untuk Azure Stack Hub di kontainer Docker. Untuk mengetahui panduannya, lihat Menggunakan Docker untuk menjalankan PowerShell untuk Azure Stack Hub.

Jika Anda ingin menginstal Modul Sumber Daya (AzureRM) PowerShell untuk Azure Stack Hub, lihat Menginstal modul AzureRM PowerShell untuk Azure Stack Hub.

Penting

Tidak akan ada rilis modul Azure Resource Modules baru. Modul AzureRM disediakan khusus untuk perbaikan penting. Ke depannya, hanya akan ada rilis Az untuk Azure Stack Hub.

Anda dapat menggunakan profil API untuk menentukan titik akhir yang kompatibel bagi penyedia sumber daya Azure Stack Hub.

Profil API menyediakan cara mengelola perbedaan versi antara Azure dan Azure Stack Hub. Profil versi API adalah serangkaian modul PowerShell Azure Resource Manager dengan versi API tertentu. Setiap platform cloud memiliki serangkaian profil versi API yang didukung. Misalnya, Azure Stack Hub mendukung versi profil tertentu seperti 2020-09-01-hybrid. Ketika Anda menginstal profil, modul PowerShell Azure Resource Manager yang sesuai dengan profil tersebut akan terinstal.

Anda dapat menginstal Azure Stack Hub yang kompatibel dengan modul PowerShell Az dalam skenario terhubung, terhubung sebagian, maupun terputus dengan koneksi internet. Artikel ini memandu Anda dalam mengikuti petunjuk detail mengenai skenario ini.

1. Verifikasi prasyarat Anda

Modul Az didukung di Azure Stack Hub dengan Versi 2002 atau yang lebih baru dan dengan perbaikan yang saat ini terinstal. Lihat Catatan rilis Azure Stack Hub untuk informasi selengkapnya.

Modul Azure PowerShell Az bekerja di Windows dengan PowerShell 5.1 atau versi lebih tinggi, atau di semua platform dengan PowerShell Core 6.x dan versi lebih baru. Anda harus menginstal versi terbaru PowerShell Core yang tersedia untuk sistem operasi Anda. Azure PowerShell tidak memiliki persyaratan lain saat dijalankan di PowerShell Core.

Untuk memeriksa versi PowerShell Anda, jalankan perintah:

$PSVersionTable.PSVersion

Prasyarat untuk Windows

Untuk menggunakan Azure PowerShell di PowerShell 5.1 pada Windows:

1. Perbarui ke Windows PowerShell 5.1 jika diperlukan. Jika Anda menggunakan Windows 10, PowerShell 5.1 sudah terinstal di dalamnya.

2. Instal .NET Framework 4.7.2 or versi lebih baru.

3. Pastikan Anda telah menginstal PowerShellGet versi terbaru. Jalankan cmdlet berikut dari perintah yang ditinggikan:

   [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. Prasyarat untuk Linux dan Mac

Perlu PowerShell Core 6.x atau versi yang lebih baru. Ikuti tautan ini untuk melihat petunjuk

3. Menghapus instalan versi modul PowerShell Azure Stack Hub yang sudah ada

Sebelum menginstal versi yang diperlukan, pastikan Anda menghapus instalan modul Azure Stack Hub Azure Resource Manager atau Az PowerShell yang terinstal sebelumnya. Menghapus instalan modul dengan menggunakan salah satu dari dua metode berikut:

1. Untuk menghapus instalan modul Azure Resource Manager dan Az PowerShell yang sudah ada, tutup semua sesi PowerShell yang aktif, dan jalankan cmdlet berikut:

   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
   

   Jika Anda mengalami kesalahan seperti 'Modul sudah digunakan', tutup sesi PowerShell yang menggunakan modul tersebut dan jalankan kembali skrip di atas.

2. Jika Penghapusan Instalan-Modul tidak berhasil, hapus semua folder yang dimulai dengan Azure, Az, atau Azs. dari lokasi $env:PSModulePath. Untuk PowerShell Windows, lokasinya mungkin C:\Program Files\WindowsPowerShell\Modules dan C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules. Untuk PowerShell Core, lokasinya mungkin C:\Program Files\PowerShell\7\Modules dan C:\Users\{yourusername}\Documents\PowerShell\Modules. Penghapusan folder ini akan menghapus instalan modul Azure PowerShell yang ada.

4. Terhubung: Menginstal dengan konektivitas internet

Modul Azure Stack Az dapat bekerja di mesin Windows dengan PowerShell 5.1 atau versi yang lebih tinggi, atau di platform Linux atau macOS dengan PowerShell 6.x atau versi yang lebih tinggi. Penggunaan cmdlet PowerShellGet adalah metode penginstalan yang lebih disarankan. Metode ini berfungsi sama pada platform yang didukung.

1. Jalankan perintah dari sesi PowerShell berikut untuk memperbarui PowerShellGet minimal ke versi 2.2.3

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

2. Tutup sesi PowerShell Anda, lalu buka sesi PowerShell baru sehingga pembaruan dapat berlaku.

3. Jalankan yang berikut ini untuk menginstal modul Az.

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

4. Instal modul AzureStack PowerShell.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

Peringatan

Modul Azure Resource Manager (AzureRM) dan Az tidak dapat diinstal pada PowerShell 5.1 untuk Windows secara bersamaan. Jika Anda ingin mempertahankan Azure Resource Manager tetap tersedia di sistem Anda, instal modul Az untuk PowerShell Core 6.x atau versi yang lebih baru. Untuk melakukannya, instal PowerShell Core 6.x atau versi yang lebih baru, lalu ikuti instruksi ini di terminal PowerShell Core.

5. Terputus: Menginstal tanpa koneksi internet

Dalam skenario terputus dengan koneksi internet, Anda dapat terlebih dahulu mengunduh modul PowerShell ke mesin yang memiliki konektivitas internet. Kemudian, Anda mentransfernya ke Azure Stack Development Kit (ASDK) untuk melakukan penginstalan.

Masuk ke komputer yang terkoneksi internet dan gunakan skrip berikut untuk mengunduh paket Azure Resource Manager dan Azure Stack Hub, tergantung pada versi Azure Stack Hub Anda.

Penginstalan memiliki lima langkah:

1. Instal Azure Stack Hub PowerShell ke mesin yang terkoneksi internet.
2. Aktifkan fitur penyimpanan tambahan.
3. Angkut paket PowerShell ke stasiun kerja Anda yang terputus koneksi internet.
4. Bootstrap penyedia NuGet secara manual di stasiun kerja Anda yang terputus koneksi internet.
5. Lakukan konfirmasi penginstalan PowerShell.

Instal Azure Stack Hub PowerShell

1. Anda dapat menggunakan modul AzureRM atau Az . Kode berikut menyimpan modul Az dari repositori https://www.powershellgallery.com/online yang dapat dipercaya .

   [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. Setelah modul Az diinstal, lanjutkan dengan menginstal modul AzureStack.

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

Catatan

Pada komputer tanpa koneksi internet, kami sarankan untuk menjalankan cmdlet berikut untuk menonaktifkan pengumpulan data telemetri. Anda dapat mengalami penurunan kinerja cmdlet jika tidak menonaktifkan pengumpulan data telemetri. Hal ini hanya berlaku untuk komputer tanpa koneksi internet

Disable-AzDataCollection

Menambahkan paket ke stasiun kerja Anda

1. Salin paket yang diunduh ke perangkat USB.

2. Masuk ke stasiun kerja yang terputus koneksi internet dan salin paket dari perangkat USB ke lokasi di stasiun kerja.

3. Bootstrap penyedia NuGet secara manual di stasiun kerja Anda yang terputus koneksi internet. Untuk mengetahui petunjuknya, lihat Melakukan bootstrap penyedia NuGet secara manual pada mesin yang tidak terhubung ke internet.

4. Daftarkan lokasi ini sebagai repositori default dan instal modul AzureRM dan AzureStack dari repositori ini:

    # 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. Instal modul Az.

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

6. Instal modul AzureStack.

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

Lakukan konfirmasi penginstalan PowerShell

Lakukan konfirmasi penginstalan dengan menjalankan perintah berikut:

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

6. Mengonfigurasikan PowerShell untuk menggunakan server proksi

Dalam skenario yang memerlukan server proksi untuk mengakses internet, pertama Anda harus mengonfigurasi PowerShell untuk menggunakan server proksi yang ada:

1. Buka prompt PowerShell yang ditinggikan.

2. Jalankan perintah berikut:

   #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. Menggunakan modul Az

Anda dapat menggunakan cmdlet dan sampel kode berdasarkan modul AzureRM. Namun, Anda mungkin ingin mengubah nama modul dan cmdlet. Nama modul telah diubah sehingga AzureRM dan Azure menjadi Az, dan sama untuk cmdlet. Misalnya, nama modul AzureRM.Compute telah diganti menjadi Az.Compute. New-AzureRMVM telah menjadi New-AzVM, and Get-AzureStorageBlob menjadi Get-AzStorageBlob.

Untuk diskusi dan panduan yang lebih lengkap tentang memindahkan skrip AzurRM ke Az dan kegagalan akibat perubahan dalam modul Az Azure Stack Hub, lihat Migrasi dari AzureRM ke Azure PowerShell Az.

Masalah yang diketahui

Kesalahan yang muncul saat menginstal modul Az

• Berlaku: Masalah ini berlaku pada versi 2002 dan yang lebih baru
• Penyebab: Saat menginstal modul, kesalahan muncul. Pesan kesalahan dimulai: Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. Atau pesan kesalahan mungkin menyertakan teks berikut: PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• Remediasi: Jalankan cmdlet berikut di sesi yang sama:
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  Tutup sesi Anda dan mulai sesi PowerShell baru yang ditinggikan.
• Kejadian: Umum

Saat menginstal modul Az, kesalahan hak Admin diperlukan muncul secara keliru

• Berlaku: Masalah ini berlaku pada versi 2002 dan yang lebih baru
• Penyebab: Saat menginstal modul dari perintah yang ditinggikan, kesalahan muncul. Kesalahan berbunyi, Administrator rights required.
• Remediasi: Tutup sesi Anda dan mulai sesi PowerShell baru yang ditingkatkan. Pastikan tidak ada Az yang telah dibuat. Modul akun dimuat dalam sesi.
• Kejadian: Umum

Cmdlet New-AzVmss gagal saat menggunakan profil 2020-09-01-hybrid

• Berlaku: Masalah ini berlaku pada profil 2020-09-01-hybrid.
• Penyebab: Cmdlet New-AzVmss tidak berfungsi dengan profil 2020-09-01-hybrid.
• Remediasi: Gunakan templat untuk membuat set skala mesin virtual. Anda dapat menemukan sampel templat Azure Stack Hub Resource Manager di Repositori GitHub AzureStack-QuickStart-Templates/101-vmss-windows-vm dan Anda dapat menemukan petunjuk tentang penggunaan Azure Stack Hub Resource Managers dengan Visual Studio Code.
• Kejadian: Umum

Kesalahan muncul saat menjalankan skrip PowerShell

• Berlaku: Masalah ini berlaku pada versi 2002 dan yang lebih baru.

• Penyebab: Saat menjalankan skrip atau perintah PowerShell menggunakan modul khusus Azure Stack Hub, skrip atau perintah Anda perlu tersedia di modul. Anda mungkin melihat kesalahan berikut:

  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.
  

  Modul saat ini adalah modul PowerShell Az, yang telah menggantikan modul PowerShell AzureRM. Jika Anda mencoba menjalankan skrip yang meminta perintah AzureRM saat modul Az diinstal, skrip Anda akan mengalami kesalahan. Atau jika Anda mencoba menjalankan skrip yang meminta perintah Az saat modul AzureRM diinstal, skrip Anda akan mengalami kesalahan.

• Remediasi: Hapus instalan modul AzureRM dan instal modul Az. Untuk petunjuk, lihat Menginstal modul Az PowerShell untuk Azure Stack Hub. Jika Anda menggunakan Azure Stack Hub Tools, gunakan alat Az. Buat klon repositori alat dari cabang az, atau unduh AzureStack-Tools dari cabang az. Untuk petunjuk, lihat Mengunduh alat Azure Stack Hub dari GitHub

• Kejadian: Umum

Kesalahan muncul dengan New-AzADServicePrincipal dan New-AzADApplication

• Berlaku: Lingkungan Azure Stack menggunakan Microsoft Entra ID.

• Penyebab: Azure Active Directory Graph memunculkan kesalahan akibat perubahan untuk membatasi IdentifierUri aplikasi Active Directory menjadi subdomain dari domain terverifikasi di direktori. Sebelum perubahan, pembatasan ini hanya diterapkan untuk aplikasi multi-penyewa. Saat ini, pembatasan ini juga berlaku untuk aplikasi penyewa tunggal. Perubahan akan mengakibatkan kesalahan berikut: Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• Remediasi: Anda dapat mengatasi pembatasan ini dengan dua cara.

  • Anda harus menggunakan nama prinsipal layanan yang merupakan subdomain dari penyewa direktori. Misalnya, jika direktori itu adalah contoso.onmicrosoft.com, nama prinsipal layanannya harus dalam bentuk <foo>.contoso.onmicrosoft.com. Gunakan cmdlet berikut:

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

    Untuk informasi selengkapnya mengenai identitas dan penggunaan prinsipal layanan dengan Azure Stack Hub, lihat Gambaran umum penyedia identitas untuk Azure Stack Hub.

  • Buat aplikasi Microsoft Entra yang menyediakan yang valid IdentifierUri lalu buat perwakilan layanan yang mengaitkan aplikasi menggunakan cmdlet berikut:

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

• Kejadian: Umum

Kesalahan: "Autentikasi SharedTokenCacheCredential gagal"

• Berlaku: Masalah ini berlaku untuk semua rilis yang didukung.
• Penyebab: Kesalahan autentikasi SharedTokenCacheCredential gagal muncul saat memiliki beberapa versi AzAccounts yang diinstal dengan Modul PowerShell Azure Stack Hub versi 2.1.1.
• Remediasi: Hapus semua versi AzAccounts dan hanya instal AzAccounts versi 2.2.8 yang didukung.
• Kejadian: Umum

Langkah berikutnya

• Mengunduh alat Azure Stack Hub dari GitHub
• Mengonfigurasi lingkungan PowerShell pengguna Azure Stack Hub
• Mengonfigurasi lingkungan PowerShell operator Azure Stack Hub
• Mengelola profil versi API di Azure Stack Hub