Azure Stack Hub에서 AzureRM에서 Azure PowerShell Az로 마이그레이션

  • 아티클

Az 모듈은 AzureRM과 기능 패리티를 가지고 있지만 더 짧고 일관된 cmdlet 이름을 사용합니다. AzureRM cmdlet용으로 작성된 스크립트는 새 모듈과 자동으로 작동하지 않습니다. 쉽게 전환하기 위해 Az는 AzureRM을 사용하여 기존 스크립트를 실행할 수 있는 도구를 제공합니다. 새 명령 집합으로 마이그레이션은 편리하지 않지만 이 문서는 새로운 모듈로 전환을 시작하는 데 도움이 됩니다.

AzureRM과 Az 간의 호환성이 손상되는 전체 변경 목록을 보려면 Az 1.0.0 마이그레이션 가이드를 참조하세요.

설치된 AzureRM 버전 확인

모든 마이그레이션 단계를 수행하기 전에 시스템에 설치된 AzureRM의 버전을 확인합니다. 이렇게 하면 스크립트가 최신 릴리스에서 이미 실행되고 있는지 확인하고 AzureRM을 제거하지 않고 명령 별칭을 사용할 수 있는지 여부를 알려줍니다.

설치한 AzureRM의 버전을 확인하려면 다음 명령을 입력합니다.

Get-InstalledModule -Name AzureRM -AllVersions

현재 스크립트가 AzureRM에서 작동하는지 확인

가장 중요한 단계입니다! 기존 스크립트를 실행하고 AzureRM(2.5.0)의 최신 릴리스에서 작동하는지 확인합니다. 스크립트가 작동하지 않으면 AzureRM 마이그레이션 가이드를 읽으세요.

Azure PowerShell Az 모듈 설치

첫 번째 단계는 플랫폼에 Az 모듈을 설치하는 것입니다. Az를 설치할 때는 AzureRM을 제거하는 것이 좋습니다. 다음 단계에서는 기존 스크립트를 계속 실행하고 이전 cmdlet 이름과의 호환성을 유지하는 방법을 알아보겠습니다.

Azure PowerShell Az 모듈을 설치하려면 다음 단계를 수행하십시오.

AzureRM 호환성 별칭을 사용하도록 설정

중요

모든 버전의 AzureRM을 제거한 경우에만 호환성 모드를 활성화하세요. AzureRM cmdlet과의 호환 모드를 계속 사용하도록 설정하면 예기치 않은 동작이 발생할 수 있습니다. AzureRM을 설치하기로 결정한 경우 이 단계를 건너뛰세요. 그러나 AzureRM cmdlet은 이전 모듈을 사용하고 Az cmdlet은 호출하지 않습니다.

AzureRM을 제거하고 최신 AzureRM 버전과 함께 스크립트가 작동하면 이제 Az 모듈에 대한 호환 모드를 사용할 때입니다. 호환성은 다음 명령으로 사용됩니다.

Enable-AzureRmAlias -Scope CurrentUser

별칭을 사용하면 Az 모듈이 설치된 이전 cmdlet 이름을 사용할 수 있습니다. 이러한 별칭은 선택한 범위에 대한 사용자 프로필에 기록됩니다. 사용자 프로필이 없으면 프로일 하나가 만들어집니다.

Warning

이 명령에 대해 다른 -Scope를 사용할 수 있지만 권장되지는 않습니다. 별칭은 선택된 범위에 대한 사용자 프로필에 기록되므로 가능한 한 범위를 제한적으로 유지합니다. 별칭을 시스템 전체에서 사용하도록 설정하면 AzureRM을 로컬 범위에 설치한 다른 사용자에게 문제가 발생할 수 있습니다.

별칭 모드가 활성화되면 스크립트를 다시 실행하여 스크립트가 여전히 예상대로 작동하는지 확인합니다.

모듈 및 cmdlet 이름 변경

일반적으로 모듈 이름은 AzureRM 및 Azure가 Az가 되도록 변경되었으며 cmdlet에도 동일하게 적용됩니다. 예를 들어, AzureRM.Compute 모듈의 이름이 Az.Compute로 변경되었습니다. New-AzureRMVM은 New-AzVM이 되고 Get-AzureStorageBlob은 이제 Get-AzStorageBlob입니다.

이 이름 변경에는 알아야 할 예외 사항이 있습니다. AzureRM 또는 Azure를 Az로 변경하는 것 이외에 일부 cmdlet의 접미사에 영향을 주지 않고 일부 모듈의 이름을 바꾸거나 기존 모듈에 병합했습니다. 또는 전체 cmdlet 접미사가 새로운 모듈 이름을 반영하도록 변경되었습니다.

AzureRM 모듈 Az 모듈 Cmdlet 접미사가 변경되었습니까?
AzureRM.Profile Az.Accounts 예
AzureRM.Insights Az.Monitor 예
AzureRM.Tags Az.Resources 예
AzureRM.UsageAggregates Az.Billing 예
AzureRM.Consumption Az.Billing 예

요약

이 단계를 따르면 기존 스크립트를 모두 업데이트하여 새 모듈을 사용할 수 있습니다. 마이그레이션을 어렵게 하는 이들 단계에 대해 질문이나 문제가 있는 경우 지침을 개선할 수 있도록 이 문서에 의견을 남겨주세요.

Az 1.0.0의 호환성이 손상되는 변경

이 문서에서는 AzureRM 6.x와 새 Az 모듈 버전 1.x 이상 간의 변경 내용에 대한 자세한 정보를 제공합니다. 목차는 스크립트에 영향을 줄 수 있는 모듈별 변경을 포함하여 전체 마이그레이션 경로를 안내합니다.

일반적인 주요 변경 내용

이 섹션에서는 Az 모듈 재설계의 일부인 일반적인 호환성이 손상되는 변경에 대해 자세히 설명합니다.

Cmdlet 명사 접두사 변경

AzureRM 모듈에서 cmdlet은 AzureRM 또는 Azure를 명사 접두사로 사용했습니다. Az는 cmdlet 이름을 간소화하고 정규화하여 모든 cmdlet에서 'Az'를 해당 cmdlet 명사 접두사로 사용합니다. 예를 들면 다음과 같습니다.

Get-AzureRMVM
Get-AzureKeyVaultSecret

다음으로 변경되었습니다.

Get-AzVM
Get-AzKeyVaultSecret

이러한 새 cmdlet 이름으로 더 간단하게 전환할 수 있도록 Az에서 Enable-AzureRmAlias 및 Disable-AzureRmAlias라는 두 개의 새 cmdlet을 도입했습니다. Enable-AzureRmAlias는 최신 Az cmdlet 이름에 매핑되는 AzureRM의 이전 cmdlet 이름에 대한 별칭을 에 만듭니다. Enable-AzureRmAlias에서 -Scope 인수를 사용하면 별칭을 사용하도록 설정되는 위치를 선택할 수 있습니다.

예를 들어, AzureRM의 다음 스크립트가 있습니다.

#Requires -Modules AzureRM.Storage
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Enable-AzureRmAlias를 사용하여 최소한의 변경으로 실행할 수 있습니다.

#Requires -Modules Az.Storage
Enable-AzureRmAlias -Scope Process
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

Enable-AzureRmAlias -Scope CurrentUser를 실행하면 열려 있는 모든 PowerShell 세션에 별칭을 사용하도록 설정되므로 이 cmdlet을 실행한 후 이와 같은 스크립트를 전혀 변경할 필요가 없습니다.

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

별칭 cmdlet을 사용하는 방법에 대한 자세한 내용은 Enable-AzureRmAlias 참조를 참조하세요.

별칭을 사용하지 않도록 설정할 준비가 되면 Disable-AzureRmAlias에서 만들어진 별칭을 제거합니다. 자세한 내용은 Disable-AzureRmAlias 참조를 참조하세요.

중요

별칭을 사용하지 않도록 설정하는 경우 별칭을 사용하도록 설정된 모든 범위에 대해 사용하지 않도록 설정해야 합니다.

모듈 이름 변경

다음 모듈을 제외하고 모듈 이름이 AzureRM.*에서 Az.*로 변경되었습니다.

AzureRM 모듈 Az 모듈
Azure.Storage Az.Storage
Azure.AnalysisServices Az.AnalysisServices
AzureRM.Profile Az.Accounts
AzureRM.Insights Az.Monitor
AzureRM.RecoveryServices.Backup Az.RecoveryServices
AzureRM.RecoveryServices.SiteRecovery Az.RecoveryServices
AzureRM.Tags Az.Resources
AzureRM.MachineLearningCompute Az.MachineLearning
AzureRM.UsageAggregates Az.Billing
AzureRM.Consumption Az.Billing

모듈 이름이 변경되면 #Requires 또는 Import-Module을 사용하여 특정 모듈을 로드하는 스크립트는 대신 새 모듈을 사용하도록 변경되어야 합니다. cmdlet 접미사가 변경되지 않은 모듈의 경우 이는 모듈 이름이 변경되었지만 작업 공간을 나타내는 접미사가 변경되지 않았음 을 의미합니다.

마이그레이션하려면 모듈 문이 필요하고 가져오기

#Requires 또는 Import-Module을 사용하여 AzureRM 모듈에 대한 종속성을 선언하는 스크립트는 새 모듈 이름을 사용하도록 업데이트해야 합니다. 예를 들면 다음과 같습니다.

#Requires -Module AzureRM.Compute

다음으로 변경되어야 합니다.

#Requires -Module Az.Compute

Import-Module의 경우

Import-Module -Name AzureRM.Compute

다음으로 변경되어야 합니다.

Import-Module -Name Az.Compute

정규화된 cmdlet 호출 마이그레이션

다음과 같이 모듈에서 정규화된 cmdlet 호출을 사용하는 스크립트는

AzureRM.Compute\Get-AzureRmVM

새 모듈 및 cmdlet 이름을 사용하도록 변경되어야 합니다.

Az.Compute\Get-AzVM

모듈 매니페스트 종속성 마이그레이션

모듈 매니페스트 파일(.psd1)을 통해 AzureRM 모듈에 대한 종속성을 나타내는 모듈은 RequiredModules 섹션에서 모듈 이름을 업데이트해야 합니다

RequiredModules = @(@{ModuleName="AzureRM.Profile"; ModuleVersion="5.8.2"})

다음으로 변경되어야 합니다.

RequiredModules = @(@{ModuleName="Az.Accounts"; ModuleVersion="1.0.0"})

제거된 모듈

다음 모듈이 제거되었습니다.

  • AzureRM.Backup
  • AzureRM.Compute.ManagedService
  • AzureRM.Scheduler

이러한 서비스를 위한 도구는 더 이상 적극적으로 지원되지 않습니다. 편리한 대체 서비스로 이동하는 것이 좋습니다.

Windows PowerShell 5.1 및 .NET 4.7.2

Windows용 PowerShell 5.1에서 Az를 사용하려면 .NET Framework 4.7.2를 설치해야 합니다. PowerShell Core 6.x 이상을 사용하는 경우 .NET Framework가 필요하지 않습니다.

PSCredential을 사용하여 사용자 로그인 임시 제거

.NET 표준의 인증 흐름이 변경되어 PSCredential을 통한 사용자 로그인이 일시적으로 제거됩니다. 이 기능은 Windows용 PowerShell 5.1에 대한 2019년 1월 15일 릴리스에서 다시 도입됩니다. 이는 이 GitHub 문제에서 자세히 설명하고 있습니다.

웹 브라우저 프롬프트 대신 기본 디바이스 코드 로그인

.NET 표준의 인증 흐름이 변경되어 대화식 로그인 중에 기본 로그인 흐름으로 디바이스 로그인을 사용합니다. 웹 브라우저 기반 로그인은 Windows용 PowerShell 5.1에 대한 2019년 1월 15일 릴리스에서 기본적으로 다시 도입됩니다. 이때 사용자는 스위치 매개 변수를 사용하여 디바이스 로그인을 선택할 수 있습니다.

모듈의 호환성이 손상되는 변경

이 섹션에서는 개별 모듈 및 cmdlet에 대한 특정 호환성이 손상되는 변경에 대해 자세히 설명합니다.

Az.ApiManagement(이전에는 AzureRM.ApiManagement)

  • 다음 cmdlet이 제거되었습니다.
    • New-AzureRmApiManagementHostnameConfiguration
    • Set-AzureRmApiManagementHostnames
    • Update-AzureRmApiManagementDeployment
    • Import-AzureRmApiManagementHostnameCertificate
    • 대신 Set-AzApiManagement를 사용하여 이러한 속성을 설정합니다.
  • 다음 속성이 제거되었습니다.
    • PsApiManagementContext에서 PsApiManagementHostnameConfiguration 형식의 PortalHostnameConfiguration, ProxyHostnameConfiguration, ManagementHostnameConfiguration, ScmHostnameConfiguration 속성을 제거했습니다. 대신 PsApiManagementCustomHostNameConfiguration 형식의 PortalCustomHostnameConfiguration, ProxyCustomHostnameConfiguration, ManagementCustomHostnameConfiguration, ScmCustomHostnameConfiguration을 사용합니다.
    • PsApiManagementContext에서 StaticIPs속성을 제거했습니다. 해당 속성은 PublicIPAddresses, PrivateIPAddresses로 분할되었습니다.
    • 필수 속성 Location을 New-AzureApiManagementVirtualNetwork cmdlet에서 제거했습니다.

Az.Billing(이전에는 AzureRM.Billing, AzureRM.Consumption, 및 AzureRM.UsageAggregates)

  • InvoiceName 매개 변수가 Get-AzConsumptionUsageDetail cmdlet에서 제거되었습니다. 스크립트는 청구서에 대한 다른 ID 매개 변수를 사용해야 합니다.

Az.Compute(이전에는 AzureRM.Compute)

  • PSVirtualMachine 및 PSVirtualMachineScaleSet 객체의 Identity 속성에서 IdentityIds가 제거되었습니다. 스크립트는 더 이상 이 필드의 값을 사용하여 처리 결정을 내려서는 안됩니다.
  • PSVirtualMachineScaleSetVM 개체의 InstanceView 속성의 형식이 VirtualMachineInstanceView에서 VirtualMachineScaleSetVMInstanceView로 변경되었습니다.
  • UpgradePolicy 속성에서 AutoOSUpgradePolicy 및 AutomaticOSUpgrade 속성이 제거되었습니다.
  • PSSnapshotUpdate 개체의 Sku 속성의 형식이 DiskSku에서 SnapshotSku로 변경되었습니다.
  • VmScaleSetVMParameterSet이 Add-AzVMDataDisk cmdlet에서 제거되어, 더 이상 ScaleSet VM에 개별적으로 데이터 디스크를 추가할 수 없습니다.

Az.KeyVault(이전에는 AzureRM.KeyVault)

  • PSKeyVaultKeyAttributes, PSKeyVaultKeyIdentityItem 및 PSKeyVaultSecretAttributes 개체에서 PurgeDisabled 속성이 제거되었습니다. 스크립트는 처리 결정을 내리기 위해 PurgeDisabled 속성을 더 이상 참조하지 않아야 합니다.

Az.Monitor(이전에는 AzureRM.Insights)

  • Set-AzDiagnosticSetting cmdlet 스크립트에서 다음을 사용하여 단일 매개 변수 이름을 위해 복수 이름 Categories 및 Timegrains 매개 변수를 제거했습니다.

    Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2

    다음과 같이 변경되어야 합니다.

    Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2

Az.Network(이전에는 AzureRM.Network)

  • 사용되지 않는 매개 변수 ResourceId를 Get-AzServiceEndpointPolicyDefinition cmdlet에서 제거
  • PSVirtualNetwork 개체에서 사용되지 않는 속성 EnableVmProtection을 제거했습니다.
  • 사용되지 않는 cmdlet 제거: Set-AzVirtualNetworkGatewayVpnClientConfig

스크립트는 더 이상 이 필드의 값에 따라 처리하도록 결정하지 않아야 합니다.

Az.Resources(이전에는 AzureRM.Resources)

  • New/Set-AzPolicyAssignment cmdlet에서 Sku 매개 변수를 제거했습니다.

  • New-AzADServicePrincipal 및 New-AzADSpCredential cmdlet에서 Password 매개 변수를 제거했습니다. 암호는 자동으로 생성되며 암호를 제공하는 스크립트는 다음과 같습니다.

    New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476 -Password $secPassword

    출력에서 암호를 검색하도록 변경해야 합니다.

    $credential = New-AzAdSpCredential -ObjectId 1f99cf81-0146-4f4e-beae-2007d0668476
$secPassword = $credential.Secret

Az.Storage(이전에는 Azure.Storage 및 AzureRM.Storage)

  • 스토리지 계정 이름만 사용하여 Oauth 스토리지 컨텍스트를 만들 수 있도록 기본 매개 변수 집합이 OAuthParameterSet으로 변경되었습니다.
    • 예: $ctx = New-AzureStorageContext -StorageAccountName $accountName
  • Location 매개 변수가 Get-AzStorageUsage cmdlet에서 필수 항목이 되었습니다.
  • 이제 Storage API 메서드는 동기 API 호출 대신 작업 기반 비동기 패턴(TAP)을 사용합니다. 다음 예제에서는 새 비동기 명령을 보여 줍니다.

Blob 스냅샷

AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$b.ICloudBlob.Snapshot()

Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$task = $b.ICloudBlob.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

공유 스냅샷

AzureRM:

$Share = Get-AzureStorageShare -Name $containerName -Context $ctx
$snapshot = $Share.Snapshot()

Az:

$Share = Get-AzStorageShare -Name $containerName -Context $ctx
$task = $Share.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

일시 삭제된 Blob 삭제 취소

AzureRM:

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$b.ICloudBlob.Undelete()

Az:

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$task = $b.ICloudBlob.UndeleteAsync()
$task.Wait()

Blob 계층 설정

AzureRM:

$blockBlob = Get-AzureStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$blockBlob.ICloudBlob.SetStandardBlobTier("hot")

$pageBlob = Get-AzureStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$pageBlob.ICloudBlob.SetPremiumBlobTier("P4")

Az:

$blockBlob = Get-AzStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$task = $blockBlob.ICloudBlob.SetStandardBlobTierAsync("hot")
$task.Wait()

$pageBlob = Get-AzStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$task = $pageBlob.ICloudBlob.SetPremiumBlobTierAsync("P4")
$task.Wait()

Az.Websites(이전에는 AzureRM.Websites)

  • 사용되지 않는 속성을 PSAppServicePlan, PSCertificate, PSCloningInfo, PSSite 개체에서 제거했습니다.

다음 단계