다음을 통해 공유

Azure VM Image Builder의 새로운 기능

  • 아티클

적용 대상: ✔️ Linux VM ✔️ Windows VM ✔️ 유연한 확장 집합 ✔️ 균일한 확장 집합

이 문서에는 Azure VM Image Builder(AIB) 서비스에 대한 모든 주요 API 변경 내용 및 기능 업데이트가 포함되어 있습니다.

업데이트

2024년 5월

호환성이 손상되는 변경: 대/소문자 구분

2024년 5월 21일부터 Azure VM Image Builder의 API 버전 2024-02-01 이상에서는 모든 필드에 대/소문자 구분을 적용합니다. 즉, API 요청에 포함된 문자의 대/소문자가 예상 형식과 정확히 일치해야 합니다.

Important

기존 Azure Image Builder 사용자를 위한 중요 참고 사항

Azure VM Image Builder의 기존 사용자인 경우 이 변경 내용이 기존 리소스에 영향을 미치지 않습니다. 대/소문자 구분 적용은 API 버전 2024-02-01 이상을 사용하여 새로 생성된 리소스에만 적용됩니다. 기존 리소스는 변경 없이 예상대로 계속 작동합니다.

대/소문자 구분과 관련된 문제가 발생하는 경우 Azure Image Builder의 업데이트된 API 설명서에서 지침을 참조하세요.

이전에는 Azure Image Builder의 API가 사례에 따라 좀 더 관대했지만 앞으로는 정확성이 매우 중요합니다. API를 호출할 때 필드 이름, 매개 변수 및 값의 대/소문자를 정확히 구분해 사용해야 합니다. 예를 들어 필드 이름이 “vmBoot”인 경우 반드시 “vmBoot”(“VMBoot” 또는 “vmboot” 불가)를 입력해야 합니다.

잘못된 대/소문자 또는 인식할 수 없는 필드를 사용하여 Azure Image Builder의 API 버전 2024-02-01 이상으로 API 요청을 보내는 경우 서비스는 이를 거부합니다. 요청이 잘못되었음을 나타내는 오류 응답이 표시됩니다. 오류는 다음과 같이 표시됩니다.

Unmarshalling entity encountered error: unmarshalling type *v2024_02_01.ImageTemplate: struct field Properties: unmarshalling type *v2024_02_01.ImageTemplateProperties: struct field Optimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize, unknown field \"vmboot\". There is an issue with the syntax with the JSON template you are submitting. Please check the JSON template for syntax and grammar. For more information on the syntax and grammar of the JSON template, visit http://aka.ms/azvmimagebuildertmplref.

오류 메시지는 "알 수 없는 필드"를 언급하고 공식 설명서로 안내합니다. Azure Image Builder Bicep 또는 ARM 템플릿 JSON 템플릿을 만드세요.

참고 항목

API 호출에 대한 Azure Image Builder의 Swagger 참조

Azure Image Builder 서비스를 호출할 때 항상 Swagger 설명서를 참조하세요. 이 설명서는 Azure Image Builder의 API 사양에 대한 확실한 소스 역할을 합니다. API 릴리스에 앞서 공개 설명서가 올바른 대문자와 필드 이름을 포함하도록 업데이트된 반면, Swagger 정의에는 서비스를 올바르게 호출할 수 있도록 각 AIB API에 대한 정확한 세부 정보가 포함되어 있습니다.

다음은 API 버전 2024-02-01의 필드 이름과 일치하도록 변경된 문서 목록입니다.

Azure Image Builder Bicep 또는 ARM 템플릿 JSON 템플릿 만들기 설명서 내:

업데이트된 필드:

  • vmboot에 대한 여러 멘션을 vmBoot(으)로 대체
  • imageVersionID에 대한 하나의 멘션을 imageVersionId(으)로 대체

제거된 필드:

  • apiVersion: 이 필드가 API에 명시적으로 지정되지 않았으므로 요청에 이 필드가 포함되지 않도록 하는 것이 좋습니다. 따라서 JSON 템플릿에 포함하면 이미지 빌드에 오류가 생길 수 있습니다.

Azure VM Image Builder 네트워킹 옵션 설명서 내:

업데이트된 필드:

  • VirtualNetworkConfig에 대한 하나의 멘션을 vnetConfig(으)로 대체

제거된 필드:

  • vnetConfig 속성의 subnetName - 이 필드는 더 이상 사용되지 않으며 새 필드는 subnetId임
  • vnetConfig 속성의 resourceGroupName - 이 필드는 더 이상 사용되지 않으며 새 필드는 subnetId임

이전 Azure Image Builder API 버전에 고정하는 방법

이전 API 버전에 고정에 대한 중요한 고려 사항

이전 Azure Image Builder API 버전에 고정하면 기존 템플릿과의 호환성이 제공되나 다음 요인으로 인해 권장되지 않습니다.

  • 사용 중단 위험: 이전 API 버전은 결국 완전히 사용 중단될 수 있습니다.

  • 누락된 기능: 이전 API 버전에 고정하면 최신 버전에 도입된 최신 기능과 향상된 기능을 놓칠 수 있습니다. 이러한 향상된 기능은 종종 성능, 보안 및 기능을 향상시킵니다.

새로운 대/소문자 구분 규칙으로 인해 이미지 템플릿의 속성을 변경하지 않으려면 Azure VM Image Builder API 호출을 이전 API 버전에 고정하는 옵션을 사용할 수 있습니다. 이렇게 하면 수정 없이 익숙한 동작으로 계속 사용할 수 있습니다.

기존 템플릿과의 호환성을 보장하려면 이미지 템플릿을 만들거나 업데이트할 때 서비스 호출에 api-version 매개 변수를 포함하여 원하는 API 버전(예: api-version=2022-07-01)을 지정합니다. 예시:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.VirtualMachineImages/imageTemplates/{imageTemplateName}?api-version=2022-07-01

코드 테스트

이전 API 버전에 고정한 후 코드를 테스트하여 예상대로 작동하는지 확인합니다. 기존 템플릿이 계속 올바르게 작동하는지 확인합니다.

2023년 11월

Azure Image Builder는 단계적 방식으로 Azure Container Instances를 사용하여 격리된 이미지 빌드를 사용하도록 설정합니다. 출시는 2024년 초까지 완료될 예정입니다. 기존 이미지 템플릿은 계속 작동하며 새 이미지 템플릿을 만들거나 빌드하는 방식은 변경되지 않습니다.

다른 임시 Azure 리소스 집합이 준비 리소스 그룹에 일시적으로 표시되지만 실제 빌드나 Azure Image Builder와 상호 작용하는 방식에는 영향을 주지 않습니다. 자세한 내용은 격리된 이미지 빌드를 참조하세요.

Important

구독이 Microsoft.ContainerInstance 공급자에 대해 등록되어 있고 Azure Container Instances 리소스 배포를 차단하는 정책이 없는지 확인합니다. 또한 Azure Container Instances 리소스에 할당량을 사용할 수 있는지 확인합니다.

2023년 4월

Azure Image Builder에 대한 새 포털 기능이 추가되었습니다. Azure Portal "이미지 템플릿"을 검색한 다음 "만들기"를 클릭합니다. 포털 내 사용자 지정 이미지 빌드 및 유효성 검사를 여기서 시작할 수도 있습니다.

API 릴리스

버전 2024-02-01

향상된 기능

  • 템플릿 만들기 또는 업데이트 시 이미지 빌드를 실행할 수 있는 새로운 autoRun 속성입니다. 자세한 내용은 속성: autoRun을 참조하세요.
  • Azure Image Builder 서비스가 이미지 빌드 중에 준비 리소스 그룹에 만드는 리소스에 태그를 적용할 수 있는 새로운 managedResourceTags 속성입니다. 자세한 내용은 속성: managedResourceTags를 참조하세요.
  • 격리된 빌드를 위해 Azure 컨테이너 인스턴스가 배포될 서브넷을 지정할 수 있는 새로운 containerInstanceSubnetId 속성입니다. 이 필드는 subnetId도 지정된 경우에만 지정할 수 있으며 subnetId에 지정된 서브넷과 동일한 Virtual Network에 있어야 합니다. 자세한 내용은 자체 빌드 VM 서브넷 가져오기 및 자체 ACI 서브넷 가져오기를 참조하세요.
  • 다음 필드를 포함하여 vmProfile 속성 업데이트에 대한 지원이 추가되었습니다.
    • vmSize
    • osDiskSizeGB
    • userAssignedIdentities
    • vnetConfig
      • subnetId
      • containerInstanceSubnetIdvmProfile 속성에 대한 자세한 내용은 vmProfile을 참조하세요.

변경 API 버전 2024-02-01에는 모든 필드에 대/소문자 구분을 적용하는 호환성이 손상되는 변경이 도입되었습니다. 즉, API 요청에 포함된 문자의 대/소문자가 예상 형식과 정확히 일치해야 합니다. 잘못된 대/소문자 또는 인식할 수 없는 필드를 사용하여 Azure Image Builder의 API 버전 2024-02-01 이상으로 API 요청을 보내는 경우 서비스는 이를 거부합니다. 요청이 잘못되었음을 나타내는 오류 응답이 표시됩니다. 자세한 내용은 호환성이 손상되는 변경: 대/소문자 구분을 참조하세요.

버전 2023-07-01

준비 중

Azure Compute Gallery 배포 대상 업데이트를 지원합니다.

변경

새 errorHandling 속성입니다. 이 속성을 사용하면 이미지 빌드 프로세스 중에 오류가 처리되는 방식을 더 효과적으로 제어할 수 있습니다. 자세한 내용은 errorHandling을 참조하세요.

버전 2022-07-01

향상된 기능

  • Azure Compute Gallery에 저장된 최신 이미지 버전을 이미지 템플릿의 원본으로 사용하는 지원이 추가되었습니다.
  • 이미지 배포에 대한 버전 번호 생성을 지원하기 위해 versioning이 추가되었습니다. 자세한 내용은 속성: 버전 관리를 참조하세요
  • Azure Compute Gallery에 배포할 때 지역별 구성에 대한 지원이 추가되었습니다. 자세한 내용은 Distribute:targetRegions를 참조하세요
  • 새 '파일' 유효성 검사 형식이 추가되었습니다. 자세한 내용은 속성 유효성 검사를 참조하세요
  • 이제 VHD를 사용자 지정 스토리지 계정의 사용자 지정 Blob 또는 컨테이너에 배포할 수 있습니다. 자세한 내용은 배포: VHD를 참조하세요
  • 직접 공유 갤러리 이미지를 이미지 템플릿의 원본으로 사용하기 위한 지원이 추가되었습니다

변경

  • replicationRegions는 이제 갤러리 배포에서 더 이상 사용되지 않습니다. 자세한 내용은 gallery-replicated-regions를 사용합니다
  • 이제 VHD를 사용자 지정 스토리지 계정의 사용자 지정 Blob 또는 컨테이너에 배포할 수 있습니다
  • targetRegions 배열이 추가되고 "SharedImage" 형식 배포에만 적용됩니다. targetRegions에 대한 자세한 내용은 Azure Compute Gallery 구성을 참조하세요
  • 직접 공유 갤러리 이미지를 이미지 템플릿의 원본으로 사용하기 위한 지원이 추가되었습니다. 직접 공유 갤러리는 현재 미리 보기로 제공됩니다.
  • 이제 트리거를 공개 미리 보기에서 사용하여 자동 이미지 빌드를 설정할 수 있습니다. 자세한 내용은 AIB 트리거를 사용하는 방법을 참조하세요

버전 2022-02-14

향상된 기능

버전 2021-10-01

주요 변경 내용

API 버전 2021-10-01은 모든 향후 API 릴리스의 일부가 될 오류 스키마를 변경합니다. Azure VM Image Builder 자동화가 있으면 API 버전 2021-10-01 이상으로 전환할 때 새 오류 출력을 알고 있어야 합니다. 최신 API 버전으로 전환한 후에는 이전 버전으로 되돌리지 않는 것이 좋습니다. 이전 오류 스키마를 생성하기 위해 자동화를 다시 변경해야 하기 때문입니다. Microsoft는 향후 릴리스에서 오류 스키마를 다시 변경하지 않습니다.

버전 2020-02-14 이전의 오류 출력
{ 
  "code": "ValidationFailed",
  "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
}
버전 2021-10-01 이후의 오류 출력
{ 
  "error": {
    "code": "ValidationFailed", 
    "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
  }
}

향상된 기능

  • VM MSI 빌드에 대한 지원이 추가되었습니다.
  • 프록시 VM 크기 사용자 지정에 대한 지원이 추가되었습니다.

버전 2020-02-14

향상된 기능

  • 다음 원본에서 이미지를 만들기 위한 지원이 추가되었습니다.
    • 관리형 이미지
    • Azure Compute Gallery
    • 플랫폼 이미지 리포지토리(플랫폼 이미지 구매 계획 포함)
  • 다음 사용자 지정에 대한 지원이 추가되었습니다.
    • Shell(Linux): 스크립트 또는 인라인
    • PowerShell(Windows): 스크립트 또는 인라인, 관리자 권한 실행, 시스템으로 실행
    • 파일(Linux 및 Windows)
    • Windows 다시 시작(Windows)
    • Windows 업데이트(Windows): 검색 조건, 필터 및 업데이트 제한
  • 다음 배포 유형에 대한 지원이 추가되었습니다.
    • VHD(가상 하드 디스크)
    • 관리형 이미지
    • Azure Compute Gallery
  • 기타 기능:
    • 고객이 자신의 가상 네트워크를 사용할 수 있도록 지원이 추가되었습니다.
    • 고객이 빌드 VM(VM 크기, 운영 체제 디스크 크기)을 사용자 지정할 수 있도록 지원이 추가되었습니다.
    • 사용자 할당 MSI(Microsoft Windows Installer)에 대한 지원이 추가되었습니다(사용자 지정/배포 단계용)
    • Gen2 이미지에 대한 지원이 추가되었습니다.

미리 보기 API

다음 API는 더 이상 사용되지 않지만 여전히 지원됩니다.

  • 버전 2019-05-01-preview

다음 단계

VM Image Builder에 대해 자세히 알아봅니다.