Az CLI を使用した ACR 転送

この記事では、acrtransfer Az CLI 拡張機能で ACR 転送機能を使用する方法について説明します。

前提条件を満たす

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

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

Az CLI 拡張機能をインストールする

AzureCloud では、次のコマンドを使用して拡張機能をインストールできます。

az extension add --name acrtransfer

AzureCloud および他のクラウドでは、BLOB をパブリック ストレージ アカウント コンテナーから直接インストールできます。 BLOB は、acrtransferext ストレージ アカウント、dist コンテナー、acrtransfer-1.0.0-py2.py3-none-any.wh BLOB でホストされます。 使用しているクラウドによっては、ストレージ URL のサフィックスを変更することが必要な場合があります。 次のコードが AzureCloud にインストールされます。

az extension add --source https://acrtransferext.blob.core.windows.net/dist/acrtransfer-1.0.0-py2.py3-none-any.whl

acrtransfer Az CLI 拡張機能を使用して ExportPipeline を作成する

acrtransfer Az CLI 拡張機能を使用して、AzureCloud コンテナー レジストリの ExportPipeline リソースを作成します。

オプションを使用せず、システム割り当て ID を使用して、エクスポート パイプラインを作成します。

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer

使用可能なすべてのオプションとユーザー割り当て ID を使用してエクスポート パイプラインを作成します。

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--options OverwriteBlobs ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity

エクスポート オプション

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

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

ExportPipeline ID に keyvault ポリシー アクセスを付与する

ユーザー割り当て ID を使用してパイプラインを作成した場合は、このユーザー割り当て ID に、keyvault に対する secret get アクセス ポリシーのアクセス許可を付与するだけです。

システム割り当て ID を使用してパイプラインを作成した場合は、まず、お使いのパイプライン リソースにシステムによって割り当てられた principalId を取得する必要があります。

パイプライン リソースを取得するには、次のコマンドを実行します。

az acr export-pipeline show --resource-group $MyRG --registry $MyReg --name $MyPipeline

この出力から、principalId フィールドの値をコピーします。

次に、次のコマンドを実行して、keyvault に対する適切な secret get アクセス ポリシーのアクセス許可をプリンシパルに付与します。

az keyvault set-policy --name $MyKeyvault --secret-permissions get --object-id $MyPrincipalID

acrtransfer Az CLI 拡張機能を使用して ImportPipeline を作成する

acrtransfer Az CLI 拡張機能を使用して、ターゲット コンテナー レジストリで ImportPipeline リソースを作成します。 既定では、アタッチされたストレージ アカウント コンテナーで新しい成果物 BLOB が受信されたときに Import PipelineRun が自動的に作成されるように、パイプラインが有効化されます。

オプションを使用せず、システム割り当て ID を使用して、インポート パイプラインを作成します。

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer

使用可能なすべてのオプションを使用し、ソーストリガーを無効にし、ユーザー割り当て ID を使用してインポート パイプラインを作成します。

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--options DeleteSourceBlobOnSuccess OverwriteTags ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity \
--source-trigger-enabled False

インポート オプション

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

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

ImportPipeline ID に keyvault ポリシー アクセスを付与する

ユーザー割り当て ID を使用してパイプラインを作成した場合は、このユーザー割り当て ID に、keyvault に対する secret get アクセス ポリシーのアクセス許可を付与するだけです。

システム割り当て ID を使用してパイプラインを作成した場合は、まず、お使いのパイプライン リソースにシステムによって割り当てられた principalId を取得する必要があります。

パイプライン リソースを取得するには、次のコマンドを実行します。

az acr import-pipeline show --resource-group $MyRG --registry $MyReg --name $MyPipeline

この出力から、principalId フィールドの値をコピーします。

次に、次のコマンドを実行して、keyvault に対する適切な secret get アクセス ポリシーをプリンシパルに付与します。

az keyvault set-policy --name $MyKeyvault --secret-permissions get --object-id $MyPrincipalID

acrtransfer Az CLI 拡張機能を使用してエクスポート用の PipelineRun を作成する

acrtransfer Az CLI 拡張機能を使用してコンテナー レジストリ用の PipelineRun リソースを作成します。 このリソースでは、前に作成した ExportPipeline リソースが実行され、指定された成果物が BLOB としてコンテナー レジストリからソース ストレージ アカウントにエクスポートされます。

エクスポート パイプライン実行を作成します。

az acr pipeline-run create \
--resource-group $MyRG \
--registry $MyReg \
--pipeline $MyPipeline \
--name $MyPipelineRun \
--pipeline-type export \
--storage-blob $MyBlob \
--artifacts hello-world:latest hello-world@sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042 \
--force-redeploy

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

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

az storage blob list --account-name $MyStorageAccount --container $MyContainer --output table

ドメイン間で BLOB を転送する

ほとんどのユースケースでは、クロス ドメイン ソリューションまたはその他の方法を使用して、ソース ドメイン内のストレージ アカウント (エクスポート パイプラインに関連付けられたストレージ アカウント) からターゲット ドメイン内のストレージ アカウント (インポート パイプラインに関連付けられたストレージ アカウント) に BLOB を転送するようになりました。 現時点では、BLOB は、インポート パイプラインに関連付けられたターゲット ドメイン ストレージ アカウント内に到着したと想定します。

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

インポート パイプラインの作成時に --source-trigger-enabled False パラメーターを使用しなかった場合、パイプラインは、BLOB がストレージ アカウント コンテナー内に到着後 15 分以内にトリガーされます。 成果物のインポートには数分かかることがあります。 インポートが正常に完了したら、ターゲット コンテナー レジストリにインポートしているリポジトリ上のタグを一覧表示して、成果物のインポートを確認します。 たとえば、az acr repository show-tagsを実行します。

az acr repository show-tags --name $MyRegistry --repository $MyRepository

Note

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

ImportPipeline の作成時に --source-trigger-enabled False パラメーターを使用した場合は、次のセクションで示すように、PipelineRun を手動で作成する必要があります。

acrtransfer Az CLI 拡張機能を使用してインポート用の PipelineRun を作成する

acrtransfer Az CLI 拡張機能を使用してコンテナー レジストリ用の PipelineRun リソースを作成します。 このリソースでは、以前に作成した ImportPipeline リソースを実行し、指定された BLOB をストレージ アカウントからコンテナー レジストリにインポートします。

インポート パイプライン実行を作成します。

az acr pipeline-run create \
--resource-group $MyRG \
--registry $MyReg \
--pipeline $MyPipeline \
--name $MyPipelineRun \
--pipeline-type import \
--storage-blob $MyBlob \
--force-redeploy

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

成果物のインポートには数分かかることがあります。 インポートが正常に完了したら、ターゲット コンテナー レジストリにリポジトリを一覧表示して、成果物のインポートを確認します。 たとえば、az acr repository show-tagsを実行します。

az acr repository show-tags --name $MyRegistry --repository $MyRepository

ACR 転送リソースを削除する

ExportPipeline を削除します。

az acr export-pipeline delete --resource-group $MyRG --registry $MyReg --name $MyPipeline

ImportPipeline を削除します。

az acr import-pipeline delete --resource-group $MyRG --registry $MyReg --name $MyPipeline

PipelineRun リソースを削除します。 これは、PipelineRun によって実行されたアクションを元に戻さないことに注意してください。 これは、PipelineRun のログの削除によく似ています。

az acr pipeline-run delete --resource-group $MyRG --registry $MyReg --name $MyPipelineRun

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

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

次のステップ

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