Bicep에서 배포 스크립트 개발

이 문서에서는 Bicep에서 배포 스크립트를 개발하는 방법을 보여 주는 예제를 제공합니다.

배포 스크립트 리소스에는 배포 기간이 있을 수 있습니다. 이러한 스크립트를 효율적으로 개발 및 테스트하려면 Azure 컨테이너 인스턴스 또는 Docker 인스턴스와 같은 전용 개발 환경을 설정하는 것이 좋습니다. 자세한 내용은 개발 환경 만들기를 참조하세요.

구문

다음 Bicep 파일은 배포 스크립트 리소스의 예입니다. 자세한 내용은 최신 배포 스크립트 스키마를 참조하세요.

CLI

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

PowerShell

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzurePowerShell'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azPowerShellVersion: '10.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

배포 스크립트에서 다음 속성 값을 지정합니다.

• tags: 배포 스크립트 태그를 지정합니다. 배포 스크립트 서비스에서 두 개의 지원 리소스(스토리지 계정 및 컨테이너 인스턴스)를 만드는 경우 태그는 두 리소스에 모두 전달됩니다. 태그를 사용하여 리소스를 식별할 수 있습니다. 이러한 지원 리소스를 식별하는 또 다른 방법은 azscripts를 포함하는 접미사를 사용하는 것입니다. 자세한 내용은 배포 스크립트 모니터링 및 문제 해결을 참조하세요.

• identity: 배포 스크립트 API 버전 2020-10-01 이상에서는 스크립트에서 Azure 관련 작업을 수행해야 하거나 프라이빗 네트워크에서 배포 스크립트를 실행하는 경우가 아니라면 사용자 할당 관리 ID가 선택 사항입니다. 배포 스크립트 서비스에서 스크립트를 실행하는 데 사용하기 때문에 API 버전 2019-10-01-preview에는 관리 ID가 필요합니다.

  identity 속성을 지정하면 스크립트 서비스가 사용자 스크립트를 호출하기 전에 Connect-AzAccount -Identity를 호출합니다. 현재 사용자가 할당한 관리 ID만 지원됩니다. 배포 스크립트에서 다른 ID로 로그인하려면 Connect-AzAccount를 호출할 수 있습니다. 자세한 내용은 최소 권한 구성을 참조하세요.

• kind: 스크립트 유형을 AzurePowerShell 또는 AzureCLI로 지정합니다. kind 외에 azCliVersion 또는 azPowerShellVersion 속성을 지정해야 합니다.

• storageAccountSettings: 기존 스토리지 계정을 사용하려면 설정을 지정합니다. storageAccountName을 지정하지 않으면 스토리지 계정이 자동으로 만들어집니다. 자세한 내용은 기존 스토리지 계정 사용을 참조하세요.

• containerSettings: Azure 컨테이너 인스턴스의 이름을 사용자 지정합니다. 컨테이너의 그룹 이름을 구성하는 방법에 대한 내용은 이 문서의 뒷부분에 있는 컨테이너 인스턴스 구성을 참조하세요. 프라이빗 네트워크에서 배포 스크립트를 실행하도록 subnetIds를 구성하는 방법에 대한 내용은 프라이빗 가상 네트워크 액세스를 참조하세요.

• environmentVariables: 스크립트에 전달할 환경 변수를 지정합니다.

• azPowerShellVersion/azCliVersion: 사용할 모듈 버전을 지정합니다.

  CLI

  지원되는 Azure CLI 버전 목록을 참조하세요.

  Important

  배포 스크립트는 Microsoft Artifact Registry에서 사용 가능한 CLI 이미지를 사용합니다. 일반적으로 배포 스크립트의 CLI 이미지를 인증하는 데 약 한 달이 걸립니다. 지난 30일 이내에 릴리스된 CLI 버전은 사용하지 마세요. 이미지의 릴리스 날짜를 확인하려면 Azure CLI 릴리스 정보를 참조하세요. 지원되지 않는 버전을 사용하는 경우 오류 메시지에 지원되는 버전이 나열됩니다.

  PowerShell

  지원되는 Azure PowerShell 버전 목록을 참조하세요. 버전은 사용할 컨테이너 이미지를 결정합니다.

  • 9 이상 Az 버전은 Ubuntu 22.04를 사용합니다.
  • 6이상 9 미만 Az 버전은 Ubuntu 20.04를 사용합니다.
  • 6 미만 Az 버전은 Ubuntu 18.04를 사용합니다.

  Important

  최신 버전의 Ubuntu로 업그레이드하는 것이 좋습니다. Ubuntu 18.04는 지원이 종료가 가까워지고 있으며 2023년 5월 31일 이후에는 보안 업데이트가 수신되지 않습니다.

• arguments: 매개 변수 값을 지정합니다. 값은 공백으로 구분됩니다.

  배포 스크립트는 CommandLineToArgvW 시스템 호출을 불러와 인수를 문자열 배열로 분할합니다. 인수가 Azure Container Instance에 명령 속성으로 전달되고 명령 속성이 문자열 배열이기 때문에 이 단계가 필요합니다.

  인수에 이스케이프된 문자가 포함된 경우 문자를 두 번 이스케이프합니다. 예를 들어 이전 샘플 Bicep 구문에서 인수는 -name \"John Dole\"입니다. 이스케이프된 문자열은 -name \\"John Dole\\"입니다.

  object 형식의 Bicep 매개 변수를 인수로 전달하려면 string() 함수를 사용하여 개체를 문자열로 변환한 다음, replace() 함수를 사용하여 따옴표(")를 이중 이스케이프 따옴표(\\")로 바꿉니다. 예시:

  replace(string(parameters('tables')), '"', '\\"')
  

  자세한 내용은 샘플 Bicep 파일을 참조하세요.

• scriptContent: 스크립트 콘텐츠를 지정합니다. loadTextContent 함수를 사용하여 가져온 인라인 스크립트 또는 외부 스크립트 파일일 수 있습니다. 자세한 내용은 이 문서의 뒷부분에 있는 인라인 파일과 외부 파일을 참조하세요. 외부 스크립트를 실행하려면 primaryScriptUri를 대신 사용합니다.

• primaryScriptUri: 지원되는 파일 확장명을 사용하여 기본 배포 스크립트에 공개적으로 액세스할 수 있는 URL을 지정합니다. 자세한 내용은 이 문서의 뒷부분에 있는 외부 스크립트 사용을 참조하세요.

• supportingScriptUris: scriptContent 또는 primaryScriptUri에서 호출되는 지원 파일에 공개적으로 액세스할 수 있는 URL 배열을 지정합니다. 자세한 내용은 이 문서의 뒷부분에 있는 인라인 파일과 외부 파일을 참조하세요.

• timeout: 스크립트 실행에 허용되는 최대 시간을 ISO 8601 형식으로 지정합니다. 기본값은 P1D입니다.

• forceUpdateTag: Bicep 파일 배포 간에 이 값을 변경하면 배포 스크립트가 강제로 다시 실행됩니다. utcNow() 또는 newGuid() 함수를 사용하는 경우 매개 변수의 기본값에서만 사용할 수 있습니다. 자세한 내용은 이 문서의 뒷부분에서 스크립트 두 번 이상 실행을 참조하세요.

• cleanupPreference. 스크립트 실행이 터미널 상태에 있을 때 지원되는 두 가지 배포 리소스(스토리지 계정 및 컨테이너 인스턴스)를 정리하는 기본 설정을 지정합니다. 기본 설정은 터미널 상태(Succeeded, Failed 또는 Canceled)에 관계없이 지원 리소스의 삭제를 요구하는 Always입니다. 자세한 내용은 이 문서 뒷부분에 나오는 배포 스크립트 리소스 정리를 참조하세요.

• retentionInterval: 배포 스크립트 실행이 터미널 상태에 도달하면 서비스에서 배포 스크립트 리소스를 유지하는 간격을 지정합니다. 이 기간이 만료되면 배포 스크립트 리소스가 삭제됩니다. 기간은 ISO 8601 패턴을 기반으로 합니다. 보존 간격은 1시간(PT1H)~26시간(PT26H)입니다. 이 속성은 cleanupPreference를 OnExpiration로 설정될 때 사용합니다. 자세한 내용은 이 문서 뒷부분에 나오는 배포 스크립트 리소스 정리를 참조하세요.

추가 샘플

• 샘플 1: 키 자격 증명 모음을 만들고 배포 스크립트를 사용하여 키 자격 증명 모음에 인증서를 할당합니다.
• 샘플 2: 구독 수준에서 리소스 그룹을 만들고 리소스 그룹에 키 자격 증명 모음을 만든 다음, 배포 스크립트를 사용하여 키 자격 증명 모음에 인증서를 할당합니다.
• 샘플 3: 사용자 할당 관리 ID를 만들고, 리소스 그룹 수준에서 ID에 참가자 역할을 할당하고, 키 자격 증명 모음을 만든 다음, 배포 스크립트를 사용하여 인증서를 키 자격 증명 모음에 할당합니다.
• 샘플 4: 사용자 할당 관리 ID를 수동으로 만들고 Microsoft Graph API를 사용하여 Microsoft Entra 애플리케이션을 만들 수 있는 권한을 할당합니다. Bicep 파일에서 배포 스크립트를 사용하여 Microsoft Entra 애플리케이션 및 서비스 주체를 만들고 개체 ID 및 클라이언트 ID를 출력합니다.

인라인 및 외부 파일

배포 스크립트는 Bicep 파일 내에 상주하거나 외부에 별도의 파일로 저장할 수 있습니다.

인라인 스크립트 사용

다음 Bicep 파일은 인라인 스크립트를 사용하는 방법을 보여 줍니다.

CLI

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: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

명령이 0이 아닌 상태를 반환하는 경우 즉시 종료를 사용하도록 스크립트에 set -e를 포함합니다. 이 사례는 오류 디버깅 프로세스를 간소화합니다.

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $ErrorActionPreference = 'Stop'
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
    '''
    retentionInterval: 'P1D'
  }
}

배포 스크립트에서 $ErrorActionPreference 변수를 사용하여 Azure PowerShell이 종료되지 않는 오류에 대응하는 방식을 제어할 수 있습니다. 배포 스크립트에 변수를 설정하지 않으면 스크립트 서비스에서 기본값인 Continue를 사용합니다. 값을 Stop으로 설정하면 오류를 더 쉽게 디버그할 수 있습니다.

스크립트 서비스는 Failed 설정에도 불구하고 스크립트에 오류가 발생하면 리소스 프로비저닝 상태를 $ErrorActionPreference로 설정합니다.

스크립트 파일 로드

loadTextContent 함수를 사용하여 스크립트 파일을 문자열로 검색합니다. 이 함수를 사용하면 외부 파일에서 스크립트를 유지 관리하고 배포 스크립트로 액세스할 수 있습니다. 스크립트 파일에 대해 지정한 경로는 Bicep 파일에 상대적입니다.

CLI

위 Bicep 파일의 인라인 스크립트를 hello.sh 파일로 추출한 다음, scripts라는 하위 폴더에 파일을 배치할 수 있습니다.

output="Hello $1"
echo $output

그런 다음, 다음 예제와 같이 이전 Bicep 파일을 수정할 수 있습니다.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

PowerShell

위 Bicep 파일의 인라인 스크립트를 hello.ps1 파일로 추출한 다음, scripts라는 하위 폴더에 파일을 배치할 수 있습니다.

param([string] $name)
$output = "Hello {0}" -f $name
Write-Output "Output is: '$output'."

그런 다음, 다음 예제와 같이 이전 Bicep 파일을 수정할 수 있습니다.

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: loadTextContent('./scripts/hello.ps1')
    retentionInterval: 'P1D'
  }
}

외부 스크립트 사용

인라인 스크립트 대신 외부 스크립트 파일을 사용할 수 있습니다. 확장명이 ps1인 기본 PowerShell 스크립트만 지원됩니다. CLI 스크립트의 경우 기본 스크립트는 유효한 Bash 스크립트 확장을 전달하거나 확장이 전혀 없을 수 있습니다. 외부 스크립트 파일을 사용하려면 scriptContent를 primaryScriptUri로 바꿉니다.

CLI

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.ps1'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

외부 스크립트 파일에 액세스할 수 있어야 합니다. Azure Storage 계정에 저장된 스크립트 파일을 보호하려면 SAS(공유 액세스 서명) 토큰을 생성하여 템플릿의 URI에 포함합니다. 배포를 완료할 만큼 충분한 여유를 두고 만료를 설정합니다. 자세한 내용은 SAS 토큰을 사용하여 프라이빗 ARM 템플릿 배포를 참조하세요.

배포 스크립트에서 참조하는 스크립트(primaryScriptUri 또는 supportingScriptUris)의 무결성을 확인해야 합니다. 신뢰하는 스크립트만 참조하세요.

지원 스크립트 사용

복잡한 논리를 하나 이상의 지원 스크립트 파일로 분리할 수 있습니다. 필요한 경우 supportingScriptUris 속성을 사용하여 지원 스크립트 파일에 URI 배열을 제공할 수 있습니다.

CLI

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
      ./hello.ps1 -name $name
    '''
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.ps1'
    ]
    retentionInterval: 'P1D'
  }
}

지원 스크립트 파일은 인라인 스크립트 및 기본 스크립트 파일 모두에서 호출할 수 있습니다. 지원 스크립트 파일에는 파일 확장명에 대한 제한이 없습니다.

지원 파일은 런타임에 azscripts/azscriptinput에 복사됩니다. 인라인 스크립트 및 기본 스크립트 파일에서 지원 파일을 참조하려면 상대 경로를 사용합니다.

Azure 리소스 액세스

Azure 리소스에 액세스하려면 identity 요소를 구성해야 합니다. 다음 Bicep 파일은 Azure 키 자격 증명 모음 목록을 검색하는 방법을 보여 줍니다. 키 자격 증명 모음에 액세스할 수 있는 사용자 할당 관리 ID 권한도 부여해야 합니다.

CLI

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

PowerShell

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvPS'
  location: location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      $kvs=Get-AzKeyVault

      $output = @()
      foreach($kv in $kvs){
        $newKv = @{
          id = $kv.resourceId
        }
        $output = $output + $newKv
      }
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs["kvs"] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

참고 항목

이제 Azure 로그인에 대한 다시 시도 논리가 래퍼 스크립트에 기본적으로 제공됩니다. 배포 스크립트와 동일한 Bicep에서 권한을 부여하는 경우 배포 스크립트 서비스는 관리 ID 역할 할당이 복제될 때까지 10초 간격으로 10분 동안 로그인을 다시 시도합니다.

출력 작업

출력 처리 방법은 사용 중인 스크립트 유형(Azure CLI 또는 Azure PowerShell)에 따라 달라집니다.

CLI

Azure CLI 배포 스크립트는 AZ_SCRIPTS_OUTPUT_PATH라는 환경 변수를 사용하여 스크립트 출력에 대한 파일의 위치를 나타냅니다. Bicep 파일 내에서 배포 스크립트를 실행하는 경우 Bash 셸은 이 환경 변수를 자동으로 구성합니다. 미리 정의된 값은 /mnt/azscripts/azscriptoutput/scriptoutputs.json으로 설정됩니다.

출력은 유효한 JSON 문자열 개체 구조를 따라야 합니다. 파일의 콘텐츠는 키/값 쌍으로 형식이 지정되어야 합니다. 예를 들어 문자열 배열을 { "MyResult": [ "foo", "bar"] }로 저장합니다. [ "foo", "bar" ]와 같은 배열 결과만 저장하는 것은 유효하지 않습니다.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

앞의 샘플에서는 jq를 사용하여 출력을 생성합니다. jq 도구는 컨테이너 이미지와 함께 제공됩니다. 자세한 내용은 개발 환경 구성을 참조하세요.

PowerShell

Azure PowerShell 배포 스크립트는 스크립트 출력을 저장하기 위한 공통 변수를 노출합니다.

다음 Bicep 파일에서는 두 deploymentScripts 리소스 간에 값을 전달하는 방법을 보여 줍니다. 첫 번째 리소스에서는 $DeploymentScriptOutputs라는 변수를 정의하고 이 변수를 사용하여 출력 값을 저장합니다. 리소스 기호 이름을 사용하여 출력 값에 액세스합니다.

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript1 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS1'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

resource deploymentScript2 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS2'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-textToEcho \\"${deploymentScript1.properties.outputs.text}\\"'
    scriptContent: '''
      param([string] $textToEcho)
      Write-Output $textToEcho
    '''
    retentionInterval: 'P1D'
  }
}

환경 변수 사용

배포 스크립트에 보안 문자열 전달

컨테이너 인스턴스에서 환경 변수(EnvironmentVariable)를 설정하여 컨테이너가 실행하는 애플리케이션 또는 스크립트의 동적 구성을 제공할 수 있습니다. 배포 스크립트는 Azure Container Instances와 동일한 방식으로 비보안 및 보안 환경 변수를 처리합니다. 자세한 내용은 컨테이너 인스턴스에서 환경 변수 설정을 참조하세요.

환경 변수에 대해 허용되는 최대 크기는 64KB입니다.

CLI

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

PowerShell

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: '''
      Write-output "Username is :$Username"
      Write-output "Password is: $Password"
    '''
    retentionInterval: 'P1D'
  }
}

시스템 정의 환경 변수

다음 표에서는 시스템 정의 환경 변수를 나열합니다.

환경 변수	기본값(CLI)	기본값(PowerShell)	시스템이 예약됨
AZ_SCRIPTS_AZURE_ENVIRONMENT	AzureCloud	AzureCloud	아니요
AZ_SCRIPTS_CLEANUP_PREFERENCE	Always	Always	아니요
AZ_SCRIPTS_OUTPUT_PATH	/mnt/azscripts/azscriptoutput/scriptoutputs.json	해당 없음	예
AZ_SCRIPTS_PATH_INPUT_DIRECTORY	/mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput	해당 없음	예
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY	/mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput	해당 없음	예
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME	userscript.sh	userscript.ps1	네
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	primaryscripturi.config	primaryscripturi.config	네
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	supportingscripturi.config	supportingscripturi.config	네
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	scriptoutputs.json	scriptoutputs.json	네
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	executionresult.json	executionresult.json	예
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	해당 없음	해당 없음	아니요

AZ_SCRIPTS_OUTPUT_PATH 사용 샘플은 이 문서의 앞부분에 있는 출력 작업을 참조하세요.

환경 변수에 액세스하려면 다음 코드를 사용합니다.

CLI

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

PowerShell

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      Write-Output "AZ_SCRIPTS_AZURE_ENVIRONMENT is : ${Env:AZ_SCRIPTS_AZURE_ENVIRONMENT}"
      Write-Output "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : ${Env:AZ_SCRIPTS_CLEANUP_PREFERENCE}"
      Write-Output "AZ_SCRIPTS_OUTPUT_PATH	is : ${Env:AZ_SCRIPTS_OUTPUT_PATH}"
      Write-Output "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_INPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : ${Env:AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : ${Env:AZ_SCRIPTS_USER_ASSIGNED_IDENTITY}"
    '''
    retentionInterval: 'P1D'
  }
}

기존 스토리지 계정 사용

스크립트를 실행하고 문제 해결을 허용하려면 스토리지 계정과 컨테이너 인스턴스가 필요합니다. 기존 스토리지 계정을 지정하거나 스크립트 서비스가 스토리지 계정과 컨테이너 인스턴스를 자동으로 만들도록 할 수 있습니다.

기존 스토리지 계정을 사용하기 위한 요구 사항은 다음과 같습니다.

• 다음 표에서는 지원되는 계정 유형을 나열합니다. 계층에 대한 열은 -SkuName 또는 --sku 매개 변수의 값을 참조합니다. 지원되는 형식에 대한 열은 -Kind 또는 --kind 매개 변수를 참조합니다.

  계층	지원 형식
  Premium_LRS	FileStorage
  Premium_ZRS	FileStorage
  Standard_GRS	Storage, StorageV2
  Standard_GZRS	StorageV2
  Standard_LRS	Storage, StorageV2
  Standard_RAGRS	Storage, StorageV2
  Standard_RAGZRS	StorageV2
  Standard_ZRS	StorageV2

  이러한 조합은 파일 공유를 지원합니다. 자세한 내용은 Azure 파일 공유 만들기 및 스토리지 계정 유형을 참조하세요.

• 스토리지 계정에 대한 방화벽 규칙은 아직 지원되지 않습니다. 자세한 내용은 Azure Storage 방화벽 및 가상 네트워크 구성을 참조하세요.

• 배포 주체에는 스토리지 계정을 관리할 수 있는 사용 권한이 있어야 합니다. 여기에는 파일 공유 읽기, 만들기, 삭제가 포함됩니다. 자세한 내용은 최소 권한 구성을 참조하세요.

기존 스토리지 계정을 지정하려면 Microsoft.Resources/deploymentScripts의 속성 요소에 다음 Bicep 코드를 추가합니다.

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

전체 Microsoft.Resources/deploymentScripts 정의 샘플은 이 문서의 앞부분에 있는 구문을 참조하세요.

기존 스토리지 계정을 사용하는 경우 스크립트 서비스는 고유한 이름을 사용하여 파일 공유를 만듭니다. 스크립트 서비스에서 파일 공유를 정리하는 방법은 배포 스크립트 리소스 정리를 참조하세요.

컨테이너 인스턴스 구성

배포 스크립트에는 새 Azure 컨테이너 인스턴스가 필요합니다. 기존 컨테이너 인스턴스는 지정할 수 없습니다. 그러나 containerGroupName을 사용하여 컨테이너 그룹 이름을 사용자 지정할 수 있습니다. 그룹 이름을 지정하지 않으면 자동으로 생성됩니다. 이 컨테이너 인스턴스를 만들려면 추가 구성이 필요합니다. 자세한 내용은 최소 권한 구성을 참조하세요.

프라이빗 네트워크에서 배포 스크립트를 실행하기 위한 subnetId 값을 지정할 수도 있습니다. 자세한 내용은 프라이빗 가상 네트워크 액세스를 참조하세요.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

스크립트를 두 번 이상 실행

배포 스크립트 실행은 idempotent 작업입니다. deploymentScripts 리소스 속성(인라인 스크립트 포함)이 변경되지 않은 경우 Bicep 파일을 다시 배포할 때 스크립트가 실행되지 않습니다.

배포 스크립트 서비스는 Bicep 파일의 리소스 이름을 같은 리소스 그룹에 있는 기존 리소스와 비교합니다. 동일한 배포 스크립트를 여러 번 실행하려는 경우 다음 두 가지 옵션을 사용할 수 있습니다.

• deploymentScripts 리소스 그룹의 이름을 바꿉니다. 예를 들어 리소스 이름 또는 리소스 이름의 일부로 utcNow 함수를 사용합니다. utcNow 함수는 매개 변수의 기본값에만 사용할 수 있습니다.

  리소스 이름을 변경하면 새 deploymentScripts 리소스가 생성됩니다. 스크립트 실행 기록을 보관하는 것이 좋습니다.

• forceUpdateTag 속성에 다른 값을 지정합니다. 예를 들어 값으로 utcNow를 사용합니다.

배포 스크립트를 작성하여 멱등성을 보장함으로써 실수로 다시 실행해도 시스템 변경이 발생하지 않도록 합니다. 예를 들어 배포 스크립트를 통해 Azure 리소스를 만들 때 스크립트가 성공하거나 중복 리소스 생성을 방지하도록 만들기 전에 해당 리소스가 없는지 확인합니다.

배포 스크립트 내에서 Microsoft Graph 사용

배포 스크립트는 Microsoft Graph를 사용하여 Microsoft Entra ID에서 개체를 만들고 작업할 수 있습니다.

명령

Azure CLI 배포 스크립트를 사용하는 경우 az ad 명령 그룹 내의 명령을 사용하여 애플리케이션, 서비스 주체, 그룹 및 사용자로 작업할 수 있습니다. az rest 명령을 사용하여 Microsoft Graph API를 직접 호출할 수도 있습니다.

Azure PowerShell 배포 스크립트를 사용하는 경우 Invoke-RestMethod cmdlet을 사용하여 Microsoft Graph API를 직접 호출할 수 있습니다.

사용 권한

배포 스크립트에서 사용하는 ID는 Microsoft Graph API로 작업할 수 있는 권한을 부여하고 수행하는 작업에 적절한 권한을 부여해야 합니다. 사용자가 할당한 관리 ID를 미리 만들고 Microsoft Graph에 대한 앱 역할을 할당하는 등, Bicep 파일 외부에서 ID에 권한을 부여해야 합니다. 자세한 내용은 이 빠른 시작 예제를 참조하세요.

배포 스크립트 리소스 정리

자동으로 생성된 두 지원 리소스는 삭제하는 데 실패하지 않는 한, deploymentScript 리소스보다 오래 유지될 수 없습니다. cleanupPreference 속성은 지원 리소스의 수명 주기를 제어합니다. retentionInterval 속성은 deploymentScript 리소스의 수명 주기를 제어합니다. 이러한 속성을 사용하는 방법은 다음과 같습니다.

• cleanupPreference: 스크립트 실행이 터미널 상태가 되면 두 지원 리소스의 정리 기본 설정을 지정합니다. 지원되는 값은 다음과 같습니다.

  • Always: 스크립트 실행이 터미널 상태가 되면 두 지원 리소스를 삭제합니다. 기존 스토리지 계정을 사용하는 경우 스크립트 서비스는 서비스에서 생성된 파일 공유를 삭제합니다. 지원 리소스 정리 후 deploymentScripts 리소스가 계속 존재할 수 있기 때문에 스크립트 서비스는 리소스를 삭제하기 전에 스크립트 실행 결과(예: stdout), 출력, 값 반환 등을 유지합니다.

  • OnSuccess: 스크립트가 성공적으로 실행되는 경우에만 두 지원 리소스를 삭제합니다. 기존 스토리지 계정을 사용하는 경우 스크립트 서비스는 스크립트 실행에 성공한 경우에만 파일 공유를 제거합니다.

    스크립트 실행이 성공하지 못하면 스크립트 서비스는 지원 리소스를 정리한 다음, 배포 스크립트 리소스를 정리하기 전에 retentionInterval 값이 만료될 때까지 기다립니다.

  • OnExpiration: retentionInterval 설정이 만료된 경우에만 두 지원 리소스를 삭제합니다. 기존 스토리지 계정을 사용하는 경우 스크립트 서비스는 파일 공유를 제거하지만 스토리지 계정은 유지합니다.

  컨테이너 인스턴스 및 스토리지 계정은 cleanupPreference 값에 따라 삭제됩니다. 그러나 스크립트가 실패하고 cleanupPreference가 Always로 설정되어 있지 않은 경우 배포 프로세스는 자동으로 컨테이너를 1시간 동안 또는 컨테이너가 정리될 때까지 계속 실행합니다. 이 시간 동안 스크립트 문제를 해결할 수 있습니다.

  배포에 성공한 후에도 컨테이너를 계속 실행하려면 스크립트에 절전 단계를 추가하세요. 예를 들어 스크립트 끝에 시작-절전을 추가합니다. 절전 단계를 추가하지 않으면 컨테이너는 터미널 상태로 설정되며 아직 삭제되지 않은 경우에도 액세스할 수 없습니다.

• retentionInterval: deploymentScript 리소스가 유지된 시점부터 만료 및 삭제되기 전까지의 시간 간격을 지정합니다.

참고 항목

스크립트 서비스에서 생성하는 스토리지 계정 및 컨테이너 인스턴스는 다른 용도로 사용하지 않는 것이 좋습니다. 스크립트 수명 주기에 따라 두 리소스가 제거될 수 있습니다.

다음 단계

이 문서에서는 배포 스크립트 리소스를 만드는 방법을 알아보았습니다. 자세히 알아보려면 다음을 수행합니다.

Bicep에서 배포 스크립트 사용