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

중요하다

AzureRM(Azure Resource Manager) PowerShell 모듈의 모든 버전은 오래되었으며 지원되지 않습니다. Az PowerShell 모듈은 이제 Azure 및 Azure Stack Hub와 상호 작용하는 데 권장되는 PowerShell 모듈입니다. 이 문서에서는 Az PowerShell 모듈을 시작하는 방법을 설명합니다. Az PowerShell 모듈로 마이그레이션하는 방법에 대한 자세한 내용은 Azure Stack HubAzureRM에서 Azure PowerShell Az로 마이그레이션을 참조하세요. 전역 Azure에서 채택된 Az 모듈의 향상된 기능에 대한 자세한 내용은 Azure Az PowerShell 모듈소개를 참조하세요.

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 관리자 모듈을 설치하는 방법을 설명합니다. Windows, macOS 및 Linux 플랫폼에 Az 모듈을 설치할 수 있습니다.

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

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

API 프로필은 Azure와 Azure Stack Hub 간의 버전 차이를 관리하는 방법을 제공합니다. API 버전 프로필은 특정 API 버전을 사용하는 Azure Resource Manager PowerShell 모듈 집합입니다. 각 클라우드 플랫폼에는 지원되는 API 버전 프로필 집합이 있습니다. 예를 들어 Azure Stack Hub는 2020-09-01 하이브리드같은 특정 프로필 버전을 지원합니다. 프로필을 설치하면 지정된 프로필에 해당하는 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 설치해야 합니다. PowerShell Core에서 실행할 때 Azure PowerShell에는 다른 요구 사항이 없습니다.

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
   

Linux 및 Mac에 대한 필수 구성 요소

PowerShell Core 6.x 이상 버전이 필요합니다. 지침을 보려면 링크을(를) 따르세요.

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

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

• 기존 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 세션을 닫고 이러한 cmdlet을 다시 실행합니다.

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

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

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
   

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

연결이 끊긴 시나리오에서는 먼저 인터넷에 연결된 컴퓨터에 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. 다음 코드는 신뢰할 수 있는 온라인 리포지토리Az 모듈을 설치합니다.

   [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
   

메모

인터넷에 연결하지 않은 컴퓨터에서는 disable-AzDataCollection cmdlet을 실행하여 원격 분석 데이터 수집을 사용하지 않도록 설정하는 것이 좋습니다. 그렇지 않으면 cmdlet의 성능이 저하될 수 있습니다. 인터넷 연결이 없는 컴퓨터에만 적용됩니다.

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

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

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

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

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

    # 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

프록시 서버를 사용하도록 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
   

Az 모듈 사용

AzureRM 모듈을 기반으로 cmdlet 및 코드 샘플을 계속 사용할 수 있습니다. 그러나 모듈 및 cmdlet의 이름을 변경해야 합니다. 모듈 이름이 AzureRM 및 Azure에서 Az로 변경되었으며, cmdlet도 동일하게 변경되었습니다. 예를 들어 AzureRM.Compute 모듈의 이름이 Az.Compute로 변경되었습니다. New-AzureRMVM은 New-AzVM이고, Get-AzureStorageBlob은 이제 Get-AzStorageBlob이다.

AzureRM 스크립트를 Az로 이동하기 위한 자세한 내용과 지침 및 Azure Stack Hub의 Az 모듈의 주요 변경 내용에 대한 자세한 내용은 AzureRM에서 Azure PowerShell Az마이그레이션을 참조하세요.

알려진 문제

Az 모듈을 설치할 때 발생하는 오류

• 적용 가능: 이 문제는 2002년 이상에 적용됩니다.
• 원인: 모듈을 설치할 때 오류가 발생합니다. 오류 메시지가 시작됩니다. 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 모듈을 설치할 때 관리자 권한 필요 오류가 잘못 발생하면 문제가 생깁니다.

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

2020-09-01-hybrid 프로필을 사용할 때 cmdlet New-AzVmss가 실패합니다.

• 적용 가능: 이 문제는 2020-09-01-하이브리드 프로필에 적용됩니다.
• 원인: Cmdlet New-AzVmss은 2020-09-01 하이브리드 프로필에서 작동하지 않습니다.
• 조치: 템플릿을 이용해 가상 머신 확장 집합을 만듭니다. GitHub 리포지토리 에서 AzureStack-QuickStart-Templates/101-vmss-windows-vm의 Azure Stack Hub 리소스 관리자 템플릿 샘플을 찾을 수 있습니다. 또한, 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 인증 실패 오류가 throw됩니다.
• 수정: 모든 버전의 AzAccounts를 제거하고 지원되는 AzAccounts 버전 2.2.8만 설치합니다.
• 발생: 일반

다음 단계

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