Bicep でデプロイスクリプトを使う

[アーティクル]
01/09/2024

deploymentScripts リソースを使うと、Bicep デプロイでスクリプトを実行し、実行結果を確認できます。これらのスクリプトを使って、次のようなカスタム手順を実行できます。

ユーザーをディレクトリに追加します。
データプレーン操作 (BLOB のコピー、シードデータベースなど) を実行する。
ライセンスキーを検索して検証します。
自己署名証明書を作成します。
Microsoft Entra ID でオブジェクトを作成します。
カスタムシステムから IP アドレスブロックを検索する。

デプロイスクリプトには次のような利点があります。

簡単にコーディング、使用、デバッグができます。デプロイスクリプトは、好みの開発環境で開発できます。スクリプトは、Bicep ファイルか外部スクリプトファイルに埋め込むことができます。
スクリプト言語とプラットフォームを指定できます。現時点では、Linux 環境の Azure PowerShell と Azure CLI のデプロイスクリプトがサポートされています。
スクリプトにコマンドライン引数を渡すことができます。
スクリプトの出力を指定して、デプロイに渡すことができます。

デプロイスクリプトリソースは、Azure Container Instances が使用可能なリージョンでのみ使用できます。詳細については、「Azure リージョンの Azure Container Instances のリソースの可用性」を参照してください。

警告

デプロイスクリプトサービスでは、スクリプトの実行とトラブルシューティングのために、ストレージアカウントとコンテナーインスタンスという 2 つの追加リソースが必要です。一般に、デプロイスクリプトが完了すると、このサービスによってこれらのリソースはクリーンアップされます。これらのリソースが削除されるまでは料金が発生します。

価格情報については、「Container Instances の価格」と「Azure Storage の料金」を参照してください。詳細については、「デプロイスクリプトリソースのクリーンアップ」を参照してください。

トレーニングリソース

ステップバイステップガイダンスでデプロイスクリプトについて学習する場合は、「デプロイスクリプトを使用して Bicep および ARM テンプレートを拡張する」を参照してください。

最低限のアクセス許可を構成する

デプロイスクリプトの API バージョン 2020-10-01 以降では、デプロイスクリプトの実行に 2 つのプリンシパルが関係します。

デプロイプリンシパル: このプリンシパルは、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 を呼び出す必要がある場合のみです。デプロイスクリプトプリンシパルの指定には 2 とおりの方法があります。
- identity プロパティにユーザー割り当てマネージド ID を指定します (デプロイスクリプトリソースの構文を参照してください)。ユーザー割り当てマネージド ID を指定すると、スクリプトサービスにより、デプロイスクリプトの呼び出し前に Connect-AzAccount -Identity が呼び出されます。マネージド ID に、スクリプト内の操作を完了するために必要なアクセス権がある必要があります。現在、identity プロパティにサポートされているのは、ユーザー割り当てマネージド ID のみです。別の ID でログインするには、この箇条書きの 2 つ目の方法を使用してください。
- サービスプリンシパルの資格情報を安全な環境変数として渡してから、デプロイスクリプトで Connect-AzAccount または az login を呼び出します。
マネージド ID を使う場合は、マネージ ID リソースに割り当てられた組み込みのマネージド ID オペレーターロールがデプロイプリンシパルに必要です。

現在のところ、デプロイスクリプトのアクセス許可を構成するための組み込みロールはありません。

配置スクリプトを作成する

次の例は、デプロイスクリプトリソースを含む単純な Bicep ファイルを示しています。このスクリプトは 1 つの文字列パラメーターを受け取り、別の文字列を作成します。

CLI
PowerShell

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

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)
      Write-Host 'The argument is {0}' -f $name
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'PT1H'
  }
}

output result string = deploymentScript.properties.outputs.text

デプロイスクリプトリソースの作成の詳細については、デプロイスクリプトの作成に関する記事を参照してください。デプロイスクリプトリソースのためにスクリプトを作成するには、Azure Container Instances や 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 を構成します。詳細については、「デプロイスクリプトリソースをクリーンアップする」を参照してください。

先ほどの Bicep ファイルに cleanupPreference プロパティを追加し、値を OnExpiration に設定します。既定値は Always です。また、rentalInterval を PT1H (1 時間) 以下に設定します。

CLI
PowerShell

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

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)
      Write-Output "The argument is {0}." -f $name
      $output = "Hello {0}." -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

Bicep ファイルを正常にデプロイしたら、Azure portal、Azure CLI、Azure PowerShell、または REST API を使って結果を確認します。

Azure portal

デプロイスクリプトリソースをデプロイすると、Azure portal のリソースグループの下にそのリソースが一覧表示されます。 [概要] ページには、デプロイスクリプトリソースに加えて、2 つのサポートリソースが表示されます。リテンション期間が過ぎると、サポートリソースは削除されます。

これらのリソースは自動的に作成されるため、両方のサポートリソースの名前に azscripts というサフィックスが付いていることに注目してください。サポートリソースを特定するもう 1 つの方法は、タグを使うことです。

デプロイスクリプトリソースグループのスクリーンショット。

一覧からデプロイスクリプトリソースを選びます。デプロイスクリプトリソースの [概要] ページには、リソースに関する重要な情報が表示されます。たとえば、[プロビジョニングの状態]、2 つのサポートリソース ([ストレージアカウント] と [コンテナーインスタンス]) などです。 [ログ] 領域には、スクリプトからの出力テキストが表示されます。

デプロイスクリプトリソースに関する情報のスクリーンショット。

[出力] を選ぶと、スクリプトの出力が表示されます。

デプロイスクリプトの出力のスクリーンショット。

リソースグループに戻り、ストレージアカウントを選び、[ファイル共有] を選びます。次に、共有名に azscripts が付いたファイル共有を選びます。 azscriptinput と azscriptoutput という 2 つのフォルダーが一覧に表示されます。出力フォルダーには、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`	2 つ以上のデプロイスクリプトリソースによって、同じリソースグループ内で同じ Azure コンテナーインスタンス名が使用されており、そのうちの 1 つでまだ実行が完了していません。
`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 サービスから "サービスを利用できません" というエラーがスローされました。
`DeploymentScriptContainerGroupInNonterminalState`	コンテナーインスタンスの作成時に、別のデプロイスクリプトが同じスコープ (同じサブスクリプション、リソースグループ名、リソース名) の同じコンテナーインスタンス名を使っていました。
`DeploymentScriptContainerGroupNameInvalid`	指定されたコンテナーインスタンス名が Azure Container Instances の要件を満たしていません。「Azure Container Instances における、トラブルシューティングに関する一般的問題」を参照してください。

プライベート仮想ネットワークにアクセスする

追加で構成すると、プライベートネットワークでデプロイスクリプトを実行できます。詳細については、「プライベート仮想ネットワークにアクセスする」を参照してください。

次のステップ

この記事では、デプロイスクリプトの使用方法について学習しました。詳細については、以下をご覧ください。

Bicep でデプロイ スクリプトを使う

トレーニング リソース