주석 및 리소스 메타데이터를 추가하여 코드 문서화

  • 4분

좋은 Bicep 코드는 자체 문서화합니다. 이것은 동료가 코드를 읽으면서 코드를 통해 발생하는 결과를 신속하게 이해할 수 있도록 명확하게 이름을 지정하고 적절한 구조를 사용하는 것을 의미합니다. 변경이 필요한 경우 올바른 부분을 수정하고 있다고 확신할 수 있습니다.

그러나 일부 상황에서는 Bicep 파일에 추가 문서를 추가하여 특정 코드를 명확하게 나타내야 할 수 있습니다. 또한 템플릿을 배포하고 Azure에서 리소스를 만든 후에는 Azure 환경을 보는 모든 사람이 각 리소스가 무엇이며 어떤 용도로 사용되는지를 이해하는 것이 중요합니다.

이 단원에서는 Bicep 파일에 주석을 추가하는 방법과 리소스 태그를 사용하여 Azure 리소스에 메타데이터를 추가하는 방법을 알아봅니다. 이 추가 설명서는 코드가 수행하는 작업, 코드를 작성하는 데 사용한 논리 및 Azure 리소스의 용도에 대한 인사이트를 동료에게 제공합니다.

코드에 주석 추가

Bicep을 사용하면 코드에 메모를 추가할 수 있습니다. 주석은 코드를 문서화하는 사람이 읽을 수 있는 텍스트이지만 파일이 Azure에 배포될 때는 무시됩니다.

Bicep은 다음 두 가지 유형의 주석을 지원합니다.

  • 한 줄 주석은 다음과 같이 이중 슬래시(//) 문자 시퀀스로 시작하고 줄의 끝까지 계속됩니다.

    // We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

  • 여러 줄 주석은 /* 및 */ 문자 시퀀스를 사용하여 주석을 묶고 다음과 같이 여러 줄에 걸쳐 있을 수 있습니다.

    /*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

팁

코드의 명확하고 분명한 부분에는 주석을 사용하지 마세요. 주석이 너무 많으면 코드의 가독성이 줄어듭니다. 또한 나중에 코드가 변경될 때 주석을 업데이트하는 것을 잊어버리기 쉽습니다. 고유한 논리 및 복잡한 식을 문서화하는 데 집중합니다.

Bicep 주석을 사용하여 각 파일의 시작 부분에 구조화된 여러 줄 블록을 추가할 수도 있습니다. 매니페스트라고 생각하면 됩니다. 팀에서 각 템플릿 및 모듈에 템플릿의 용도 및 포함된 내용을 설명하는 매니페스트를 포함해야 한다고 결정할 수 있습니다. 예를 들면 다음과 같습니다.

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

매개 변수 파일에 주석 추가

매개 변수 파일을 사용하면 배포에 대한 매개 변수 값 집합을 지정하는 JSON 파일을 만들 수 있습니다. 매개 변수 값은 Bicep 템플릿에서 선언된 매개 변수와 일치해야 합니다.

매개 변수 파일에서 지정하는 값은 문서화되는 경우에도 유용합니다. 파일을 읽는 사람에게 즉시 표시되지 않을 수 있는 매개 변수 값을 사용하는 경우에는 매개 변수 파일에 주석을 추가하는 것이 좋습니다.

예를 들어 웹 사이트의 Bicep 템플릿에는 회사의 제품 재고 API에 액세스하기 위한 URL에 대한 매개 변수가 포함될 수 있습니다. 따라서 웹 사이트에서는 창고에 장난감 재고가 있는지 여부를 표시할 수 있습니다. 각 환경에 대한 재고 API에 액세스하기 위한 URL은 이해하기 쉽지 않기 때문에 다음과 같이 주석으로 사용하는 것이 좋습니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

팁

주석을 포함하는 매개 변수 파일 및 다른 JSON 파일을 사용하는 경우 일반적으로 .json 대신 .jsonc 파일 확장명을 사용해야 합니다. 이렇게 하면 주석이 허용된다는 사실을 Visual Studio Code 및 기타 도구가 이해하는 데 도움이 됩니다.

매개 변수, 변수 및 출력에 대한 설명 추가

매개 변수, 변수 또는 출력을 만들 때 @description() 데코레이터를 적용하여 용도를 설명할 수 있습니다.

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

Bicep에 Visual Studio Code 확장을 사용하는 경우 심볼 이름을 가리킬 때마다 설명이 표시되므로 설명은 주석보다 더 강력합니다. 또한 모듈로서 Bicep 파일을 사용하는 경우 매개 변수에 적용된 설명이 표시됩니다.

리소스에 설명 추가

또한 정의하는 리소스에 대한 설명을 추가하는 것이 유용할 수 있습니다. @description() 데코레이터를 리소스에도 적용할 수 있습니다.

일부 리소스는 설명 또는 사람이 읽을 수 있는 기타 정보를 리소스 자체에 추가할 수 있도록 지원합니다. 예를 들어, 많은 Azure Policy 리소스 및 Azure RBAC(역할 기반 액세스 제어) 역할 할당에는 다음과 같은 설명 속성이 포함되어 있습니다.

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

이 속성을 사용하여 각 역할 할당을 만든 이유를 설명하는 것이 좋습니다. 이 설명은 리소스를 사용하여 Azure에 배포되므로 Azure 환경의 RBAC 구성을 감사하는 사람은 누구나 역할 할당의 용도를 즉시 파악할 수 있습니다.

리소스 태그 적용

Bicep 파일의 주석은 배포된 리소스에는 나타나지 않습니다. Bicep 파일을 문서화하는 데에만 도움이 됩니다. 그러나 다음을 비롯하여 배포된 Azure 리소스에 대한 정보를 추적해야 하는 경우가 많습니다.

  • 특정 비용 센터에 Azure 비용 할당
  • 데이터베이스 및 스토리지 계정에 포함된 데이터를 분류하고 보호하는 방법 이해
  • 리소스 관리를 담당하는 팀 또는 사람의 이름 기록
  • 프로덕션 또는 개발과 같이 리소스가 관련된 환경의 이름 추적

리소스 태그를 사용하면 리소스에 대한 중요한 메타데이터를 저장할 수 있습니다. Bicep 코드에서 리소스 태그를 정의하면 Azure에서는 배포 시 리소스와 함께 해당 정보를 저장합니다.

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Azure PowerShell 및 Azure CLI와 같은 도구를 사용하여 리소스 태그를 쿼리하면 Azure Portal에서 태그를 볼 수 있습니다.

태그의 위치를 보여 주는 스토리지 계정에 대한 Azure Portal의 스크린샷

모든 리소스에 대해 동일한 태그 세트를 사용하는 것이 일반적이므로 태그를 매개 변수 또는 변수로 정의한 다음, 각 리소스에서 다시 사용하는 것이 좋습니다.

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  tags: tags
}