Bicep 파일 리팩터링

• 5분

템플릿을 Bicep으로 변환하는 단계를 변환하고 마이그레이션한 후에는 파일을 개선해야 합니다. 이 프로세스를 리팩터링이라고 합니다. JSON ARM 템플릿 및 Azure 리소스를 Bicep으로 마이그레이션하기 위한 권장 워크플로의 세 번째 단계는 리팩터링 단계입니다.

리팩터링 단계는 Bicep 코드의 품질을 개선하는 데 중점을 둡니다. 개선 사항에는 템플릿 표준에 맞게 템플릿을 맞추도록 코드 주석 추가와 같은 변경 사항이 포함될 수 있습니다.

리팩터링 단계는 순서에 따라 수행할 수 있는 8단계로 구성됩니다.

• 리소스 API 버전을 검토합니다.
• 새 Bicep 파일의 Linter 제안 사항을 검토합니다.
• 매개 변수, 변수, 기호 이름을 수정합니다.
• 식을 단순화합니다.
• 자식 및 확장 리소스를 검토합니다.
• 모듈화합니다.
• 설명을 추가합니다.
• Bicep 모범 사례를 준수합니다.

다음 예제에서는 App Service 요금제를 만드는 JSON 템플릿의 Bicep decompile 명령 출력을 보여 줍니다.

@description('Location for resources.')
param location string = resourceGroup().location

@allowed([
  'prod'
  'dev'
  'test'
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service Plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {
  name: appServicePlanName_var
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanInstanceCount
  }
  kind: 'app'
  properties: {}
}

output appServicePlanId string = appServicePlanName.id

이 Bicep 템플릿을 있는 그대로 배포하면 배포는 성공하지만 템플릿 표준에 맞도록 개선할 수 있는 여지가 있습니다.

리소스 API 버전 검토

Bicep을 사용하여 Azure 리소스와 상호 작용하는 경우 사용할 API 버전을 지정합니다. Azure 제품이 변경되고 개선됨에 따라 새로운 기능에 대한 액세스를 제공하는 최신 API 버전이 릴리스됩니다. Azure 리소스를 내보낼 때 내보낸 템플릿에는 리소스 종류에 대한 최신 API 버전이 없을 수도 있습니다. 향후 배포에 필요한 특정 속성이 있는 경우 API를 적절한 버전으로 업데이트합니다. 내보낸 각 리소스에 대한 API 버전을 검토하는 것이 좋습니다.

Azure ARM 템플릿 참조는 템플릿에 대한 적절한 API 버전 및 리소스 속성을 확인하는 데 도움이 될 수 있습니다.

새 Bicep 파일의 Linter 제안 사항 검토

Visual Studio Code용 Bicep 확장을 사용하여 Bicep 파일을 만들 때 linter는 자동으로 실행되고 코드의 오류를 강조 표시하고 제안을 제공합니다. 많은 제안 및 오류에는 문제에 대한 빠른 수정을 적용하는 옵션이 포함됩니다. 해당 권장 사항을 검토하고 Bicep 파일을 조정합니다.

매개 변수, 변수, 기호 이름 수정

인프라가 프로덕션 및 개발과 같은 여러 환경을 지원하는 경우 해당 환경을 지원하는 매개 변수를 만듭니다. 좋은 매개 변수 명명 규칙을 사용하면 환경별로 배포를 쉽게 사용자 지정할 수 있습니다.

디컴필러에서 생성된 매개 변수, 변수 및 기호 이름의 이름이 표준 명명 규칙과 일치하지 않을 수 있습니다. 생성된 이름을 검토하고 필요에 따라 조정합니다.

다음 예제에서는 명명 appServicePlanName_var 된 변수가 _var 원래 변수 이름의 끝에 추가되었습니다.

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service Plan instances.')
param appServicePlanInstanceCount int = 1

var appServicePlanName_var = 'plan-${environment}-001'

resource appServicePlanName 'Microsoft.Web/serverfarms@2020-12-01' = {

명확성을 위해 변수 이름에서 _var를 제거하는 것이 좋습니다. 그러나 변수 이름을 바꾸면 새 이름이 App Service 요금제 리소스의 기호 이름과 충돌합니다. 따라서 먼저 리소스의 이름을 바꾼 다음 해당 정의에 사용되는 변수의 이름을 바꾸는 것이 좋습니다.

식 단순화

디컴파일 프로세스가 항상 일부 Bicep 기능을 활용하는 것은 아닙니다. 변환에서 생성된 식을 검토하고 단순화합니다. 예를 들어 디컴파일된 템플릿에는 문자열 보간을 사용하여 단순화할 수 있는 concat() 또는 format() 함수가 포함될 수 있습니다. Linter의 제안 사항을 검토하고 필요에 따라 조정합니다.

자식 및 확장 리소스 검토

Bicep은 리소스 이름 연결, 속성 사용, 중첩 리소스 사용 parent 등 자식 및 확장 리소스를 선언하는 여러 가지 방법을 제공합니다.

디컴파일 후 해당 리소스를 검토하고 구조가 표준을 충족하는지 확인하는 것이 좋습니다. 예를 들어 문자열 연결을 사용하여 자식 리소스 이름을 만들지 마세요. 대신 parent 속성이나 중첩된 리소스를 사용해야 합니다. 마찬가지로 가상 네트워크의 속성으로 또는 별도의 리소스로 서브넷을 참조할 수 있습니다.

모듈화

리소스가 많은 템플릿을 변환하는 경우 단순성을 위해 개별 리소스 종류를 모듈로 나누는 것이 좋습니다. Bicep에서 모듈을 사용하면 템플릿 배포의 복잡성을 줄이는 데 도움이 됩니다.

설명 및 설명 추가

좋은 Bicep 코드는 자체 문서화합니다. Bicep에서 코드에 주석과 설명을 추가하여 인프라를 문서화할 수 있습니다. 주석과 설명은 팀원이 코드를 이해하고 변경 시 신뢰도를 높이는 데 도움이 될 수 있습니다. 모듈의 매개 변수 값을 지정해야 하는 경우와 같이 Visual Studio Code에서 Bicep 파일로 작업할 때 주석 및 설명이 표시됩니다. 그러나 Azure에 Bicep 파일을 배포하면 주석이 무시됩니다.

문자 시퀀스를 사용하여 // 단일 줄 주석 추가할 수 있습니다. 다중 줄 주석 경우 a로 시작하고 다음으로 /* 끝납니다*/. 코드의 특정 줄 또는 코드 섹션에 적용되는 주석을 추가할 수 있습니다.

파일 시작 부분에 여러 줄의 주석을 추가할 수 있습니다.

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

단일 줄 주석 코드 섹션 또는 개별 줄의 헤더로 추가하여 코드를 설명할 수 있습니다.

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.

Bicep은 매개 변수, 변수, 리소스, 모듈 및 출력의 용도를 문서화하는 데 사용할 수 있는 데코레이터를 제공합니다 @description . 설명하는 항목 위의 줄에 설명을 추가할 수 있습니다.

@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

Bicep 모범 사례를 준수

Bicep 파일이 표준 권장 사항을 준수해야 합니다. 놓쳤을 수도 있는 모든 사항을 대상으로 Bicep 모범 사례를 검토하세요.

변환된 템플릿

적절하게 개선한 후 배포하기 전에 최종 템플릿을 검토합니다. 업데이트된 템플릿에는 수정된 이름, API 버전, 설명 및 추가된 설명이 포함됩니다.

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

// Parameters
@description('Location for all resources.')
param location string = resourceGroup().location

@allowed([
  'prod' // Production environment
  'dev' // Development environment
  'test' // Test environment
])
@description('The list of allowed environment names.')
param environment string = 'prod'

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
@description('The list of allowed App Service plan SKUs.')
param appServicePlanSku string = 'P1v3'

@minValue(1)
@maxValue(10)
@description('The number of allowed App Service plan instances.')
param appServicePlanInstanceCount int = 1

// Variables
@description('The name of the App Service plan.')
var appServicePlanName = 'plan-${environment}-001'

// Resource - App Service plan
@description('The App Service plan resource name.')
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku // Specifies the SKU of the App Service plan.
    capacity: appServicePlanInstanceCount
  }
  kind: 'app' // Specifies a Windows App Service plan.
}

// Outputs
@description('The resource ID of the App Service plan.')
output appServicePlanId string = appServicePlan.id // Resource ID of the App Service plan.