Azure Stack Hub용 PowerShell Az 및 Azure Stack 모듈 설치

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

AzureStack 모듈에 대한 자세한 내용은 PSGallery를 참조하세요.

이 문서에서는 PowerShellGet을 사용하여 Azure PowerShell Az 및 호환되는 Azure Stack Hub 관리자 모듈을 설치하는 방법을 설명합니다. Az 모듈은 Windows, macOS 및 Linux 플랫폼에 설치할 수 있습니다.

Docker 컨테이너에서 Azure Stack Hub용 Az 모듈을 실행할 수도 있습니다. 자세한 내용은 Docker를 사용하여 Azure Stack Hub용 PowerShell 실행을 참조하세요.

Azure Stack Hub용 PowerShell 리소스 모듈(AzureRM) 모듈을 설치하려면 Azure Stack Hub 용 PowerShell AzureRM 모듈 설치를 참조하세요.

중요

새 Azure 리소스 모듈 모듈 릴리스는 없습니다. Azure 리소스 모듈 모듈은 중요한 수정에 대해서만 지원됩니다. 앞으로 Azure Stack Hub에 대한 Az 릴리스만 있을 것입니다.

API 프로필을 사용하여 Azure Stack Hub 리소스 공급자에 대해 호환되는 엔드포인트를 지정할 수 있습니다.

API 프로필은 Azure와 Azure Stack Hub 간의 버전 차이를 관리하는 방법을 제공합니다. API 버전 프로필은 특정 API 버전이 있는 Azure Resource Manager PowerShell 모듈 집합입니다. 각 클라우드 플랫폼에는 지원되는 API 버전 프로필 집합이 있습니다. 예를 들어 Azure Stack Hub는 2020-09-01-hybrid와 같은 특정 프로필 버전을 지원합니다. 프로필을 설치하면 지정된 프로필에 해당하는 Azure Resource Manager PowerShell 모듈이 설치됩니다.

인터넷에 연결되거나 부분적으로 연결되거나 연결이 끊긴 시나리오에서 Azure Stack Hub 호환 PowerShell Az 모듈을 설치할 수 있습니다. 이 문서에서는 이러한 시나리오에 대한 자세한 지침을 안내합니다.

1. 필수 구성 요소 확인

Az 모듈은 업데이트 2002 이상 및 현재 핫픽스가 설치된 Azure Stack Hub에서 지원됩니다. 자세한 내용은 Azure Stack Hub 릴리스 정보를 참조하세요.

Azure PowerShell Az 모듈은 Windows의 PowerShell 5.1 이상 또는 모든 플랫폼에서 PowerShell Core 6.x 이상에서 작동합니다. 운영 체제에 사용할 수 있는 최신 버전의 PowerShell Core 를 설치해야 합니다. Azure PowerShell PowerShell Core에서 실행할 때 다른 요구 사항이 없습니다.

PowerShell 버전을 확인하려면 다음 명령을 실행합니다.

$PSVersionTable.PSVersion

Windows의 필수 구성 요소

Windows의 PowerShell 5.1에서 Azure PowerShell을 사용하려면 다음을 수행합니다.

1. 필요한 경우 Windows PowerShell 5.1로 업데이트합니다. Windows 10을 사용하는 경우 PowerShell 5.1이 이미 설치되어 있습니다.

2. .NET Framework 4.7.2 이상을 설치합니다.

3. 최신 버전의 PowerShellGet이 있는지 확인합니다. 관리자 권한 프롬프트에서 다음 cmdlet을 실행합니다.

   [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. Linux 및 Mac의 필수 구성 요소

PowerShell Core 6.x 이상 버전이 필요합니다. 지침은 링크를 따르세요.

3. Azure Stack Hub PowerShell 모듈의 기존 버전 제거

필요한 버전을 설치하기 전에 이전에 설치된 Azure Stack Hub Azure Resource Manager 또는 Az PowerShell 모듈을 제거해야 합니다. 다음 두 가지 방법 중 하나를 사용하여 모듈을 제거합니다.

1. 기존 Azure Resource Manager 및 Az PowerShell 모듈을 제거하려면 활성 PowerShell 세션을 모두 닫고 다음 cmdlet을 실행합니다.

   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
   

   '모듈이 이미 사용 중'과 같은 오류가 발생하면 모듈을 사용하는 PowerShell 세션을 닫고 위의 스크립트를 다시 실행합니다.

2. Uninstall-Module 성공하지 못한 경우 , Az또는 Azs. 로 시작하는 Azure모든 폴더를 $env:PSModulePath 위치에서 삭제합니다. Windows PowerShell 경우 위치는 및 C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules일 C:\Program Files\WindowsPowerShell\Modules 수 있습니다. PowerShell Core의 경우 위치는 및 C:\Users\{yourusername}\Documents\PowerShell\Modules일 C:\Program Files\PowerShell\7\Modules 수 있습니다. 이러한 폴더를 삭제하면 기존 Azure PowerShell 모듈이 제거됩니다.

4. 연결됨: 인터넷 연결을 사용하여 설치

Azure Stack Az 모듈은 Windows 컴퓨터에서 PowerShell 5.1 이상 또는 Linux 또는 macOS 플랫폼에서 PowerShell 6.x 이상에서 작동합니다. 기본 설치 방법은 PowerShellGet cmdlet을 사용하는 것입니다. 이 메서드는 지원되는 플랫폼에서도 동일하게 작동합니다.

1. PowerShell 세션에서 다음 명령을 실행하여 PowerShellGet을 최소 버전 2.2.3으로 업데이트합니다.

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

2. PowerShell 세션을 닫은 다음, 새 PowerShell 세션을 열어야 업데이트가 적용될 수 있습니다.

3. 다음을 실행하여 Az 모듈을 설치합니다.

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

4. AzureStack PowerShell 모듈을 설치합니다.

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

경고

Windows용 PowerShell 5.1용 Azure Resource Manager(AzureRM) 및 Az 모듈을 동시에 설치할 수 없습니다. 시스템에서 Azure Resource Manager 사용할 수 있도록 유지해야 하는 경우 PowerShell Core 6.x 이상용 Az 모듈을 설치합니다. 이렇게 하려면 PowerShell Core 6.x 이상을 설치 한 다음 PowerShell Core 터미널에서 다음 지침을 따릅니다.

5. 연결이 끊김: 인터넷 연결 없이 설치

연결이 끊긴 시나리오에서는 먼저 인터넷에 연결된 컴퓨터에 PowerShell 모듈을 다운로드합니다. 그런 다음 설치를 위해 ASDK(Azure Stack Development Kit)로 전송합니다.

인터넷에 연결된 컴퓨터에 로그인하고 다음 스크립트를 사용하여 Azure Stack Hub 버전에 따라 Azure Resource Manager 및 Azure Stack Hub 패키지를 다운로드합니다.

설치에는 다음 5단계가 있습니다.

1. 연결된 컴퓨터에 Azure Stack Hub PowerShell을 설치합니다.
2. 추가 스토리지 기능을 사용하도록 설정합니다.
3. PowerShell 패키지를 연결이 끊긴 워크스테이션으로 전송합니다.
4. 연결이 끊긴 워크스테이션에서 NuGet 공급자를 수동으로 부트스트랩합니다.
5. PowerShell 설치를 확인합니다.

Azure Stack Hub PowerShell 설치

1. AzureRM 또는 Az 모듈을 사용할 수 있습니다. 다음 코드는 신뢰할 수 있는 온라인 리포지토리에서 Az 모듈을 저장합니다 https://www.powershellgallery.com/.

   [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. Az 모듈이 설치되면 AzureStack 모듈 설치를 진행합니다.

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

참고

인터넷에 연결하지 않은 컴퓨터에서는 원격 분석 데이터 수집을 사용하지 않도록 설정하기 위해 다음 cmdlet을 실행하는 것이 좋습니다. 원격 분석 데이터 수집을 사용하지 않도록 설정하지 않고 cmdlet의 성능이 저하 될 수 있습니다. 인터넷 연결이 없는 컴퓨터에만 적용됩니다.

Disable-AzDataCollection

워크스테이션에 패키지 추가

1. 다운로드한 패키지를 USB 디바이스에 복사합니다.

2. 연결이 끊긴 워크스테이션에 로그인하고 USB 디바이스에서 워크스테이션의 위치로 패키지를 복사합니다.

3. 연결이 끊긴 워크스테이션에서 NuGet 공급자를 수동으로 부트스트랩합니다. 지침은 인터넷에 연결되지 않은 컴퓨터에서 NuGet 공급자를 수동으로 부트스트랩을 참조하세요.

4. 이 위치를 기본 리포지토리로 등록하고 이 리포지토리에서 및 AzureStack 모듈을 설치 AzureRM 합니다.

    # 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. Az 모듈을 설치합니다.

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

6. AzureStack 모듈을 설치합니다.

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

PowerShell 설치 확인

다음 명령을 실행하여 설치를 확인합니다.

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

6. 프록시 서버를 사용하도록 PowerShell 구성

프록시 서버가 인터넷에 액세스해야 하는 시나리오에서는 먼저 기존 프록시 서버를 사용하도록 PowerShell을 구성합니다.

1. 관리자 권한 PowerShell 프롬프트를 엽니다.

2. 다음 명령을 실행합니다.

   #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. Az 모듈 사용

AzureRM 모듈을 기반으로 cmdlet 및 코드 샘플을 사용할 수 있습니다. 그러나 모듈 및 cmdlet의 이름을 변경하려고 합니다. 모듈 이름이 변경되어 및 Azure가 AzureRM 가 되고 Azcmdlet의 경우 동일합니다. 예를 들어, AzureRM.Compute 모듈의 이름이 Az.Compute로 변경되었습니다. New-AzureRMVM은 New-AzVM이 되고 Get-AzureStorageBlob은 이제 Get-AzStorageBlob입니다.

AzurRM 스크립트를 Az로 이동하고 Azure Stack Hub의 Az 모듈에서 호환성이 손상되는 변경에 대한 자세한 내용과 지침은 AzureRM에서 Azure PowerShell Az로 마이그레이션을 참조하세요.

알려진 문제

Az 모듈을 설치할 때 오류가 발생했습니다.

• 적용 가능: 이 문제는 2002년 이상에 적용됩니다.
• 원인: 모듈을 설치할 때 오류가 throw됩니다. 오류 메시지가 시작됩니다. Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'. 또는 오류 메시지에 다음 텍스트가 포함될 수 있습니다. PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• 수정: 동일한 세션에서 다음 cmdlet을 실행합니다.
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  세션을 닫고 새 관리자 권한 PowerShell 세션을 시작합니다.
• 발생: 일반

Az 모듈을 설치하면 관리 권한 필요 오류가 잘못 throw됩니다.

• 적용 가능: 이 문제는 2002년 이상에 적용됩니다.
• 원인: 관리자 권한 프롬프트에서 모듈을 설치하면 오류가 throw됩니다. 오류는 입니다 Administrator rights required.
• 수정: 세션을 닫고 새 관리자 권한 PowerShell 세션을 시작합니다. 기존 Az가 없는지 확인합니다. 세션에 로드된 계정 모듈입니다.
• 발생: 일반

2020-09-01-hybrid 프로필을 사용할 때 cmdlet New-AzVmss 실패

• 적용 가능: 이 문제는 2020-09-01-하이브리드 프로필에 적용됩니다.
• 원인: New-AzVmss cmdlet은 2020-09-01-hybrid 프로필에서 작동하지 않습니다.
• 수정: 템플릿을 사용하여 가상 머신 확장 집합을 만듭니다. GitHub 리포지토리 AzureStack-QuickStart-Templates/101-vmss-windows-vm에서 Azure Stack Hub Resource Manager 템플릿 샘플을 찾을 수 있으며 Visual Studio Code Azure Stack Hub 리소스 관리자를 사용하는 방법에 대한 지침을 찾을 수 있습니다.
• 발생: 일반

PowerShell 스크립트를 실행할 때 발생하는 오류

• 적용 가능: 이 문제는 2002년 이상에 적용됩니다.

• 원인: Azure Stack Hub 특정 모듈을 사용하여 스크립트 또는 PowerShell 명령을 실행하는 경우 모듈에서 스크립트 또는 명령을 사용할 수 있어야 합니다. 다음 오류가 표시될 수 있습니다.

  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.
  

  현재 모듈은 PowerShell AzureRM 모듈을 대체한 PowerShell Az 모듈입니다. Az 모듈이 설치될 때 AzureRM 명령을 호출하는 스크립트를 실행하려고 하면 스크립트에서 오류가 발생합니다. 또는 AzureRM 모듈이 설치될 때 Az 명령을 호출하는 스크립트를 실행하려고 하면 스크립트에서 오류가 발생합니다.

• 수정: AzureRM 모듈을 제거하고 Az 모듈을 설치합니다. 자세한 내용은 Azure Stack Hub용 PowerShell Az 모듈 설치를 참조하세요. Azure Stack Hub 도구를 사용하는 경우 Az 도구를 사용합니다. az 분기에서 도구 리포지토리를 복제하거나 az 분기에서 AzureStack-Tools 다운로드합니다. 자세한 내용은 GitHub에서 Azure Stack Hub 도구 다운로드를 참조하세요.

• 발생: 일반

New-AzADServicePrincipal 및 New-AzADApplication 발생한 오류

• 적용 가능: Microsoft Entra ID 사용하는 Azure Stack 환경.

• 원인: Azure Active Directory Graph는 Active Directory 애플리케이션이 디렉터리에서 확인된 도메인의 하위 도메인이 되도록 제한하는 IdentifierUri 호환성이 손상되는 변경을 도입했습니다. 변경 전에 이 제한은 다중 테넌트 앱에만 적용되었습니다. 이제 이 제한은 단일 테넌트 앱에도 적용됩니다. 변경으로 인해 다음 오류가 발생합니다 Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running.

• 수정: 두 가지 방법으로 이 제한을 해결할 수 있습니다.

  • 디렉터리 테넌트의 하위 도메인인 서비스 주체 이름을 사용해야 합니다. 예를 들어 디렉터리가 contoso.onmicrosoft.com인 경우 서비스 주체 이름은 형식 <foo>.contoso.onmicrosoft.com이어야 합니다. 다음 cmdlet을 사용합니다.

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

    AZURE Stack Hub에서 ID 및 서비스 주체 사용에 대한 자세한 내용은 Azure Stack Hub 에 대한 ID 공급자 개요를 참조하세요.

  • 유효한 IdentifierUri 를 제공하는 Microsoft Entra 앱을 만든 다음, 다음 cmdlet을 사용하여 앱을 연결한 서비스 주체를 만듭니다.

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

• 발생: 일반

오류: "SharedTokenCacheCredential 인증 실패"

• 적용 가능: 이 문제는 지원되는 모든 릴리스에 적용됩니다.
• 원인: Azure Stack Hub PowerShell 모듈 버전 2.1.1과 함께 여러 버전의 AzAccounts를 설치할 때 SharedTokenCacheCredential 인증 실패 오류가 발생합니다.
• 수정: 모든 버전의 AzAccounts를 제거하고 지원되는 AzAccounts 버전 2.2.8만 설치합니다.
• 발생: 일반

다음 단계

• GitHub에서 Azure Stack Hub 도구 다운로드
• Azure Stack Hub 사용자의 PowerShell 환경 구성
• Azure Stack Hub 운영자의 PowerShell 환경 구성
• Azure Stack Hub에서 API 버전 프로필 관리