ARM テンプレートを使用した ACR 転送

[アーティクル]
10/31/2023

前提条件を満たす

この記事の操作を試す前に、こちらで説明されている前提条件を完了してください。これは、次のことを意味します。

両方のクラウドに既存の Premium SKU レジストリがある
両方のクラウドに既存のストレージアカウントコンテナーがある
両方のクラウドに既存の Keyvault があり、必要なアクセス許可を持つ有効な SAS トークンを含むシークレットが格納されている
両方のクラウドに最新バージョンの Az CLI がインストールされている

重要

ACR Transfer では、技術的な制限により、レイヤーサイズが 8 GB に制限された成果物がサポートされています。

Az CLI 拡張機能の使用を検討してください

自動化されていないほとんどのユースケースでは、可能であれば Az CLI 拡張機能を使用することをお勧めします。 Az CLI 拡張機能のドキュメントは、こちらで参照できます。

Resource Manager を使用して ExportPipeline を作成する

Azure Resource Manager テンプレートデプロイを使用して、ソースコンテナーレジストリに ExportPipeline リソースを作成します。

ExportPipeline Resource Manager のテンプレートファイルをローカルフォルダーにコピーします。

ファイル azuredeploy.parameters.json に次のパラメーター値を入力します。

パラメーター	値
registryName	ソースコンテナーレジストリの名前
exportPipelineName	エクスポートパイプライン用に選択した名前
targetUri	ソース環境内のストレージコンテナーの URI (エクスポートパイプラインのターゲット)。例: `https://sourcestorage.blob.core.windows.net/transfer`
KeyVaultName	ソースキーコンテナーの名前
sasTokenSecretName	ソースキーコンテナー内の SAS トークンシークレットの名前例: acrexportsas

エクスポートオプション

エクスポートパイプラインの options プロパティでは、省略可能なブール値がサポートされています。次の値が推奨されます。

パラメーター	値
options	OverwriteBlobs - 既存のターゲット BLOB を上書きします。 ContinueOnErrors - 1 つの成果物のエクスポートが失敗した場合に、ソースレジストリ内の残りの成果物のエクスポートを続行します。

リソースを作成する

次の例に示すように、az deployment group create を実行して exportPipeline という名前のリソースを作成します。既定で、最初のオプションを使用すると、サンプルテンプレートによって ExportPipeline リソースのシステム割り当て ID が有効になります。

2 つ目のオプションを使用すると、リソースにユーザー割り当て ID を指定できます (ユーザー割り当て ID の作成は示されていません)。

どちらのオプションでも、テンプレートによって、エクスポートキーコンテナー内の SAS トークンにアクセスするための ID が構成されます。

オプション 1: リソースを作成し、システム割り当て ID を有効にする

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json

オプション 2:リソースを作成し、ユーザー割り当て ID を指定する

このコマンドでは、ユーザー割り当て ID のリソース ID を追加のパラメーターとして指定します。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

コマンド出力で、パイプラインのリソース ID (id) を書き留めます。この値を後で使用できるように環境変数に格納するには、az deployment group show を実行します。次に例を示します。

EXPORT_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

Resource Manager を使用して ImportPipeline を作成する

Azure Resource Manager テンプレートデプロイを使用して、ターゲットコンテナーレジストリに ImportPipeline リソースを作成します。既定では、ターゲット環境のストレージアカウントに成果物 BLOB が含まれている場合、パイプラインが有効化されて自動的にインポートが行われます。

ImportPipeline Resource Manager のテンプレートファイルをローカルフォルダーにコピーします。

ファイル azuredeploy.parameters.json に次のパラメーター値を入力します。

パラメーター	値
registryName	ターゲットコンテナーレジストリの名前
importPipelineName	インポートパイプライン用に選択した名前
sourceUri	ターゲット環境内のストレージコンテナーの URI (インポートパイプラインのソース)。例: `https://targetstorage.blob.core.windows.net/transfer`
KeyVaultName	ターゲットキーコンテナーの名前
sasTokenSecretName	ターゲットキーコンテナー内の SAS トークンシークレットの名前例: acr importsas

インポートオプション

インポートパイプラインの options プロパティでは、省略可能なブール値がサポートされています。次の値が推奨されます。

パラメーター	値
options	OverwriteTags - 既存のターゲットタグを上書きします。 DeleteSourceBlobOnSuccess - ターゲットレジストリへのインポートが正常に完了した後にソースストレージ BLOB を削除します。 ContinueOnErrors - 1 つの成果物のインポートが失敗した場合に、ターゲットレジストリ内の残りの成果物のインポートを続行します。

パラメーター

値

options

OverwriteTags - 既存のターゲットタグを上書きします。
DeleteSourceBlobOnSuccess - ターゲットレジストリへのインポートが正常に完了した後にソースストレージ BLOB を削除します。
ContinueOnErrors - 1 つの成果物のインポートが失敗した場合に、ターゲットレジストリ内の残りの成果物のインポートを続行します。

リソースを作成する

次の例に示すように、az deployment group create を実行して importPipeline という名前のリソースを作成します。既定で、最初のオプションを使用すると、サンプルテンプレートによって ImportPipeline リソースのシステム割り当て ID が有効になります。

2 つ目のオプションを使用すると、リソースにユーザー割り当て ID を指定できます (ユーザー割り当て ID の作成は示されていません)。

どちらのオプションでも、テンプレートによって、インポートキーコンテナー内の SAS トークンにアクセスするための ID が構成されます。

オプション 1: リソースを作成し、システム割り当て ID を有効にする

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json

オプション 2:リソースを作成し、ユーザー割り当て ID を指定する

このコマンドでは、ユーザー割り当て ID のリソース ID を追加のパラメーターとして指定します。

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

インポートを手動で実行する場合は、パイプラインのリソース ID (id) を書き留めておきます。この値を後で使用できるように環境変数に格納するには、az deployment group show コマンドを実行します。次に例を示します。

IMPORT_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

Resource Manager を使用してエクスポート用に PipelineRun を作成する

Azure Resource Manager テンプレートデプロイを使用して、ソースコンテナーレジストリに PipelineRun リソースを作成します。このリソースでは、前に作成した ExportPipeline リソースが実行され、指定された成果物が BLOB としてコンテナーレジストリからソースストレージアカウントにエクスポートされます。

PipelineRun Resource Manager のテンプレートファイルをローカルフォルダーにコピーします。

ファイル azuredeploy.parameters.json に次のパラメーター値を入力します。

パラメーター	値
registryName	ソースコンテナーレジストリの名前
pipelineRunName	実行用に選択した名前
pipelineResourceId	エクスポートパイプラインのリソース ID 例: `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline`
targetName	myblob など、ソースストレージアカウントにエクスポートされた成果物 BLOB 用に選択した名前
artifacts	タグまたはマニフェストダイジェストとして転送するソース成果物の配列例: `[samples/hello-world:v1", "samples/nginx:v1" , "myrepository@sha256:0a2e01852872..."]`

同じプロパティを使用して PipelineRun リソースを再デプロイする場合は、forceUpdateTag プロパティも使用する必要があります。

az deployment group create を実行して、PipelineRun リソースを作成します。次の例では、デプロイ exportPipelineRun に名前を付けます。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json

後で使用するために、パイプライン実行のリソース ID を環境変数に格納します。

EXPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

成果物のエクスポートには数分かかることがあります。デプロイが正常に完了したら、ソースストレージアカウントの transfer コンテナーでエクスポート済み BLOB を一覧表示することによって、成果物のエクスポートを確認します。たとえば、az storage blob list コマンドを実行します。

az storage blob list \
  --account-name $SOURCE_SA \
  --container transfer \
  --output table

BLOB を転送する (オプション)

AzCopy ツールまたはその他の方法を使用して、ソースストレージアカウントからターゲットストレージアカウントに BLOB データを転送します。

たとえば、次の azcopy copy コマンドを実行すると、ソースアカウントの transfer コンテナーから、ターゲットアカウントの transfer コンテナーへ、myblob がコピーされます。 BLOB がターゲットアカウントに存在する場合は上書きされます。認証では、ソースコンテナーとターゲットコンテナーに対する適切なアクセス許可を持つ SAS トークンが使用されます (トークンを作成する手順については説明しません)。

azcopy copy \
  'https://<source-storage-account-name>.blob.core.windows.net/transfer/myblob'$SOURCE_SAS \
  'https://<destination-storage-account-name>.blob.core.windows.net/transfer/myblob'$TARGET_SAS \
  --overwrite true

ImportPipeline リソースをトリガーする

ImportPipeline の sourceTriggerStatus パラメーターを有効にした場合 (既定値)、BLOB がターゲットストレージアカウントにコピーされた後にパイプラインがトリガーされます。成果物のインポートには数分かかることがあります。インポートが正常に完了したら、ターゲットコンテナーレジストリにリポジトリを一覧表示して、成果物のインポートを確認します。たとえば、az acr repository list を実行します。

az acr repository list --name <target-registry-name>

Note

ソーストリガーによって、過去 60 日以内の最終変更時刻を含む BLOB のみがインポートされます。ソーストリガーを使用してそれより古い BLOB をインポートする場合は、BLOB メタデータを追加して BLOB の最終変更時刻を更新するか、手動で作成したパイプライン実行を使用してインポートしてください。

インポートパイプラインの sourceTriggerStatus パラメーターを有効にしなかった場合は、次のセクションに示すように、ImportPipeline リソースを手動で実行します。

Resource Manager を使用してインポート用に PipelineRun を作成する (省略可能)

PipelineRun リソースを使用して、成果物をターゲットコンテナーレジストリにインポートするための ImportPipeline をトリガーすることもできます。

PipelineRun Resource Manager のテンプレートファイルをローカルフォルダーにコピーします。

ファイル azuredeploy.parameters.json に次のパラメーター値を入力します。

パラメーター	値
registryName	ターゲットコンテナーレジストリの名前
pipelineRunName	実行用に選択した名前
pipelineResourceId	インポートパイプラインのリソース ID 例: `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/importPipelines/myImportPipeline`
sourceName	ストレージアカウント内のエクスポート済み成果物の既存の BLOB の名前 (myblob など)

同じプロパティを使用して PipelineRun リソースを再デプロイする場合は、forceUpdateTag プロパティも使用する必要があります。

az deployment group create を実行して、リソースを実行します。

az deployment group create \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --template-file azuredeploy.json \
  --parameters azuredeploy.parameters.json

後で使用するために、パイプライン実行のリソース ID を環境変数に格納します。

IMPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

デプロイが正常に完了したら、ターゲットコンテナーレジストリにリポジトリを一覧表示して、成果物のインポートを確認します。たとえば、az acr repository list を実行します。

az acr repository list --name <target-registry-name>

PipelineRun リソースを再デプロイする

同じプロパティを使用して PipelineRun リソースを再デプロイする場合は、forceUpdateTag プロパティを使用する必要があります。このプロパティは、構成が変更されていない場合でも、PipelineRun リソースを再作成する必要があることを示します。 PipelineRun リソースを再デプロイするたびに、forceUpdateTag が異なることを確認してください。次の例では、エクスポートの PipelineRun を再作成しています。 forceUpdateTag を設定するために、現在の日時を使用します。これにより、このプロパティは常に一意になります。

CURRENT_DATETIME=`date +"%Y-%m-%d:%T"`

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json \
  --parameters forceUpdateTag=$CURRENT_DATETIME

パイプラインリソースを削除する

次のコマンド例では、az resource delete を使用して、この記事で作成したパイプラインリソースを削除します。このリソース ID は、以前に環境変数に格納したものです。

# Delete export resources
az resource delete \
--resource-group $SOURCE_RG \
--ids $EXPORT_RES_ID $EXPORT_RUN_RES_ID \
--api-version 2019-12-01-preview

# Delete import resources
az resource delete \
--resource-group $TARGET_RG \
--ids $IMPORT_RES_ID $IMPORT_RUN_RES_ID \
--api-version 2019-12-01-preview

ACR 転送のトラブルシューティング

トラブルシューティングのガイダンスについては、「ACR 転送のトラブルシューティング」を参照してください。

次のステップ

ネットワーク制限があるコンテナーレジストリからエクスポートパイプラインの作成をブロックする方法について説明します。

ARM テンプレートを使用した ACR 転送

前提条件を満たす

Az CLI 拡張機能の使用を検討してください

Resource Manager を使用して ExportPipeline を作成する

エクスポート オプション

リソースを作成する

オプション 1: リソースを作成し、システム割り当て ID を有効にする

オプション 2:リソースを作成し、ユーザー割り当て ID を指定する

Resource Manager を使用して ImportPipeline を作成する

インポート オプション

リソースを作成する

オプション 1: リソースを作成し、システム割り当て ID を有効にする

オプション 2:リソースを作成し、ユーザー割り当て ID を指定する

Resource Manager を使用してエクスポート用に PipelineRun を作成する

BLOB を転送する (オプション)

ImportPipeline リソースをトリガーする

Resource Manager を使用してインポート用に PipelineRun を作成する (省略可能)

PipelineRun リソースを再デプロイする

パイプライン リソースを削除する

ACR 転送のトラブルシューティング

次のステップ

その他のリソース

エクスポートオプション

インポートオプション

パイプラインリソースを削除する