리소스를 Bicep 파일로 변환 및 마이그레이션

10분

Bicep으로 마이그레이션하는 프로세스를 시작할 때 구조화된 프로세스를 따라 Bicep 파일이 Azure 리소스를 올바르게 설명하는지 확인하는 것이 중요합니다. Bicep 코드가 모범 사례를 따르고 후속 배포에 사용할 수 있도록 완전히 테스트되고 안전한지 확인해야 합니다. 이 단원에서는 변환 단계와 마이그레이션 단계라는 Bicep 마이그레이션의 처음 두 단계를 알아봅니다.

Diagram that shows the convert and migrate phases of the recommended workflow for migrating Azure resources to Bicep.

이 두 단계의 기본 초점은 나중에 리팩터링하고 테스트하기 전에 새 Bicep 파일을 준비하는 것입니다.

단계 변환

리소스를 Bicep으로 마이그레이션하는 변환 단계의 목표는 Azure 리소스의 초기 표현을 캡처하는 것입니다. 이 단계에서 생성하는 Bicep 파일은 완전하지 않으며 사용할 준비가 되지 않았습니다. 그러나 해당 파일은 마이그레이션의 시작점을 제공합니다.

변환 단계는 순서대로 완료하는 두 개의 가능한 단계로 구성됩니다.

Azure 리소스의 표현을 캡처합니다.
필요한 경우 decompile 명령을 사용하여 JSON 표현을 Bicep으로 변환합니다.

Diagram that shows a JSON template decompiled to JSON, and Azure resources that are exported to a JSON template, which is then decompiled.

Bicep으로 변환하려는 기존 JSON 템플릿이 있는 경우 첫 번째 단계는 간단합니다. 원본 템플릿 이미 있기 때문입니다. 이 단원에서는 Bicep으로 디컴파일하는 방법을 알아봅니다.

Azure Portal 또는 다른 도구를 사용하여 배포된 Azure 리소스를 변환하는 경우 리소스 정의를 캡처해야 합니다. 리소스 정의를 내보내고 Bicep으로 변환하거나 Visual Studio Code의 리소스 삽입 명령을 사용하여 Azure 리소스 의 Bicep 표현을 삽입할 수 있습니다.

Azure가 리소스를 표현하는 방법

Azure Resource Manager는 Azure에서 리소스를 배포하고 관리하는 데 사용되는 서비스입니다. Azure에 배포된 모든 리소스는 리소스 배포에 사용한 메서드와 관계없이 Resource Manager에서 추적합니다. Azure Portal, Azure CLI, Azure PowerShell, Resource Manager REST API, Azure SDK를 사용하여 Resource Manager와 상호 작용할 수 있습니다.

Diagram that shows Resource Manager accepting requests from all Azure clients and libraries.

Azure에서 컨트롤 플레인 작업과 데이터 평면 작업이라는 두 가지 유형의 작업이 있습니다. 컨트롤 플레 인 작업은 구독의 리소스를 관리하는 데 사용됩니다. 데이터 평면 작업은 리소스에 의해 노출되는 기능에 액세스하는 데 사용됩니다. 예를 들어 컨트롤 플레인 작업을 사용하여 가상 머신을 만들지만 데이터 평면 작업을 사용하여 RDP(원격 데스크톱 프로토콜)를 통해 가상 머신에 연결합니다.

기존 리소스를 JSON 템플릿으로 내보내기

Azure 리소스가 만들어지는 방식과 관계없이 Resource Manager는 각 리소스에 대한 정보를 JSON 형식으로 제공합니다. 리소스의 JSON 표현 복사본을 요청하면 리소스를 내보냅니다. 내보내는 JSON 파일을 Bicep으로 디컴파일할 수 있습니다.

Resource Manager는 Azure 리소스를 템플릿으로 내보내는 여러 가지 방법을 제공합니다. Azure Portal, Azure CLI, Azure PowerShell cmdlet을 사용하여 단일 리소스, 여러 리소스, 전체 리소스 그룹을 내보낼 수 있습니다.

내보내기 프로세스는 컨트롤 플레인 작업입니다. 즉, Azure 리소스의 구성만 내보냅니다. 예를 들어 가상 머신을 내보낼 때 가상 머신의 하드 드라이브에 있는 데이터는 내보내지지 않습니다. 스토리지 계정을 내보낼 때 스토리지 계정의 Blob 및 기타 콘텐츠는 내보내기 프로세스를 통해 내보내지지 않습니다.

기존 리소스를 내보낼 때 몇 가지 사항을 고려해야 합니다.

내보낸 리소스 정의는 해당 리소스의 현재 상태에 대한 스냅샷입니다. 여기에는 초기 배포 이후 리소스에 대한 모든 변경 사항이 포함됩니다.
내보낸 템플릿에는 Bicep 정의에서 일반적으로 생략되는 몇 가지 기본 리소스 속성이 포함될 수 있습니다. 예를 들어 내보내기 프로세스는 Azure에서 자동으로 설정하는 읽기 전용 속성을 추가할 수 있습니다. 읽기 전용이므로 이를 포함하는 것은 의미가 없습니다. Bicep으로 마이그레이션할 때 리소스 정의에서 해당 속성을 제거하여 Bicep 파일에 혼동을 일으킬 수 있는 불필요한 코드가 없도록 하는 것이 좋습니다.
내보낸 템플릿에는 템플릿을 다시 사용할 수 있도록 하는 데 필요한 매개 변수가 모두 포함되지 않을 수 있습니다. 템플릿을 내보낼 때 많은 속성이 템플릿으로 하드 코드됩니다. 이 모듈의 뒷부분에서 매개 변수를 추가하는 방법을 확인할 수 있습니다.
일부 리소스는 이 접근 방식을 사용하여 내보낼 수 없으며 Bicep 파일에서 수동으로 정의해야 합니다. 이 단원의 뒷부분에서 해당 리소스를 다시 만드는 방법을 알아봅니다.

JSON 템플릿에 배포 저장

Azure Portal에서 리소스를 수동으로 배포한 적이 있는 경우 검토 + 만들기 탭에서 자동화 용 템플릿을 다운로드하는 옵션을 발견했을 수 있습니다. 이 옵션은 포털에서 리소스를 만드는 동안 설정한 이름과 속성을 기반으로 하는 JSON ARM 템플릿을 저장합니다.

Resource Manager는 배포도 추적합니다. 배포 작업에는 Azure Portal 리소스 만들기 환경 및 ARM 템플릿 배포에서 제출한 변경 내용이 포함됩니다. Azure Portal, Azure PowerShell cmdlet, Azure CLI 또는 기타 도구를 사용하여 변경한 기존 리소스는 일반적으로 배포를 만들지 않습니다.

호환되는 도구를 사용하여 배포를 만든 경우 리소스 그룹의 배포 기록에서 배포 템플릿에 액세스할 수 있습니다. Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 배포를 저장할 수 있습니다.

이 방법을 사용하여 템플릿을 저장할 때 몇 가지 사항을 고려해야 합니다.

저장된 템플릿은 배포 시 리소스의 상태를 보여 줍니다. 배포 후에 변경된 사항은 포함되지 않습니다.
배포에 여러 리소스가 포함된 경우 포함/제외할 특정 리소스를 선택할 수 없습니다. 이 작업은 초기 배포의 일부인 모든 리소스의 정의를 다운로드합니다. 그러나 프로세스의 마이그레이션 단계로 이동하면 필요하지 않은 리소스를 수동으로 무시할 수 있습니다.
템플릿에는 배포에 필요한 리소스 속성만 포함됩니다.
템플릿에는 여러 환경에서 템플릿을 다시 배포하는 데 사용할 수 있는 매개 변수가 포함될 수 있습니다. 그러나 매개 변수가 요구 사항에 적합한지도 확인해야 합니다.
템플릿에는 아마도 불필요한 속성이 포함되지는 않았을 것이지만 템플릿에 예상한 모든 항목이 포함되어 있는지 확인하고 불필요한 모든 속성을 제거해야 합니다.

참고

그러나 기존 리소스를 내보내거나 배포를 저장하여 리소스를 내보내는 경우 내보낸 파일을 시작점으로 취급하고 직접 사용하지 마세요. 대신 최종 템플릿의 시작점으로 사용합니다.

기존 리소스를 Bicep에 삽입하기

Visual Studio Code용 Bicep 확장에는 Azure 리소스의 Bicep 표현을 캡처하는 리소스 삽입 명령이 포함되어 있습니다. 이 명령은 Azure에서 리소스의 JSON 정의를 읽고, 읽기 전용으로 인식되는 속성을 제거하고, JSON을 Bicep으로 디컴파일합니다. 내보내기 함수와 마찬가지로 결과 Bicep 코드를 최종 Bicep 파일의 시작점으로 사용할 수 있습니다.

Visual Studio Code 명령 팔레트를 열어 리소스를 삽입할 수 있습니다. Windows 및 Linux에서는 Ctrl+Shift+P를 사용하고 macOS에서는 ⌘+Shift+P를 사용합니다.

원본 JSON ARM 템플릿 디컴파일

Azure 리소스를 Bicep으로 마이그레이션하는 두 번째 단계는 JSON ARM 템플릿 및 Azure 리소스를 Bicep 템플릿으로 변환하는 것입니다. Bicep 도구에는 템플릿을 변환하는 decompile 명령이 포함되어 있습니다. Azure CLI 또는 Bicep CLI에서 decompile 명령을 호출할 수 있습니다.

디컴파일 프로세스는 JSON에서 Bicep으로의 전체 매핑을 보장하지 않습니다. 파일을 사용하여 리소스를 배포하기 전에 템플릿 모범 사례를 충족하도록 생성된 Bicep 파일을 수정해야 할 수 있습니다. 이를 마이그레이션의 시작점으로 생각하세요. 이 모듈의 뒷부분에서는 디컴필레이션 프로세스 중에 발생하는 문제를 해결하는 방법을 알아봅니다.

템플릿을 디컴파일한 다음 변환 단계를 완료했습니다. 이제 시작할 유효한 Bicep 파일이 있습니다.

마이그레이션 단계

리소스를 Bicep으로 마이그레이션하는 마이그레이션 단계의 목표는 배포 가능한 Bicep 파일의 첫 번째 초안을 만들고 마이그레이션 범위에 있는 모든 Azure 리소스를 정의하는 것입니다.

마이그레이션 단계는 순서대로 완료하는 세 단계로 구성됩니다.

비어 있는 새 Bicep 파일을 만듭니다.
디컴파일된 템플릿에서 각 리소스를 복사합니다.
누락된 리소스를 확인하고 다시 만듭니다.

Diagram that shows the steps for migrating a template to Bicep.

새 Bicep 파일 만들기

새로운 Bicep 파일을 만드는 것이 좋습니다. 변환 단계에서 만든 파일은 살펴볼 참조 지점이지만 최종 파일로 처리하거나 있는 그대로 배포해서는 안 됩니다.

새 Bicep 파일에 리소스 복사

변환된 Bicep 파일에서 새 Bicep 파일로 각 리소스를 개별적으로 복사합니다. 이 프로세스를 통해 리소스별로 문제를 해결하고 템플릿이 커지면 혼동을 방지할 수 있습니다.

지원하지 않는 리소스 다시 만들기

Azure Portal, Azure CLI 또는 Azure PowerShell을 통해 모든 Azure 리소스 유형을 내보낼 수 있는 것은 아닙니다. 예를 들어 DependencyAgentWindows 및 MMAExtension(Microsoft Monitoring Agent)과 같은 가상 머신 확장은 내보낼 수 없는 리소스 종류입니다.

Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 리소스를 내보내려고 할 때 지원되지 않는 리소스 종류가 포함되면 자세한 오류 메시지가 생성됩니다. 새 Bicep 파일에서 가상 머신 확장과 같이 내보내지 않은 리소스를 다시 만들어야 합니다. Azure Resource Explorer, ARM 템플릿 참조 및 Azure 빠른 시작 템플릿을 포함하여 리소스를 다시 만드는 여러 도구 및 방법 중에서 선택할 수 있습니다.

Azure Resource Explorer

Azure Resource Explorer는 Azure Portal에 포함된 도구입니다. 포털에는 특정 리소스 종류가 표시되지 않지만 Resource Explorer는 해당 리소스의 JSON 표현을 제공할 수 있습니다. Resource Explorer에 액세스하려면 검색 상자에서 이를 검색합니다.

Screenshot of the Azure portal that shows the search box with resource explorer entered.

결과 창에는 구독에 대해 등록된 리소스 공급자 목록과 볼 수 있는 권한이 있는 모든 리소스, 리소스 그룹 및 구독에 대한 세부 정보가 표시됩니다. 리소스의 JSON 표현을 보려면 창 왼쪽에서 계층 구조를 선택합니다.

Screenshot of the Azure portal that shows Azure Resource Explorer.

리소스를 선택하면 다음 예제와 같이 JSON 표현을 볼 수 있습니다.

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

이 JSON 표현을 사용하여 Bicep 리소스를 직접 정의할 수 있습니다.

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

참고

JSON 표현에는 provisioningState라는 속성이 포함됩니다. provisioningState 속성은 읽기 전용으로, Azure에서 자동으로 설정되므로 Bicep 리소스 정의에 포함되지 않습니다.

팁

Visual Studio Code용 Bicep 확장은 Bicep에서 Azure 리소스를 정의하는 데 도움이 됩니다. 예를 들어 리소스의 Bicep 표현에는 API 버전이 포함되지만 내보낸 JSON 버전에는 포함되지 않습니다. Visual Studio Code에서 리소스 종류를 입력하기 시작하면 API 버전이 자동으로 제안됩니다.

ARM 템플릿 참조

ARM 템플릿 참조는 ARM 템플릿 구조, 리소스 종류, API 버전, Azure 리소스에 대한 속성 정의에 대한 정보를 제공합니다. 설명서는 Bicep 및 JSON 형식의 예제를 제공합니다.

특정 리소스 공급자 및 리소스 종류(예: Microsoft.Web/serverfarms 및 해당 API 버전)를 선택할 수 있습니다. 필수 리소스 속성과 선택 리소스 속성을 검토할 수 있습니다. 속성이 수행하는 작업을 이해하는 데 도움이 되는 속성 설명을 볼 수도 있습니다.

Azure 빠른 시작 템플릿

Azure 빠른 시작 템플릿 리포지토리는 커뮤니티에서 제공하는 템플릿 컬렉션입니다. 이 검색 가능한 템플릿 리포지토리는 많은 Azure 리소스 및 솔루션 예제를 제공합니다. 일부 빠른 시작에서는 JSON ARM 템플릿과 Bicep ARM 템플릿을 모두 볼 수 있습니다. 이러한 템플릿을 참조 지점으로 사용하여 배포할 템플릿을 빌드하고 확인할 수 있습니다.

Azure App Service 요금제 및 앱을 빌드하는 템플릿을 찾으려고 한다고 가정하겠습니다. 각 빠른 시작 템플릿은 템플릿을 Azure에 직접 배포하거나 GitHub에서 템플릿을 볼 수 있는 옵션을 제공합니다.

Screenshot that shows an Azure Quickstart Template that deploys a basic Linux web app.

Azure 빠른 시작 템플릿은 커뮤니티 기여로 이루어졌습니다. 기능이 Azure 서비스에 정기적으로 추가되기 때문에 일부 예제는 최신이 아닐 수 있습니다. 예제에는 템플릿을 사용하는 데 필요하지 않은 리소스 및 속성이 포함될 수도 있습니다. 하지만 빠른 시작 템플릿의 리포지토리는 ARM 템플릿을 사용하여 리소스를 배포하는 방법을 이해하는 데 유용한 리소스입니다.