모듈에 매개 변수 및 출력 추가

7분

사용자가 만드는 각 모듈은 명확한 용도가 있어야 합니다. 모듈이 계약을 가지고 있다고 생각하면 됩니다. 매개 변수 집합을 수락하고 리소스 집합을 만들며 일부 출력을 부모 템플릿에 다시 제공할 수 있습니다. 모듈을 사용할 때는 작동 방식을 걱정할 필요가 없으며, 모듈은 기대하는 대로 작동할 것입니다.

모듈을 계획할 때 다음 사항을 고려하십시오.

모듈의 용도를 충족하기 위해 알아야 할 사항
모듈 사용자가 제공해야 하는 것
모듈 사용자가 출력으로 액세스할 수 있을 것으로 예상해야 하는 것

모듈 매개 변수

모듈에서 허용하는 매개 변수와 각 매개 변수의 선택 또는 필수 사항 여부

템플릿에 대한 매개변수를 만들 때 가능한 경우 기본 매개 변수를 추가하는 것이 좋습니다. 모듈에서는 고유 기본 매개 변수를 사용할 수 있는 부모 템플릿에서 모듈을 사용하기 때문에 기본 매개 변수를 추가하는 것이 항상 중요한 것은 아닙니다. 기본값이 있는 두 파일 모두에 유사한 매개 변수가 있다면 템플릿 사용자가 적용할 기본값을 파악하고 일관성을 적용하기 어려울 수 있습니다. 부모 템플릿의 기본값을 그대로 유지하고 모듈에서는 제거하는 것이 좋습니다.

또한 리소스에 대한 SKU 및 기타 중요한 구성 설정을 제어하는 매개 변수를 관리 방법을 고려해야 합니다. 독립 실행형 Bicep 템플릿을 만들 때 템플릿에 비즈니스 규칙을 포함하는 것이 일반적입니다. 예: 프로덕션 환경을 배포할 때 스토리지 계정은 GRS 계층을 사용해야 합니다. 그러나 모듈은 때때로 다른 문제를 제시합니다.

재사용 가능하고 유연해야 하는 모듈을 빌드하는 경우 각 부모 템플릿에 대한 비즈니스 규칙이 다를 수 있으므로 비즈니스 규칙을 제네릭 모듈에 포함하는 것은 별로 의미가 없을 수 있습니다. 부모 템플릿에서 비즈니스 규칙을 정의한 다음 매개 변수를 통해 모듈 구성을 명시적으로 전달하는 것이 좋습니다.

그러나 고유한 조직에서 특정 요구 사항에 맞는 리소스를 쉽게 배포할 수 있도록 하는 모듈을 만드는 경우에는 부모 템플릿을 단순화하는 비즈니스 규칙을 포함하는 것이 좋습니다.

모듈에 포함하는 매개변수에는 @description 특성을 사용하여 유의미한 설명을 추가해야 합니다.

@description('The name of the storage account to deploy.')
param storageAccountName string

조건 사용

Bicep과 같은 코드를 사용하여 인프라를 배포하는 목표 중 하나는 중복 작업을 피하거나 동일하거나 매우 유사한 용도로 여러 템플릿을 만드는 것을 방지하는 것입니다. Bicep의 기능은 다양한 상황에서 맞게 재사용 가능한 모듈을 생성할 수 있는 강력한 도구 상자를 제공합니다. 모듈, 식, 기본 매개 변수 값 및 조건과 같은 기능을 결합하여 필요한 유연성을 제공하는 재사용 가능한 코드를 빌드할 수 있습니다.

Azure Cosmos DB 계정을 배포하는 모듈을 만든다고 가정합니다. 프로덕션 환경에 배포되면 해당 로그를 Log Analytics 작업 영역으로 보내도록 계정을 구성해야 합니다. Log Analytics 전송할 로그를 구성하려면 diagnosticSettings 리소스를 정의합니다.

리소스 정의에 조건을 추가하여 요구 사항을 충족하고, 기본값을 추가하여 작업 영역 ID 매개 변수를 선택 사항으로 만들 수 있습니다.

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

이 모듈을 Bicep 템플릿에 포함하면 작업 영역 ID를 설정하여 Log Analytics에 Azure Cosmos DB 계정 로그를 보내도록 쉽게 구성할 수 있습니다. 또는 배포 중인 환경에 대한 로그가 필요하지 않은 경우 매개 변수를 생략하면 됩니다. 기본값이 있습니다. 모듈은 요구 사항에 적합한 작업을 수행하는 데 필요한 논리를 캡슐화합니다.

팁

if문이 true 또는 false로 계산되는 경우 두 시나리오 모두에 대해 템플릿이 유효한지 테스트해야 합니다.

모듈 출력

모듈은 출력을 정의할 수 있습니다. 부모 템플릿에서 사용할 정보에 대해 출력을 만드는 것이 좋습니다. 예를 들어 모듈이 스토리지 계정을 정의하는 경우 부모 템플릿에서 액세스할 수 있도록 스토리지 계정 이름에 대한 출력을 만드는 것이 좋습니다.

경고

비밀 값으로 출력을 사용하지 마세요. 출력은 배포 기록의 일부로 로그되므로 보안 값으로 적합하지 않습니다. 그 대신 다음 옵션 중 하나를 고려할 수 있습니다.

출력을 사용하여 리소스 이름을 제공합니다. 그러면 부모 템플릿에서 해당 이름으로 existing 리소스를 만들고 보안 값을 동적으로 조회할 수 있습니다.
Azure Key Vault 비밀에 값을 씁니다. 필요할 때 부모 템플릿이 볼트에서 비밀을 읽도록 합니다.

부모 템플릿은 변수의 모듈 출력을 사용하고 다른 리소스 정의에 속성을 사용하거나 변수와 속성을 출력 자체로 표시할 수 있습니다. Bicep 파일 전체에 출력을 노출하고 사용하면 팀과 공유하고 여러 배포에서 다시 사용할 수 있는 재사용 가능한 Bicep 모듈 집합을 만들 수 있습니다. @description 특성을 사용하여 출력에 유의미한 설명을 추가하는 것도 좋은 방법입니다.

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

팁

또한 전용 서비스를 사용하여 Bicep 템플릿에서 생성하는 설정을 저장, 관리 및 액세스할 수 있습니다. Key Vault은 보안 값을 저장하도록 설계되었습니다. Azure App Configuration은 기타(비보안) 값을 저장하도록 설계되었습니다.

모듈을 서로 연결하기

여러 모듈을 함께 구성하는 부모 Bicep 파일을 만드는 것이 일반적입니다. 예를 들어 전용 가상 네트워크를 사용하는 가상 머신을 배포하는 새 Bicep 템플릿을 빌드한다고 가정합니다. 가상 네트워크를 정의하는 모듈을 만들 수 있습니다. 그런 다음 가상 네트워크의 서브넷 리소스 ID를 해당 모듈의 출력으로 가져와 가상 머신 모듈에 대한 입력으로 사용할 수 있습니다.

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

이 예제에서는 모듈 간의 참조에 기호 이름을 사용합니다. 이 참조는 Bicep이 모듈 간의 관계를 자동으로 이해할 수 있도록 합니다.

Bicep은 종속성이 있는 것을 알기 때문에 모듈을 시퀀스대로 배포합니다.

Bicep은 virtualNetwork 모듈의 모든 항목을 배포합니다.
해당 배포가 성공하면 Bicep은 subnetResourceId 출력값에 액세스하여 virtualMachine 모듈에 매개 변수로 전달합니다.
Bicep은 virtualMachine 모듈의 모든 항목을 배포합니다.

참고

모듈에 따르는 경우 Bicep은 전체 모듈 배포가 완료될 때까지 대기합니다. 모듈을 계획할 때 이 점을 기억하세요. 배포에 오랜 시간이 걸리는 리소스를 정의하는 모듈을 만드는 경우, 해당 모듈에 종속된 다른 모든 리소스는 전체 모듈의 배포가 완료될 때까지 대기합니다.

모듈에 매개 변수 및 출력 추가

모듈 매개 변수

조건 사용

모듈 출력

모듈을 서로 연결하기

피드백