매개 변수 이해

• 8분

매개 변수를 사용하면 배포 시 Bicep 템플릿에 정보를 제공할 수 있습니다. 템플릿 내에서 매개 변수를 선언하면 Bicep 템플릿이 유연해지고 재사용할 수 있게 됩니다.

데코레이터는 매개 변수에 제약 조건과 메타데이터를 연결하는 방법을 제공하기 때문에 템플릿을 사용하는 모든 사용자가 제공해야 하는 정보를 쉽게 파악할 수 있습니다.

이 단원에서는 매개 변수와 데코레이터에 대해 알아봅니다.

매개 변수 선언

Bicep 템플릿에서 param 키워드를 사용하여 매개 변수를 선언합니다. 이러한 선언을 템플릿 파일 어디에나 배치할 수 있습니다. 단, 파일의 맨 위에 배치하여 Bicep 코드를 쉽게 읽을 수 있도록 하는 것이 좋습니다.

매개 변수를 선언하는 방법은 다음과 같습니다.

param environmentName string

각 부분이 어떻게 작동하는지 살펴보겠습니다.

• param은 매개 변수를 선언할 Bicep에 표시됩니다.

• environmentName은 매개 변수의 이름을 의미합니다. 매개 변수 이름은 어느 것이든 가능하지만 템플릿 사용자가 이해할 수 있도록 명확한 이름을 사용해야 합니다. 동일한 템플릿 내에서 해당 이름을 사용하여 매개 변수를 참조할 수도 있습니다. 매개 변수 이름은 고유해야 합니다. 동일한 Bicep 파일에 있는 변수 또는 리소스와 이름이 같으면 안 됩니다.

  팁

  매개 변수 선언에 대한 모범 사례 명명 규칙을 사용합니다. 적절한 명명 규칙을 사용하면 템플릿을 읽고 이해하기 쉽게 만들 수 있습니다. 명확하고 설명이 포함된 이름을 사용하고 일관된 명명 전략을 채택해야 합니다.

• string은 매개 변수의 형식을 의미합니다.

  팁

  템플릿에서 사용하는 매개 변수에 대해 신중하게 생각합니다. 배포 사이에 변경되는 설정에 매개 변수를 사용해 봅니다. 배포 사이에 변경되지 않는 설정에는 변수와 하드 코드된 값을 사용할 수 있습니다.

기본값 추가

템플릿의 매개 변수에 기본값을 할당할 수 있습니다. 기본값을 할당하면 매개 변수를 선택 항목으로 설정할 수 있게 됩니다. 매개 변수에 지정된 값 없이 템플릿이 배포되는 경우에는 기본값이 할당됩니다.

기본값을 추가하는 방법은 다음과 같습니다.

param environmentName string = 'dev'

매개 변수 environmentName에는 dev의 기본값이 할당됩니다.

기본값으로 언어 식을 사용할 수 있습니다. 다음은 기본값이 현재 리소스 그룹의 위치로 설정되어 있고 이름이 location인 문자열 매개 변수의 예입니다.

param location string = resourceGroup().location

매개 변수 형식 이해

매개 변수를 선언할 때 매개 변수에 포함될 정보 형식을 Bicep에 알려야 합니다. Bicep은 매개 변수에 할당된 값이 매개 변수 형식과 호환되는지 확인합니다.

Bicep의 매개 변수는 다음 형식 중 하나일 수 있습니다.

• string - 임의 텍스트를 입력할 수 있습니다.
• int - 숫자를 입력할 수 있습니다.
• bool- 부울(true 또는 false) 값을 나타냅니다.
• object 및 array - 정형 데이터 및 목록을 나타냅니다.

개체

개체 매개 변수를 사용하여 정형 데이터를 한 곳에 함께 결합할 수 있습니다. 개체에는 다양한 형식의 속성이 여러 개 있을 수 있습니다. Bicep 파일의 리소스 정의, 변수 또는 식 내에서 개체를 사용할 수 있습니다. 다음은 개체의 예입니다.

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

이 매개 변수는 두 개의 문자열 속성(name, tier) 및 정수 속성(capacity)이 있는 개체입니다. 각 속성은 해당 줄에 있습니다.

템플릿에서 매개 변수를 참조할 때 다음 예제처럼 점 뒤에 속성 이름을 사용하여 개체의 개별 속성을 선택할 수 있습니다.

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

개체 매개 변수를 사용할 수 있는 또 다른 예는 리소스 태그를 지정하는 경우입니다. 배포하는 리소스에 사용자 지정 태그 메타데이터를 연결할 수 있으며, 이 메타데이터를 사용하여 리소스에 대한 중요한 정보를 식별할 수 있습니다.

태그는 리소스를 소유하는 팀을 추적하거나 리소스가 프로덕션 또는 비프로덕션 환경에 속하는 경우와 같은 시나리오에 유용합니다. 일반적으로 각 환경마다 서로 다른 태그를 사용하지만 템플릿 내의 모든 리소스에서 동일한 태그 값을 다시 사용해야 합니다. 따라서 리소스 태그는 다음 예제와 같은 개체 매개 변수에 적합합니다.

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Bicep 파일에서 리소스를 정의할 때마다 tags 속성을 정의할 때 다시 사용할 수 있습니다.

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

배열

배열은 항목 목록입니다. 예를 들어, 문자열 값 배열을 사용하여 Azure Monitor 작업 그룹에 대한 이메일 주소 목록을 선언할 수 있습니다. 또는 개체 배열을 사용하여 가상 네트워크의 서브넷 목록을 나타낼 수 있습니다.

예제를 살펴보겠습니다. Azure Cosmos DB를 사용하여 여러 지역에 걸쳐 있는 데이터베이스 계정을 만들 수 있으며, Azure Cosmos DB는 데이터 복제를 자동으로 처리합니다. 새 데이터베이스 계정을 배포할 때 계정을 배포할 Azure 지역 목록을 지정해야 합니다. 환경에 따라 다른 위치 목록이 있어야 하는 경우가 많습니다. 예를 들어, 테스트 환경에서 비용을 절감하기 위해 하나 또는 두 개의 위치만 사용할 수 있습니다. 그러나 프로덕션 환경에서는 여러 위치를 사용할 수 있습니다.

위치 목록을 지정하는 배열 매개 변수를 만들 수 있습니다.

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Azure Cosmos DB 리소스를 선언하면 배열 매개 변수를 참조할 수 있습니다.

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

그러면 매개 변수 값을 변경하여 개발 환경에 다른 매개 변수 값을 쉽게 사용할 수 있습니다. 이제 원래 템플릿을 수정하지 않고 다른 매개 변수 값을 제공하는 방법을 알아보겠습니다.

허용된 값 목록 지정

경우에 따라 매개 변수에 특정 값이 있는지 확인해야 합니다. 예를 들어, 팀에서 Premium v3 S SKU를 사용하여 프로덕션 App Service 요금제를 배포해야 한다고 결정할 수 있습니다. 이 규칙을 적용하려면 @allowed 매개 변수 데코레이터를 사용합니다. 매개 변수 데코레이터는 매개 변수의 값이 무엇이어야 하는지에 대한 정보를 Bicep에 제공하는 방법입니다. 다음은 몇 개의 특정 값만 할당할 수 있도록 appServicePlanSkuName이라는 문자열 매개 변수를 제한하는 방법입니다.

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

매개 변수 길이 및 값 제한

문자열 매개 변수를 사용하는 경우 문자열의 길이를 제한해야 하는 경우가 많습니다. Azure 리소스 이름 지정의 예를 살펴보겠습니다. 모든 Azure 리소스 종류는 이름의 길이에 제한이 있습니다. 나중에 배포할 때 오류가 생기지 않도록 이름 지정을 제어하는 매개 변수의 최소 및 최대 문자 길이를 지정하는 것이 좋습니다. @minLength 및 @maxLength 데코레이터를 매개 변수에 허용하려는 최소 및 최대 문자 길이에 사용할 수 있습니다.

다음은 이름이 storageAccountName인 문자열 매개 변수를 선언하는 예입니다. 이 경우는 길이가 5~24자만 가능합니다.

@minLength(5)
@maxLength(24)
param storageAccountName string

이 매개 변수에는 두 개의 데코레이터가 포함됩니다. 각 데코레이터를 해당 줄에 배치하여 매개 변수에 여러 데코레이터를 적용할 수 있습니다.

숫자 매개 변수를 사용할 때는 값이 특정 범위에 들어야 할 수 있습니다. 예를 들어, 장난감 회사는 누구나 App Service 요금제를 배포할 때마다 항상 하나 이상의 인스턴스를 배포해야 하지만 요금제의 인스턴스를 10개 이하로 배포해야 한다고 결정할 수 있습니다. 요구 사항을 충족하기 위해 @minValue 및 @maxValue 데코레이터를 사용하여 허용되는 최솟값과 최댓값을 지정할 수 있습니다. 다음 예제에서는 정수 매개 변수 appServicePlanInstanceCount를 선언합니다. 해당 값은 1~10(포함)일 수 있습니다.

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

매개 변수에 설명 추가

매개 변수는 다른 사용자도 템플릿을 다시 사용할 수 있게 해주는 좋은 방법입니다. 다른 사용자가 템플릿을 사용할 때 각 매개 변수가 하는 일을 이해해야 올바른 값을 제공할 수 있습니다. Bicep은 사람이 읽을 수 있는 방식으로 매개 변수의 용도를 문서화할 수 있도록 @description 데코레이터를 제공합니다.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

매개 변수에 대한 설명을 제공하는 것이 좋습니다. 설명을 유용하게 만들고 템플릿에 필요한 매개 변수 값에 대한 중요한 정보를 제공해봅니다.