다음을 통해 공유

Bicep의 Azure Resource Manager 템플릿 사양

  • 아티클

템플릿 사양은 나중에 배포할 수 있도록 ARM 템플릿(Azure Resource Manager 템플릿)을 저장하기 위한 리소스 유형입니다. 이 리소스 유형을 사용하여 조직 내 다른 사용자와 ARM 템플릿을 공유할 수 있습니다. 다른 Azure 리소스와 마찬가지로 Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 템플릿 사양을 공유할 수 있습니다. Azure CLI 또는 Azure PowerShell을 통해 Bicep 파일을 제공하여 템플릿 사양을 만들 수 있습니다. Bicep 파일은 저장되기 전에 ARM JSON 템플릿으로 변환 컴파일됩니다. 현재 Azure Portal에서 Bicep 파일을 가져와 템플릿 사양 리소스를 만들 수 없습니다.

Microsoft.Resources/templateSpecs는 템플릿 사양에 대한 리소스 유형입니다. 기본 템플릿과 연결된 템플릿으로 구성됩니다. Azure는 리소스 그룹에 템플릿 사양을 안전하게 저장합니다. 기본 템플릿과 연결된 템플릿은 모두 JSON에 형식이어야 합니다. 템플릿 사양은 버전 관리를 지원합니다.

템플릿 사양을 배포하려면 PowerShell, Azure CLI, Azure Portal, REST 및 기타 지원되는 SDK 및 클라이언트와 같은 표준 Azure 도구를 사용합니다. 템플릿 또는 Bicep 파일에서와 동일한 명령을 사용합니다.

참고 항목

Azure PowerShell에서 Bicep의 템플릿 사양을 사용하려면 버전 6.3.0 이상을 설치해야 합니다. Azure CLI에서 사용하려면 버전 2.27.0 이상을 사용합니다.

배포를 디자인할 때 항상 리소스의 수명 주기를 고려하고 유사한 수명 주기를 공유하는 리소스를 단일 템플릿 사양으로 그룹화합니다. 예를 들어 배포에는 자체 데이터베이스 및 컨테이너가 포함된 각 인스턴스와 함께 여러 Azure Cosmos DB 인스턴스가 포함됩니다. 데이터베이스와 컨테이너가 많이 변경되지 않는 경우 Cosmo DB 인스턴스와 기본 데이터베이스 및 컨테이너를 포함할 하나의 템플릿 사양을 만들 수 있습니다. 그런 다음, 복사 루프와 함께 Bicep에서 조건 문을 사용하여 이러한 리소스의 여러 인스턴스를 만들 수 있습니다.

팁

모듈 레지스트리와 템플릿 사양 간의 선택은 대부분 기본 설정의 문제입니다. 두 가지 중 선택할 때 고려해야 할 몇 가지가 있습니다.

  • 모듈 레지스트리는 Bicep에서만 지원됩니다. 아직 Bicep를 사용하지 않는 경우 템플릿 사양을 사용합니다.
  • Bicep 모듈 레지스트리의 콘텐츠는 다른 Bicep 파일에서만 배포할 수 있습니다. 템플릿 사양은 API, Azure PowerShell, Azure CLI 및 Azure Portal에서 직접 배포할 수 있습니다. UiFormDefinition을 사용하여 포털 배포 환경을 사용자 지정할 수도 있습니다.
  • Bicep에는 loadTextContent 및 loadFileAsBase64 함수를 사용하여 다른 프로젝트 아티팩트(Bicep 및 ARM이 아닌 템플릿 파일 포함. 예: PowerShell 스크립트, CLI 스크립트 및 기타 이진 파일 포함)를 포함하는 데 몇 가지 제한된 기능이 있습니다. 템플릿 사양은 이러한 아티팩트를 패키지할 수 없습니다.

학습 리소스

템플릿 사양 및 실습 지침에 대한 자세한 내용은 템플릿 사양을 사용하여 다시 사용할 수 있는 인프라 코드 라이브러리 게시를 참조하세요.

필요한 사용 권한

템플릿 사양에 대해 정의된 Azure 기본 제공 역할은 두 가지입니다.

또한 Bicep 파일을 배포하기 위한 권한도 필요합니다. 배포 - CLI 또는 배포 - PowerShell을 참조하세요.

템플릿 사양을 사용하는 이유는 무엇인가요?

템플릿 사양은 다음과 같은 이점을 제공합니다.

  • 템플릿 사양에 대해 표준 ARM 템플릿 또는 Bicep 파일을 사용합니다.
  • SAS 토큰이 아닌 Azure RBAC를 통해 액세스를 관리합니다.
  • 사용자가 Bicep 파일에 쓰기 액세스 권한이 없어도 템플릿 사양을 배포할 수 있습니다.
  • PowerShell 스크립트 또는 DevOps 파이프라인과 같은 기존 배포 프로세스에 템플릿 사양을 통합할 수 있습니다.

템플릿 사양을 사용하면 정식 템플릿을 만들고 조직 내 팀과 이를 공유할 수 있습니다. 템플릿 사양은 배포를 위해 Azure Resource Manager에 제공되지만 올바른 권한이 없는 사용자가 액세스할 수 없기 때문에 안전합니다. 사용자가 템플릿을 배포하기 위해서는 템플릿 사양에 대해 읽기 액세스 권한만 필요하므로, 다른 사람에게 수정 권한 없이 템플릿을 공유할 수 있습니다.

GitHub 리포지토리 또는 스토리지 계정에 현재 템플릿이 있으면 템플릿을 공유하거나 사용하려고 할 때 여러 문제가 발생합니다. 템플릿을 배포하려면 템플릿을 공개적으로 액세스할 수 있게 하거나 SAS 토큰으로 액세스를 관리해야 합니다. 이러한 제한을 우회하기 위해서는 사용자가 결국 원래 템플릿으로부터 분기되는 로컬 복사본을 만들 수 있습니다. 템플릿 사양은 템플릿 공유를 단순화합니다.

조직 내 관리자는 템플릿 사양에 포함된 템플릿이 조직 요구 사항 및 지침을 따르는지 확인해야 합니다.

템플릿 사양 만들기

다음 예제에서는 Azure에서 스토리지 계정을 만들기 위한 간단한 Bicep 파일을 보여줍니다.

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

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

다음을 사용하여 템플릿 사양을 만듭니다.

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

Bicep 파일을 사용하여 템플릿 사양을 만들 수도 있습니다. 그러나 mainTemplate의 콘텐츠는 JSON 형식이어야 합니다. 다음 템플릿은 스토리지 계정을 배포하기 위한 템플릿 사양을 만듭니다.

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2023-04-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Bicep 파일에 포함된 JSON 템플릿은 다음과 같이 변경해야 합니다.

  • 줄 끝에 있는 쉼표를 제거합니다.
  • 큰따옴표를 작은따옴표로 바꿉니다.
  • 식 내에서 작은따옴표를 이스케이프합니다. 예를 들면 'name': '[parameters(\'storageAccountType\')]'입니다.
  • Bicep 파일에 정의된 매개 변수 및 변수에 액세스하기 위해 매개 변수 이름 및 변수 이름을 직접 사용할 수 있습니다. mainTemplate에 정의된 매개 변수 및 변수에 액세스하려면 여전히 ARM JSON 템플릿 구문을 사용해야 합니다. 예를 들면 'name': '[parameters(\'storageAccountType\')]'입니다.
  • Bicep 구문을 사용하여 Bicep 함수를 호출합니다. 예를 들면 'location': resourceGroup().location입니다.

템플릿 사양의 크기는 약 2MB로 제한됩니다. 템플릿 사양 크기가 제한을 초과하면 TemplateSpecTooLarge 오류 코드가 표시됩니다. 오류 메시지는 다음을 말합니다.

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

다음을 사용하여 구독에 있는 모든 템플릿 사양을 확인할 수 있습니다.

Get-AzTemplateSpec

해당 버전을 포함하여 템플릿 사양의 세부 정보를 확인할 수 있습니다.

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

템플릿 사양 배포

템플릿 사양을 만든 후에는 템플릿 사양 읽기 권한자 역할을 가진 사용자가 이를 배포할 수 있습니다. 또한 ARM 템플릿을 배포하기 위한 권한도 필요합니다. 배포 - CLI 또는 배포 - PowerShell을 참조하세요.

포털, PowerShell, Azure CLI 또는 더 큰 템플릿 배포에 있는 Bicep 모듈을 통해 템플릿 사양을 배포할 수 있습니다. 조직 내 사용자는 Azure의 모든 범위(리소스 그룹, 구독, 관리 그룹 또는 테넌트)에 템플릿 사양을 배포할 수 있습니다.

Bicep 파일의 경로 또는 URI를 전달하는 대신 해당 리소스 ID를 제공하여 템플릿 사양을 배포합니다. 리소스 ID의 형식은 다음과 같습니다.

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

리소스 ID에는 템플릿 사양의 버전 번호가 포함됩니다.

예를 들어 다음 명령으로 템플릿 사양을 배포합니다.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

실제로, 일반적으로 Get-AzTemplateSpec 또는 az ts show를 실행하여 배포하려는 템플릿 사양의 ID를 가져옵니다.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

또한 다음 형식으로 URL을 열어서 템플릿 사양을 배포할 수 있습니다.

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

매개 변수

템플릿 사양에 매개 변수를 전달하는 것은 Bicep 파일에 매개 변수를 전달하는 것과 유사합니다. 인라인으로 또는 매개 변수 파일에 매개 변수 값을 추가합니다.

인라인 매개 변수입니다.

매개 변수를 인라인으로 전달하려면 다음을 사용합니다.

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

매개 변수 파일

  • Bicep 매개 변수 파일 사용

    Bicep 매개 변수 파일을 만들려면 using 문을 지정해야 합니다. 예를 들어 다음과 같습니다.

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    자세한 내용은 Bicep 매개 변수 파일을 참조하세요.

    다음으로 매개 변수 파일을 전달하려면:

    현재 Azure PowerShell을 사용하여 .bicepparam 파일로 템플릿 사양을 배포할 수 없습니다.

  • JSON 매개 변수 파일 사용

    다음 JSON은 샘플 JSON 매개 변수 파일입니다.

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

    그리고 다음으로 매개 변수 파일을 전달합니다.

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

버전 관리

템플릿 사양을 만들 때는 이에 대한 버전 이름을 제공합니다. 템플릿 코드로 반복할 때 기존 버전(핫픽스용)을 업데이트하거나 새 버전을 게시할 수 있습니다. 버전은 텍스트 문자열입니다. 유의적 버전을 포함하여 특정 버전 관리 시스템을 따르도록 선택할 수 있습니다. 템플릿 사양의 사용자는 이를 배포할 때 사용할 버전 이름을 제공할 수 있습니다. 버전을 무제한으로 사용할 수 있습니다.

태그 사용

태그를 통해 리소스를 논리적으로 구성할 수 있습니다. Azure PowerShell 및 Azure CLI를 사용하여 태그를 템플릿 사양에 추가할 수 있습니다. 다음 예제에서는 템플릿 사양을 만들 때 태그를 지정하는 방법을 보여 줍니다.

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

다음 예제에서는 기존 템플릿 사양을 업데이트할 때 태그를 적용하는 방법을 보여 줍니다.

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

템플릿과 해당 버전 모두에는 태그가 있을 수 있습니다. 태그는 지정한 매개 변수에 따라 적용되거나 상속됩니다.

템플릿 사양 버전 버전 매개 변수 태그 매개 변수 태그 값
Exists 해당 없음 지정되지 않음 지정됨 템플릿 사양에 적용됨
Exists 새로 만들기 지정됨 지정되지 않음 템플릿 사양에서 버전으로 상속됨
새로 만들기 새로 만들기 지정됨 지정됨 템플릿 사양 및 버전 모두에 적용됨
Exists 새로 만들기 지정됨 지정됨 버전에 적용됨
Exists Exists 지정됨 지정됨 버전에 적용됨

템플릿 사양을 생성한 후 Bicep 모듈에서 해당 템플릿 사양에 연결할 수 있습니다. 템플릿 사양은 해당 모듈이 포함된 Bicep 파일을 배포할 때 배포됩니다. 자세한 내용은 템플릿 사양의 파일을 참조하세요.

모듈 연결을 위한 템플릿 사양에 대한 별칭을 만들려면 모듈에 대한 별칭을 참조하세요.

다음 단계

템플릿 사양 및 실습 지침에 대한 자세한 내용은 템플릿 사양을 사용하여 다시 사용할 수 있는 인프라 코드 라이브러리 게시를 참조하세요.