Bicep 파일의 구조 계획

• 7분

Bicep을 사용하면 코드를 구성하는 방법을 유연하게 결정할 수 있습니다. 이 단원에서는 Bicep 코드를 구조화할 수 있는 방법과 일관된 스타일과 명확하고 이해할 수 있는 Bicep 코드의 중요성에 대해 알아봅니다.

Bicep 코드는 어떤 순서를 따라야 합니까?

Bicep 템플릿에는 매개 변수, 변수, 리소스, 모듈, 출력 및 전체 템플릿에 대한 targetScope를 비롯한 많은 요소가 포함될 수 있습니다. Bicep은 요소가 따라야 하는 순서를 적용하지 않습니다. 그러나 템플릿이 명확하고 이해할 수 있도록 요소의 순서를 고려하는 것이 중요합니다.

코드를 정렬하는 방법에는 다음 두 가지가 있습니다.

• 요소 형식별로 요소 그룹화
• 리소스별로 요소 그룹화

팀은 이러한 방식을 합의하고 일관되게 사용해야 합니다.

요소 형식별로 요소 그룹화

동일한 형식의 모든 요소를 함께 그룹화할 수 있습니다. 모든 매개 변수는 하나의 위치, 일반적으로 파일 맨 위에 배치됩니다. 변수가 다음에 오고, 그 다음에 리소스와 모듈이 오고, 출력이 맨 아래에 옵니다. 예를 들어 Azure SQL 데이터베이스 및 스토리지 계정을 배포하는 Bicep 파일이 있을 수 있습니다.

형식별로 요소를 그룹화하면 다음과 같은 결과가 표시될 수 있습니다.

이 순서는 다른 인프라를 코드 언어로 익숙하게 사용하는 경우(예: Azure Resource Manager 템플릿의 언어)에 적합합니다. 또한 특정 형식의 요소를 찾을 위치가 명확해지므로 템플릿을 쉽게 이해할 수 있습니다. 그러나 좀 더 긴 템플릿에서는 요소 간에 탐색하고 이동하는 것이 어려울 수 있습니다.

이러한 범주 내에서 요소를 정렬하는 방법을 결정해야 합니다. 관련 매개 변수를 함께 그룹화하는 것이 좋습니다. 예를 들어 스토리지 계정에 대한 모든 매개 변수는 함께 속하며, 그 안에서 스토리지 계정의 SKU 매개 변수가 함께 속합니다.

마찬가지로 관련 리소스를 함께 그룹화할 수 있습니다. 이렇게 하면 템플릿을 사용하는 모든 사용자가 템플릿을 빠르게 탐색하고 템플릿의 중요한 부분을 이해할 수 있습니다.

경우에 따라 여러 보조 지원 리소스를 사용하여 기본 리소스를 배포하는 템플릿을 만듭니다. 예를 들어, Azure App Service에서 호스트되는 웹 사이트를 배포하는 템플릿을 만들 수 있습니다. 기본 리소스는 App Service 앱입니다. 동일한 템플릿의 보조 리소스에는 App Service 요금제, 스토리지 계정, Application Insights 인스턴스 등이 포함될 수 있습니다. 이와 같은 템플릿이 있는 경우 템플릿을 여는 모든 사용자가 템플릿의 용도를 빠르게 식별하고 중요한 리소스를 찾을 수 있도록 기본 리소스를 템플릿의 리소스 섹션 맨 위에 배치하는 것이 좋습니다.

리소스별로 요소 그룹화

혹은 배포하는 리소스의 형식에 따라 요소를 그룹화할 수 있습니다. 앞의 예제를 계속 진행하여 Azure SQL 데이터베이스 리소스와 관련된 모든 매개 변수, 변수, 리소스 및 출력을 그룹화할 수 있습니다. 그런 후 다음과 같이 스토리지 계정에 대한 매개 변수, 변수, 리소스 및 출력을 추가할 수 있습니다.

리소스별로 그룹화하면 특정 리소스에 필요한 모든 요소가 한 위치에 있게 되므로 템플릿을 더 쉽게 읽을 수 있습니다. 그러나 예를 들어 모든 매개 변수를 검토하려는 경우라면 특정 요소 형식이 선언되는 방법을 빠르게 확인하기가 더 어렵습니다.

또한 구성 맵을 사용할 때 environmentType 매개 변수와 같이 여러 리소스에 공통되는 매개 변수 및 변수를 처리하는 방법도 고려해야 합니다. 일반적인 매개 변수와 변수는 일반적으로 Bicep 파일의 맨 위에 함께 배치해야 합니다.

공백은 구조를 만드는 데 어떻게 도움이 될까요?

빈 줄 또는 공백을 사용하면 시각적 구조를 템플릿에 추가하는 데 도움이 될 수 있습니다. 공백을 신중하게 사용하면 Bicep 코드의 섹션을 논리적으로 그룹화할 수 있으며, 이를 통해 리소스 간 관계를 명확하게 파악할 수 있습니다. 이렇게 하려면 원하는 그룹화 스타일에 관계없이 주 섹션 사이에 빈 줄을 추가하는 것이 좋습니다.

몇 가지 유사한 리소스를 정의하려면 어떻게 해야 할까요?

Bicep을 사용하면 루프를 사용하여 단일 정의에서 유사한 리소스를 배포할 수 있습니다. for 키워드를 사용하여 리소스 루프를 정의하면 Bicep 코드를 더 명확하게 만들 수 있으며 리소스 정의가 불필요하게 중복되는 경우를 줄일 수 있습니다. 나중에 리소스 정의를 변경해야 하는 경우 한 곳에서만 업데이트하면 됩니다. 기본적으로 Azure Resource Manager에서 리소스를 배포할 때 루프의 모든 리소스가 동시에 배포되므로 배포가 최대한 효율적이 됩니다.

동일하거나 속성만 약간 다른 여러 리소스를 정의한 위치를 찾습니다. 그런 다음, 다른 리소스와는 다른 속성과 함께, 만들 리소스를 나열하는 변수를 추가합니다. 다음 예제에서는 루프를 사용하여 각각 고유한 이름과 파티션 키가 있는 Azure Cosmos DB 컨테이너 세트를 정의합니다.

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

특정 환경에만 리소스를 배포하려면 어떻게 해야 할까요?

경우에 따라 특정 환경 또는 특정 조건에서만 배포해야 하는 리소스를 정의합니다. if 키워드를 사용하면 매개 변수 값, 구성 맵 변수 또는 다른 조건에 따라 리소스를 선택적으로 배포할 수 있습니다. 다음 예제에서는 구성 맵을 사용하여 테스트 환경이 아닌 프로덕션 환경에 대한 로깅 리소스를 배포합니다.

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

리소스 간의 종속성을 표현하려면 어떻게 해야 할까요?

복잡한 Bicep 템플릿에서는 리소스 간의 종속성을 표현해야 합니다. Bicep은 리소스 간 종속성을 이해하면 올바른 순서로 배포합니다.

Bicep을 사용하면 dependsOn 속성을 사용하여 종속성을 명시적으로 지정할 수 있습니다. 그러나 대부분의 경우 Bicep이 자동으로 종속성을 감지하도록 할 수 있습니다. 다른 리소스의 속성 내에서 한 리소스의 심볼 이름을 사용하면 Bicep에서 관계를 감지합니다. 가능하다면 Bicep이 자체적으로 관리하도록 하는 것이 더 좋습니다. 이렇게 하면 템플릿을 변경할 때 Bicep은 종속성이 항상 올바른지 확인하므로, 사용자가 불필요한 코드를 추가하여 템플릿을 더 복잡하고 읽기 어렵게 만드는 경우를 피할 수 있습니다.

부모-자식 관계를 표현하려면 어떻게 해야 할까요?

Azure Resource Manager 및 Bicep에는 자식 리소스라는 개념이 있습니다. 이 개념은 부모의 컨텍스트 내에서 배포된 경우에만 의미가 있습니다. 예를 들어, Azure SQL 데이터베이스는 SQL 서버 인스턴스의 자식입니다. 자식 리소스를 정의하는 방법에는 여러 가지가 있지만 대부분의 경우 parent 속성을 사용하는 것이 좋습니다. 이를 통해 Bicep은 관계를 이해하여 Visual Studio Code에서 유효성 검사를 제공할 수 있으며, 템플릿을 읽는 다른 모든 사용자에게도 관계를 명확하게 알 수 있습니다.

리소스 속성을 설정하려면 어떻게 해야 할까요?

Bicep 파일에서 리소스 속성의 값을 지정해야 합니다. 리소스 정의에 값을 하드 코딩하는 경우 신중하게 하는 것이 좋습니다. 값이 변경되지 않을 것이라는 사실을 알고 있는 경우 다른 매개 변수를 사용하여 템플릿의 테스트 및 사용을 어렵게 만드는 것보다 하드 코딩하는 것이 더 좋을 수 있습니다. 그러나 값이 변경될 수 있다면 매개 변수나 변수로 정의하여 Bicep 코드를 보다 동적으로 재사용할 수 있게 하는 것이 좋습니다.

값을 하드 코딩하는 경우 다른 사람이 이해할 수 있는지 확인하는 것이 좋습니다. 예를 들어 리소스가 솔루션에 대해 올바르게 동작하기 위해 속성을 특정 값으로 설정해야 하는 경우 설명을 제공하는 잘 명명된 변수를 만든 다음, 해당 변수를 사용하여 값을 할당하는 것이 좋습니다. 변수 이름만으로 전체 스토리를 알 수 없는 경우 주석을 추가하는 것이 좋습니다. 이 모듈의 뒷부분에서 주석에 대해 좀 더 자세히 알아봅니다.

일부 리소스 속성의 경우 값을 자동으로 생성하려면 함수 및 문자열 보간을 포함하는 복잡한 식을 만들어야 합니다. Bicep 코드는 일반적으로 변수를 선언하고 리소스 코드 블록에서 참조할 때 더 명확해집니다.

output hostname string = '${app.name}.azurewebsites.net'

output hostname string = app.properties.defaultHostname

버전 제어를 효과적으로 사용하려면 어떻게 해야 할까요?

Git과 같은 버전 제어 시스템은 코드를 리팩터링할 때 작업을 간소화하는 데 도움이 될 수 있습니다.

버전 제어 시스템은 파일의 변경 내용을 추적하도록 설계되어 있으므로 실수한 경우 이러한 시스템을 사용하여 이전 버전의 코드로 쉽게 되돌릴 수 있습니다. 필요한 정확한 시점으로 돌아갈 수 있도록 작업을 자주 커밋하는 것이 좋습니다.

버전 제어를 사용하면 Bicep 파일에서 이전 코드를 제거할 수도 있습니다. Bicep 코드에 더 이상 필요하지 않은 리소스 정의가 포함되어 있으면 어떻게 해야 할까요? 나중에 정의가 다시 필요할 수 있으며, 주석 처리한 후 파일에 보관하는 것도 좋습니다. 그러나 실제로는 정의를 보관하면 Bicep 파일을 복잡하게만 만들며, 다른 사람들이 주석 처리된 리소스가 여전히 포함되어 있는 이유를 이해하기가 어려워집니다.

또 다른 고려 사항은 누군가가 실수로 주석 처리된 정의를 해제할 수 있으며 이로 인해 예측할 수 없거나 잠재적으로 부정적인 결과를 초래할 수 있다는 것입니다. 버전 제어 시스템을 사용하는 경우 이전 리소스 정의를 간단히 제거할 수 있습니다. 나중에 정의가 다시 필요한 경우 파일 기록에서 검색할 수 있습니다.