Bicep에서 배포 스크립트 사용
deploymentScripts 리소스를 사용하여 Bicep 배포에서 스크립트를 실행하고 실행 결과를 검토할 수 있습니다. 이러한 스크립트를 사용하여 다음과 같은 사용자 지정 단계를 수행할 수 있습니다.
- 디렉터리에 사용자를 추가합니다.
- 데이터 평면 작업(예: Blob 복사 또는 데이터베이스 시드)을 수행합니다.
- 라이선스 키를 조회하고 유효성을 검사합니다.
- 자체 서명된 인증서를 만듭니다.
- Microsoft Entra ID에서 개체를 만듭니다.
- 사용자 지정 시스템에서 IP 주소 블록을 조회합니다.
배포 스크립트의 이점은 다음과 같습니다.
- 쉽게 코딩하고, 사용하고, 디버그할 수 있습니다. 원하는 개발 환경에서 배포 스크립트를 개발할 수 있습니다. 스크립트는 Bicep 또는 외부 스크립트 파일에 포함될 수 있습니다.
- 스크립트 언어 및 플랫폼을 지정할 수 있습니다. 현재 Linux 환경에서 Azure PowerShell 및 Azure CLI 배포 스크립트가 지원됩니다.
- 스크립트에 명령줄 인수를 전달할 수 있습니다.
- 스크립트 출력을 지정하고 이를 배포에 다시 전달할 수 있습니다.
배포 스크립트 리소스는 Azure Container Instance를 사용할 수 있는 지역에서만 사용할 수 있습니다. 자세한 내용은 Azure 지역의 Azure Container Instances에 대한 리소스 가용성을 참조하세요.
Warning
배포 스크립트 서비스를 사용하려면 스크립트를 실행하고 문제를 해결하기 위해 스토리지 계정과 컨테이너 인스턴스라는 두 가지 추가 리소스가 필요합니다. 일반적으로 서비스는 배포 스크립트가 완료된 후 이러한 리소스를 정리합니다. 이러한 리소스는 제거될 때까지 요금이 부과됩니다.
가격 책정 정보는 Container Instances 가격 책정 및 Azure Storage 가격 책정을 참조하세요. 자세한 내용은 배포 스크립트 리소스 정리를 참조하세요.
학습 리소스
단계별 지침을 통해 배포 스크립트에 대해 알아보려면 배포 스크립트를 사용하여 Bicep 및 ARM 템플릿 확장을 참조하세요.
최소 권한 구성
배포 스크립트 API 버전 2020-10-01 이상의 경우 배포 스크립트 실행과 관련된 두 가지 주체가 있습니다.
배포 주체: 이 보안 주체는 Bicep 파일을 배포하는 데 사용됩니다. 배포 스크립트 리소스를 실행하는 데 필요한 기본 리소스(스토리지 계정 및 Azure 컨테이너 인스턴스)를 만듭니다. 최소 권한 권한을 구성하려면 다음 속성이 있는 사용자 지정 역할을 배포 주체에 할당합니다.
{ "roleName": "deployment-script-minimum-privilege-for-deployment-principal", "description": "Configure least privilege for the deployment principal in deployment script", "type": "customRole", "IsCustom": true, "permissions": [ { "actions": [ "Microsoft.Storage/storageAccounts/*", "Microsoft.ContainerInstance/containerGroups/*", "Microsoft.Resources/deployments/*", "Microsoft.Resources/deploymentScripts/*" ], } ], "assignableScopes": [ "[subscription().id]" ] }Azure Storage 및 Azure Container Instances 리소스 공급자가 등록되지 않은 경우
Microsoft.Storage/register/action및Microsoft.ContainerInstance/register/action를 추가해야 합니다.배포 스크립트 주체: 이 주체는 배포 스크립트가 Azure에 인증하고 Azure CLI 또는 PowerShell을 호출해야 하는 경우에만 필요합니다. 배포 스크립트 주체를 지정하는 방법에는 두 가지가 있습니다.
identity속성에서 사용자 할당 관리 ID를 지정합니다. (배포 스크립트 리소스 구문을 참조하세요.) 사용자 할당 관리 ID를 지정하면 스크립트 서비스는 배포 스크립트를 호출하기 전에Connect-AzAccount -Identity를 호출합니다. 관리 ID에는 스크립트에서 작업을 완료하는 데 필요한 액세스 권한이 있어야 합니다. 현재는identity속성에 대해 사용자 할당 관리 ID만 지원됩니다. 다른 ID로 로그인하려면 이 목록의 두 번째 메서드를 사용합니다.- 서비스 주체 자격 증명을 보안 환경 변수로 전달한 다음 배포 스크립트에서 Connect-AzAccount 또는 az login을 호출할 수 있습니다.
관리 ID를 사용하는 경우 배포 주체에는 관리 ID 리소스에 할당된 기본 제공 관리 ID 운영자 역할이 필요합니다.
현재, 배포 스크립트 권한을 구성하기 위해 조율되는 기본 제공 역할은 없습니다.
배포 스크립트 만들기
다음 예제에서는 배포 스크립트 리소스가 있는 간단한 Bicep 파일을 보여 줍니다. 이 스크립트는 하나의 문자열 매개 변수를 사용하고 다른 문자열을 만듭니다.
param name string = 'John Dole'
param location string = resourceGroup().location
resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
name: 'inlineCLI'
location: location
kind: 'AzureCLI'
properties: {
azCliVersion: '2.52.0'
arguments: name
scriptContent: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
retentionInterval: 'PT1H'
}
}
output text string = deploymentScript.properties.outputs.text
배포 스크립트 리소스를 만드는 방법에 대한 자세한 내용은 배포 스크립트 만들기를 참조하세요. 배포 스크립트 리소스에 대한 스크립트를 만들기 위해 Azure 컨테이너 인스턴스 또는 Docker 이미지와 같은 전용 스크립트 개발 환경을 설정하는 것이 좋습니다. 스크립트를 개발하고 철저히 테스트한 후에는 배포 스크립트 리소스에서 스크립트 파일을 통합하거나 호출할 수 있습니다. 자세한 내용은 스크립트 개발 환경 구성을 참조하세요.
스크립트를 inlineScript.bicep 파일에 저장하고 다음 스크립트를 사용하여 리소스를 배포합니다.
$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
New-AzResourceGroup -Name $resourceGroupName -Location $location
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "inlineScript.bicep"
Write-Host "Press [ENTER] to continue ..."
배포 스크립트 모니터링 및 문제 해결
배포 스크립트 리소스를 배포하는 경우 사용자 스크립트, 실행 결과 및 stdout 파일을 저장할 스토리지 계정이 필요합니다. 사용자 고유의 스토리지 계정을 지정할 수 있습니다. 자세한 내용은 기존 스토리지 계정 사용을 참조하세요.
사용자 고유의 스토리지 계정을 지정하는 대신 cleanupPreference를 OnExpiration로 설정할 수 있습니다. 그런 다음, 스토리지 계정이 제거되기 전에 출력을 검토하는 데 충분한 시간을 허용하는 기간으로 retentionInterval을 구성합니다. 자세한 내용은 배포 스크립트 리소스 정리를 참조하세요.
cleanupPreference 속성을 앞의 Bicep 파일에 추가하고 값을 OnExpiration으로 설정합니다. 기본값은 Always입니다. 또한 rentalInterval을 PT1H(1시간) 또는 더 짧게 설정합니다.
param name string = 'John Dole'
param location string = resourceGroup().location
resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
name: 'inlineCLI'
location: location
kind: 'AzureCLI'
properties: {
azCliVersion: '2.52.0'
arguments: name
scriptContent: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
cleanupPreference: 'OnExpiration'
retentionInterval: 'PT1H'
}
}
output text string = deploymentScript.properties.outputs.text
Bicep 파일을 성공적으로 배포한 후 Azure Portal, Azure CLI, Azure PowerShell 또는 REST API를 사용하여 결과를 확인합니다.
Azure Portal
배포 스크립트 리소스를 배포한 후 리소스는 Azure Portal의 리소스 그룹 아래에 나열됩니다. 개요 페이지에는 배포 스크립트 리소스 외에도 두 개의 지원 리소스가 나열됩니다. 보존 간격이 만료되면 지원 리소스가 삭제됩니다.
두 지원 리소스는 자동으로 만들어지므로 이러한 두 리소스의 이름에 azscripts 접미사가 있습니다. 지원 리소스를 식별하는 다른 방법은 태그를 사용하는 것입니다.
목록에서 배포 스크립트 리소스를 선택합니다. 배포 스크립트 리소스의 개요 페이지에는 프로비전 상태 및 두 개의 지원 리소스(스토리지 계정 및 컨테이너 인스턴스)와 같은 리소스에 대한 중요한 정보가 표시됩니다. 로그 영역에는 스크립트의 인쇄 텍스트가 표시됩니다.
출력을 선택하여 스크립트의 출력을 표시합니다.
리소스 그룹으로 돌아가서 스토리지 계정을 선택하고 파일 공유를 선택한 다음, 공유 이름에 azscripts가 추가된 파일 공유를 선택합니다. 목록에 azscriptinput 및 azscriptoutput이라는 두 개의 폴더가 표시됩니다. 출력 폴더에는 executionresult.json 파일 및 스크립트 출력 파일이 포함되어 있습니다. executionresult.json 파일에는 스크립트 실행 오류 메시지가 포함되어 있습니다. 출력 파일은 스크립트를 성공적으로 실행하는 경우에만 생성됩니다.
입력 폴더에는 시스템 스크립트 파일과 사용자 배포 스크립트 파일이 포함되어 있습니다. 사용자 배포 스크립트 파일을 수정된 파일로 바꾸고 Azure 컨테이너 인스턴스에서 배포 스크립트를 다시 실행할 수 있습니다.
Azure CLI
Azure CLI를 사용하여 구독 또는 리소스 그룹 범위에서 배포 스크립트를 관리할 수 있습니다.
- az deployment-scripts delete: 배포 스크립트를 삭제합니다.
- az deployment-scripts list: 모든 배포 스크립트를 나열합니다.
- az deployment-scripts show: 배포 스크립트를 검색합니다.
- az deployment-scripts show-log: 배포 스크립트 로그를 표시합니다.
list 명령의 출력은 다음 예제와 유사합니다.
{
"arguments": "John Dole",
"azCliVersion": "2.52.0",
"cleanupPreference": "OnExpiration",
"containerSettings": {
"containerGroupName": null
},
"environmentVariables": null,
"forceUpdateTag": null,
"id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
"identity": null,
"kind": "AzureCLI",
"location": "centralus",
"name": "inlineCLI",
"outputs": {
"text": "Hello John Dole"
},
"primaryScriptUri": null,
"provisioningState": "Succeeded",
"resourceGroup": "dsDemo",
"retentionInterval": "1:00:00",
"scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
"status": {
"containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
"endTime": "2023-12-11T20:20:12.149468+00:00",
"error": null,
"expirationTime": "2023-12-11T21:20:12.149468+00:00",
"startTime": "2023-12-11T20:18:26.674492+00:00",
"storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
},
"storageAccountSettings": null,
"supportingScriptUris": null,
"systemData": {
"createdAt": "2023-12-11T19:45:32.239063+00:00",
"createdBy": "johndole@contoso.com",
"createdByType": "User",
"lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
"lastModifiedBy": "johndole@contoso.com",
"lastModifiedByType": "User"
},
"tags": null,
"timeout": "1 day, 0:00:00",
"type": "Microsoft.Resources/deploymentScripts"
}
Azure PowerShell
Azure PowerShell을 사용하여 구독 또는 리소스 그룹 범위에서 배포 스크립트를 관리할 수 있습니다.
- Get-AzDeploymentScript: 배포 스크립트를 가져오거나 나열합니다.
- Get-AzDeploymentScriptLog: 배포 스크립트 실행의 로그를 가져옵니다.
- Remove-AzDeploymentScript: 배포 스크립트와 연결된 해당 리소스를 제거합니다.
- Save-AzDeploymentScriptLog: 배포 스크립트 실행 로그를 디스크에 저장합니다.
Get-AzDeploymentScript 출력은 다음 예제와 유사합니다.
Name : inlinePS
Id : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName : dsDemo
Location : centralus
SubscriptionId : 01234567-89AB-CDEF-0123-456789ABCDEF
ProvisioningState : Succeeded
Identity :
ScriptKind : AzurePowerShell
AzPowerShellVersion : 10.0
StartTime : 12/11/2023 9:45:50 PM
EndTime : 12/11/2023 9:46:59 PM
ExpirationDate : 12/11/2023 10:46:59 PM
CleanupPreference : OnExpiration
StorageAccountId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/ee5o4rmoo6ilmazscripts
Outputs :
Key Value
================== ==================
text Hello John Dole.
RetentionInterval : PT1H
Timeout : P1D
REST API
REST API를 사용하여 리소스 그룹 수준 및 구독 수준에서 배포 스크립트 리소스에 대한 정보를 가져올 수 있습니다.
/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01
/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01
다음 예에서는 ARMClient를 사용합니다. ARMClient는 지원되는 Microsoft 도구가 아닙니다.
armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01
출력은 다음 예제와 유사합니다.
{
"kind": "AzureCLI",
"identity": null,
"location": "centralus",
"systemData": {
"createdAt": "2023-12-11T19:45:32.239063+00:00",
"createdBy": "johndole@contoso.com",
"createdByType": "User",
"lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
"lastModifiedBy": "johndole@contoso.com",
"lastModifiedByType": "User"
},
"properties": {
"provisioningState": "Succeeded",
"azCliVersion": "2.52.0",
"scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
"arguments": "John Dole",
"retentionInterval": "1:00:00",
"timeout": "1 day, 0:00:00",
"containerSettings": {
"containerGroupName": null
},
"status": {
"containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
"endTime": "2023-12-11T20:20:12.149468+00:00",
"error": null,
"expirationTime": "2023-12-11T21:20:12.149468+00:00",
"startTime": "2023-12-11T20:18:26.674492+00:00",
"storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
},
"outputs": {
"text": "Hello John Dole"
},
"cleanupPreference": "OnSuccess"
},
"id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
"type": "Microsoft.Resources/deploymentScripts",
"name": "inlineCLI",
}
다음 REST API는 로그를 반환합니다.
/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01
배포 스크립트 리소스를 삭제하기 전에만 작동합니다.
배포 스크립트 오류 코드
다음 표에서는 배포 스크립트에 대한 오류 코드를 나열합니다.
| 오류 코드 | 설명 |
|---|---|
DeploymentScriptInvalidOperation |
Bicep 파일의 배포 스크립트 리소스 정의에 잘못된 속성 이름이 있습니다. |
DeploymentScriptResourceConflict |
터미널 상태가 아닌 상태에 있는 배포 스크립트 리소스는 삭제할 수 없으며 실행이 1시간을 초과하지 않았습니다. 또는 동일한 리소스 식별자(동일한 구독, 리소스 그룹 이름 및 리소스 이름)를 사용하는 동일한 배포 스크립트를 다시 실행할 수는 없으며, 동시에 다른 스크립트 본문 콘텐츠가 있습니다. |
DeploymentScriptOperationFailed |
배포 스크립트 작업이 내부적으로 실패했습니다. Microsoft 지원에 문의하세요. |
DeploymentScriptStorageAccountAccessKeyNotSpecified |
기존 스토리지 계정에 대한 액세스 키를 지정하지 않았습니다. |
DeploymentScriptContainerGroupContainsInvalidContainers |
배포 스크립트 서비스에서 만든 컨테이너 그룹이 외부에서 수정되었으며 잘못된 컨테이너가 추가되었습니다. |
DeploymentScriptContainerGroupInNonterminalState |
둘 이상의 배포 스크립트 리소스가 동일한 리소스 그룹에서 동일한 Azure Container Instance 이름을 사용하며 그 중 하나는 아직 실행을 완료하지 않았습니다. |
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript |
배포에 제공된 기존 스토리지를 스크립트가 배포되는 구독에서 찾을 수 없습니다. |
DeploymentScriptStorageAccountInvalidKind |
BlobBlobStorage 또는 BlobStorage 유형의 기존 스토리지 계정은 파일 공유를 지원하지 않으므로 사용할 수 없습니다. |
DeploymentScriptStorageAccountInvalidKindAndSku |
기존 스토리지 계정은 파일 공유를 지원하지 않습니다. 지원되는 스토리지 계정 유형 목록은 기존 스토리지 계정 사용을 참조하세요. |
DeploymentScriptStorageAccountNotFound |
스토리지 계정이 존재하지 않거나 외부 프로세스 또는 도구에 의해 삭제되었습니다. |
DeploymentScriptStorageAccountWithServiceEndpointEnabled |
지정된 스토리지 계정에 서비스 엔드포인트가 있습니다. 서비스 엔드포인트가 포함된 스토리지 계정은 지원되지 않습니다. |
DeploymentScriptStorageAccountInvalidAccessKey |
기존 스토리지 계정에 대해 잘못된 액세스 키가 지정되었습니다. |
DeploymentScriptStorageAccountInvalidAccessKeyFormat |
스토리지 계정 키의 형식이 잘못되었습니다. 스토리지 계정 액세스 키 관리를 참조하세요. |
DeploymentScriptExceededMaxAllowedTime |
배포 스크립트 실행 시간이 배포 스크립트 리소스 정의에 지정된 시간 제한 값을 초과했습니다. |
DeploymentScriptInvalidOutputs |
배포 스크립트 출력이 올바른 JSON 개체가 아닙니다. |
DeploymentScriptContainerInstancesServiceLoginFailure |
사용자 할당 관리 ID를 1분 간격으로 10번 시도한 후에는 로그인할 수 없습니다. |
DeploymentScriptContainerGroupNotFound |
배포 스크립트 서비스에서 만든 컨테이너 그룹이 외부 도구나 프로세스에 의해 삭제되었습니다. |
DeploymentScriptDownloadFailure |
지원 스크립트를 다운로드하지 못했습니다. 지원 스크립트 사용을 참조하세요. |
DeploymentScriptError |
사용자 스크립트에서 예외가 발생했습니다. |
DeploymentScriptBootstrapScriptExecutionFailed |
부트스트랩 스크립트에서 오류가 발생했습니다. 부트스트랩 스크립트는 배포 스크립트 실행을 오케스트레이션하는 시스템 스크립트입니다. |
DeploymentScriptExecutionFailed |
배포 스크립트를 실행하는 동안 알 수 없는 오류가 발생했습니다. |
DeploymentScriptContainerInstancesServiceUnavailable |
컨테이너 인스턴스를 만드는 동안 Azure Container Instances 서비스는 "서비스를 사용할 수 없음" 오류를 throw했습니다. |
DeploymentScriptContainerGroupInNonterminalState |
컨테이너 인스턴스를 만들 때 다른 배포 스크립트는 동일한 범위(동일한 구독, 리소스 그룹 이름 및 리소스 이름)에서 동일한 컨테이너 인스턴스 이름을 사용했습니다. |
DeploymentScriptContainerGroupNameInvalid |
지정된 컨테이너 인스턴스 이름이 Azure Container Instances 요구 사항을 충족하지 않습니다. Azure Container Instances에서 일반적인 문제 해결을 참조하세요. |
프라이빗 가상 네트워크에 액세스
몇 가지 추가 구성을 사용하여 프라이빗 네트워크에서 배포 스크립트를 실행할 수 있습니다. 자세한 내용은 프라이빗 가상 네트워크 액세스를 참조하세요.
다음 단계
이 문서에서는 배포 스크립트를 사용하는 방법을 알아보았습니다. 자세한 내용은 다음을 참조하세요.