빠른 시작: Bicep 파일 배포 문제 해결

2025-05-01

이 빠른 시작에서는 Bicep 파일 배포 오류를 해결하는 방법을 설명합니다. 오류가 있는 파일을 만들고 오류를 해결하는 방법을 알아봅니다.

배포와 관련된 세 가지 유형의 오류가 있습니다.

검증 오류는 배포가 시작되기 전에 발생하며 파일의 구문 오류로 인해 발생합니다. Visual Studio Code와 같은 코드 편집기는 이러한 오류를 식별할 수 있습니다.
배포 명령이 실행되지만 리소스가 배포되지 않은 경우 실행 전 유효성 검사 오류가 발생합니다. 이러한 오류는 배포를 시작하지 않고 발견됩니다. 예를 들어 매개 변수 값이 잘못된 경우 실행 전 유효성 검사에서 오류가 발견됩니다.
배포 오류는 배포 프로세스 중에 발생하며 Azure 환경에서 배포 진행 상황을 평가해야만 찾을 수 있습니다.

모든 오류 유형에서 배포 문제를 해결하는 데 사용하는 오류 코드를 반환합니다. 유효성 검사 및 실행 전 오류는 활동 로그에 표시되지만 배포 기록에는 표시되지 않습니다. 구문 오류가 있는 Bicep 파일은 JSON으로 컴파일되지 않으며 활동 로그에 표시되지 않습니다.

필수 조건

이 빠른 시작을 완료하려면 다음 항목이 필요합니다.

Azure 구독이 없는 경우, 시작하기 전에 무료 계정을 만드십시오.
최신 Bicep 확장이 있는 Visual Studio Code.
Azure PowerShell 또는 Azure CLI의 최신 버전입니다.

오류가 있는 Bicep 파일 만들기

다음 Bicep 파일을 복사하여 로컬로 저장합니다. 이 파일을 사용하여 유효성 검사 오류, 실행 전 오류 및 배포 오류를 해결합니다. 이 빠른 시작에서는 파일 이름을 troubleshoot.bicep이라고 가정하지만, 다른 이름을 지정할 수 있습니다.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  ___location: resourceGroup().___location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
  name: 'doesnotexist'
}

output storageAccountName string = storageAccountName
output vnetResult object = existingVNet

유효성 검사 오류 해결

Visual Studio Code에서 파일을 엽니다. Visual Studio Code는 구문 오류를 식별합니다. 첫 번째 매개 변수 선언은 오류를 나타내기 위해 빨간색 물결선으로 표시됩니다.

Bicep 파일의 구문 오류를 강조 표시하는 빨간색 물결선이 있는 Visual Studio Code의 스크린샷

오류로 표시된 줄은 다음과 같습니다.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

마우스를 parameter 위에 올리면 오류 메시지가 표시됩니다.

Bicep 파일의 구문 오류를 마우스로 가리킬 때 Visual Studio Code에 표시되는 자세한 오류 메시지의 스크린샷

메시지 상태: 이 선언 형식을 인식할 수 없습니다. 매개 변수, 변수, 리소스 또는 출력 선언을 지정합니다. 이 파일을 배포하려고 하면 배포 명령에서 동일한 오류 메시지가 표시됩니다.

매개 변수 선언에 대한 설명서를 보면 키워드가 실제로 param표시됩니다. 해당 구문을 변경하면 유효성 검사 오류가 사라집니다. @allowed 데코레이터도 오류로 표시되었지만 매개 변수 선언을 변경하여 해당 오류도 해결됩니다. 데코레이터 다음에 매개 변수 선언이 예상되므로 데코레이터가 오류로 표시되었습니다. 선언이 잘못되었을 때 이 조건은 참이 아니었습니다.

고정 줄은 다음과 같습니다.

param storageAccountType string = 'Standard_LRS'

실행 전 오류 수정

유효성 검사 오류를 수정했으므로 이제 파일을 배포할 차례입니다. 하지만 실행 전 오류를 보려면 잘못된 매개 변수 값을 제공합니다.

Azure CLI
PowerShell을 참조하십시오.

az group create --name troubleshootRG --___location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

New-AzResourceGroup -Name troubleshootRG -Location westus
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.bicep `
  -prefixName longNamewith!!Charactersthatarenotallowed

Azure Resource Manager는 스토리지 계정의 이름에 허용되지 않는 문자가 포함되어 있는지 확인합니다. 배포를 시도하지 않습니다.

실행 전 유효성 검사에 실패했음을 나타내는 오류 메시지가 표시됩니다. 또한 스토리지 계정 이름은 길이가 3자에서 24자 사이여야 하며 숫자와 소문자만 사용해야 한다는 메시지가 표시됩니다. 제공한 접두사는 해당 요구 사항을 충족하지 못했습니다. 이 오류 코드에 대한 자세한 내용은 스토리지 계정 이름에 대한 오류 해결을 참조하세요.

실행 전 오류가 발견되었으므로 기록에 배포가 없습니다.

Bicep 파일에 대한 배포가 없는 Azure Portal의 배포 기록 섹션 스크린샷

그러나 실패한 배포는 활동 로그에 있습니다.

Bicep 파일 배포에 대한 실행 전 유효성 검사 오류를 표시하는 Azure Portal의 활동 로그 스크린샷

로그 항목의 세부 정보를 열어 오류 메시지를 볼 수 있습니다.

배포 오류 수정

파일을 다시 배포하고 이름 접두사 매개 변수에 허용되는 값을 제공합니다.

Azure CLI
PowerShell을 참조하십시오.

az group create --name troubleshootRG --___location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=stg

New-AzResourceGroup -Name troubleshootRG -Location westus
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.bicep `
  -prefixName stg

배포가 시작되지만 가상 네트워크를 찾을 수 없다는 메시지와 함께 실패합니다. 일반적으로 리소스에 대한 참조를 변경하여 이 오류를 수정합니다. 이 빠른 시작에서는 참조를 삭제합니다. 이 오류 코드에 대한 자세한 내용은 리소스를 찾을 수 없는 오류 해결을 참조하세요.

포털에서 배포가 기록에 표시되는지 확인합니다.

Bicep 파일에 대한 실패한 배포를 보여 주는 Azure Portal의 배포 기록 섹션 스크린샷

배포 기록에서 항목을 열어 오류에 대한 세부 정보를 가져올 수 있습니다. 이 오류는 활동 로그에도 있습니다.

Bicep 파일은 리소스 그룹에 존재하지 않는 가상 네트워크를 참조하려고 시도합니다. 기존 가상 네트워크에 대한 참조를 삭제하여 오류를 해결합니다.

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  ___location: resourceGroup().___location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

output storageAccountName string = storageAccountName

오류 없이 해당 Bicep 파일을 배포할 수 있습니다.

자원을 정리하세요

Azure 리소스가 더 이상 필요하지 않으면 리소스 그룹을 삭제합니다. Cloud Shell 또는 포털에서 리소스 그룹을 삭제할 수 있습니다.

Azure CLI
PowerShell을 참조하십시오.

az group delete --name troubleshootRG

꺾쇠 괄호와 함께 <rgname>를 리소스 그룹 이름으로 바꾸십시오.

Remove-AzResourceGroup -Name troubleshootRG

포털에서 리소스 그룹을 삭제하려면 다음 단계를 따르세요.

Azure Portal의 검색 상자에 리소스 그룹을 입력합니다.
이름으로 필터링 필드에 리소스 그룹 이름을 입력합니다.
해당 리소스 그룹 이름을 선택합니다.
리소스 그룹 삭제를 선택합니다.
삭제를 확인하려면 리소스 그룹 이름을 입력하고 삭제를 선택합니다.

다음 단계

이 빠른 시작에서는 Bicep 파일 배포 오류를 해결하는 방법을 알아보았습니다.

일반적인 Azure 배포 오류 문제 해결