잘못된 템플릿 오류 해결

  • 아티클

이 문서에서는 Bicep 파일 및 Azure Resource Manager 템플릿(ARM 템플릿)에 대한 잘못된 템플릿 오류를 해결하는 방법을 설명합니다. 이 오류는 구문 오류, 잘못된 매개 변수 값 또는 순환 종속성과 같은 몇 가지 이유로 발생합니다.

증상

템플릿이 배포되면 다음을 나타내는 오류가 표시됩니다.

Code=InvalidTemplate
Message=<varies>

오류 메시지는 오류 유형에 따라 다릅니다.

원인

이 오류로 인해 별도의 몇 가지 유형의 오류가 발생할 수 있습니다. 일반적으로 템플릿에는 구문 또는 구조 오류가 있습니다.

해결 방법 1: 구문 오류

템플릿 유효성 검사 실패를 나타내는 오류 메시지가 표시되면 템플릿 구문에 문제가 있습니다.

Code=InvalidTemplate
Message=Deployment template validation failed

템플릿 식에는 요소가 많기 때문에 구문 오류가 발생할 수 있습니다. 예를 들어 스토리지 계정에 대한 이름 할당에는 단일 또는 이중 따옴표 쌍, 중괄호, 정사각형 대괄호 및 대괄호가 포함됩니다. 식에는 달러 기호, 콤마 및 점과 같은 함수와 문자도 포함되어 있습니다.

name: 'storage${uniqueString(resourceGroup().id)}'

이러한 유형의 오류를 수신하면 식 구문을 검토합니다. 구문 오류를 식별하기 위해 최신 Bicep 확장 또는 Azure Resource Manager Tools 확장과 함께 Visual Studio Code를 사용할 수 있습니다.

해결 방법 2: 잘못된 세그먼트 길이

리소스 이름이 올바른 형식이 아닐 경우 다른 잘못된 템플릿 오류가 발생합니다. 이 오류를 해결하려면 이름 및 형식 불일치 오류 해결을 참조하세요.

해결 방법 3: 매개 변수가 유효하지 않음

템플릿에서 매개 변수의 허용된 값을 지정할 수 있습니다. 배포하는 동안 허용된 값이 아닌 값을 제공하는 경우 다음 오류와 유사한 메시지가 표시됩니다.

Code=InvalidTemplate;
Message=Deployment template validation failed: 'The provided value {parameter value}
for the template parameter {parameter name} is not valid. The parameter value is not
part of the allowed values

매개 변수의 허용된 값에 대한 템플릿을 확인하고 배포 중에 허용된 값을 사용합니다. 자세한 내용은 Bicep 또는 ARM 템플릿에 대해 허용된 값을 참조하세요.

해결 방법 4: 너무 많은 대상 리소스 그룹

단일 배포에서는 5개의 대상 리소스 그룹으로 제한되어 있기 때문에 이전 배포에서 이 오류가 표시될 수 있습니다. 2020년 5월, 이 제한이 800개의 리소스 그룹으로 증가되었습니다. 자세한 내용은 Bicep 또는 ARM 템플릿을 위해 여러 리소스 그룹을 배포하는 방법을 참조하세요.

해결 방법 5: 순환 종속성이 발견됨

이 오류 메시지는 배포가 시작될 수 없도록 리소스가 서로 종속되어 있는 경우에 표시됩니다. 상호 종속성의 조합은 둘 이상의 리소스가 이미 대기 중인 다른 리소스를 기다리게 만듭니다. 예를 들어 resource1은 resource3에 따라 달라지고, resource2는 resource1에 따라 달라지고, resource3는 resource2에 따라 달라집니다. 일반적으로 이런 문제는 불필요한 종속성을 제거하여 해결할 수 있습니다.

Bicep는 하나의 리소스가 다른 리소스의 기호 이름을 사용할 때 암시적 종속성이 생성됩니다. 일반적으로 dependsOn을 사용하는 명시적 종속성은 필요하지 않습니다. 자세한 내용은 Bicep 종속성을 참조하세요.

순환 종속성을 해결하려면:

  1. 템플릿에서 순환 종속성 내에 식별된 리소스를 찾습니다.
  2. 해당 리소스에 대해 dependsOn 속성 및 reference 또는 resourceId 함수가 사용되었는지 검토하여 어떤 리소스에 종속되는지 확인합니다.
  3. 해당 리소스를 검토하여 어떤 리소스에 종속되는지 확인합니다. 원래 리소스에 종속되는 리소스를 확인할 때까지 종속성을 추적합니다.
  4. 순환 종속성에 관련된 리소스의 경우 dependsOn 속성이 사용된 부분을 신중하게 모두 검토하여 필요하지 않은 종속성이 있는지 식별합니다. 배포 문제를 해결하려면 순환 종속성을 제거합니다. 코드를 삭제하는 대신 주석을 사용하여 다음 배포 중에 코드가 실행되지 않도록 할 수 있습니다. ARM 템플릿 또는 Bicep 파일에서 한 줄 주석(//) 또는 여러 줄 주석(/* ... */)을 사용할 수 있습니다.
  5. 템플릿을 다시 배포합니다.

dependsOn 속성에서 값을 제거하면 템플릿을 배포할 때 오류가 발생할 수 있습니다. 오류가 발생하면 해당 종속성을 템플릿에 다시 추가합니다. 주석을 사용하여 템플릿의 코드를 바이패스한 경우 주석을 제거하여 코드를 복원할 수 있습니다.

이러한 방법으로 순환 종속성 문제가 해결되지 않으면 일부 배포 논리를 자식 리소스(예: 확장 또는 구성 설정)로 이동하는 것이 좋습니다. 순환 종속성에 관련된 리소스를 배포한 후에 자식 리소스를 배포하도록 구성합니다. 예를 들어 두 개의 가상 머신을 배포하지만 각 컴퓨터에 서로를 참조하는 속성을 설정해야 한다고 가정합니다. 이런 경우 다음과 같은 순서로 배포할 수 있습니다.

  1. vm1
  2. vm2
  3. vm1의 확장은 vm1 및 vm2에 종속됩니다. 이 확장은 vm2에서 얻은 값을 vm1에 설정합니다.
  4. vm2의 확장은 vm1 및 vm2에 종속됩니다. 이 확장은 vm1에서 얻은 값을 vm2에 설정합니다.

동일한 방식이 App Service 앱에 적합합니다. 구성 값을 앱 리소스의 자식 리소스로 이동하는 것이 좋습니다. 두 개의 웹앱을 다음과 같은 순서로 배포할 수 있습니다.

  1. webapp1
  2. webapp2
  3. webapp1의 구성은 webapp1 및 webapp2에 따라 다릅니다. webapp2의 값을 사용하는 앱 설정이 포함됩니다.
  4. webapp2의 구성은 webapp1 및 webapp2에 따라 다릅니다. webapp1의 값을 사용하는 앱 설정이 포함됩니다.

해결 방법 6: 내보낸 템플릿에 대한 구문 유효성 검사

Azure에서 리소스를 배포한 후 ARM 템플릿 JSON을 내보내고 다른 배포에 맞게 수정할 수 있습니다. 리소스를 배포하는 데 사용하기 ‘전에’ 내보낸 템플릿의 구문이 올바른지 검사해야 합니다.

포털, Azure CLI 또는 Azure PowerShell에서 템플릿을 내보낼 수 있습니다. 리소스 또는 리소스 그룹에서 템플릿을 내보냈거나 배포 기록에서 템플릿을 내보낸 경우 권장 사항이 있습니다.

ARM 템플릿을 내보낸 후 JSON 템플릿을 Bicep으로 디컴파일할 수 있습니다. 그런 다음, 모범 사례 및 Linter를 사용하여 코드의 유효성을 검사합니다.

자세한 내용은 다음 문서를 참조하세요.